Phase 13: Tools & Protocols

कौशल का पता लगाना और प्रगतिशील प्रकटीकरण

एक कौशल अपने शरीर को लोड करने से पहले उपयोगी हो जाता है। इसका नाम और विवरण कैटलॉग में जगह कमाता है; इसकी गहरी फाइलें केवल तभी संदर्भ प्राप्त करती हैं जब कार्य उन्हें प्राप्त होता है।

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 13 · 22 (Agent Skills: Portable Contract and Runtime Boundary)

Time: ~105 minutes

सीखने के लक्ष्य

फ़ाइल सिस्टम डिस्कवरी पाइपलाइन का निर्माण करें जो दायरा, सत्यापन, टकराव नीति और कैटलॉग प्रकाशन को अलग करता है।
खुलासा के तीन स्तरों को समझाएंः कैटलॉग मेटाडेटा, सक्रिय निर्देश और कार्य-विशिष्ट संसाधन।
डिज़ाइन संदर्भ ताकि एजेंट पूरे पैकेज को लोड किए बिना आवश्यक विवरण तक सीधे पहुंच सके।
सक्रिय कौशल संदर्भ से स्वतंत्र रूप से बजट कैटलॉग स्थान।
पथ पार करने और सिम्लिंक से बचने के लिए जब एक कौशल अपने स्वयं के संसाधनों को पढ़ता है।

समस्या

आपके एजेंट 200 स्थापित कौशल है.SKILL.md, संदर्भ फ़ाइल, स्क्रिप्ट, और टेम्पलेट सत्र की शुरुआत में वर्तमान कार्य को संबंधित प्रक्रिया में दफन कर देगा। कुछ भी लोड करने से उपयोगकर्ता को फ़ाइल सिस्टम के सटीक पथ याद रखने के लिए मजबूर होगा।

सामान्य समझौता एक सूची है: प्रत्येक पात्र कौशल के लिए मॉडल को एक कॉम्पैक्ट पहचान और रूटिंग विवरण दिखाएं, फिर चयन के बाद ही पूरे शरीर को लोड करें। यह दो नई इंजीनियरिंग समस्याएं पैदा करता है।

सबसे पहले, खोज केवल पुनरावर्ती फ़ाइल खोज नहीं है। कौशल परियोजना, उपयोगकर्ता, व्यवस्थापक, प्लगइन या अंतर्निहित स्कोप पर मौजूद हो सकते हैं। दो पैकेज एक नाम साझा कर सकते हैं। एक सिम्लिंक विश्वसनीय जड़ के बाहर इंगित कर सकता है। एक गलत पैकेज कैटलॉग स्थान का उपभोग कर सकता है या इसे कॉल करना असंभव हो सकता है।

दूसरा, प्रगतिशील प्रकटीकरण प्रगतिशील भ्रम में बदल सकता है।SKILL.md"संदर्भ में गाइड पढ़ें" और पैकेज में बारह गाइड हैं, मॉडल को अनुमान लगाना चाहिए। यदि प्रत्येक गाइड तीन और फ़ाइलों को इंगित करता है, तो लोडिंग एक अनलिमिटेड ग्राफ चाल बन जाता है।

अच्छा रनटाइम खोज को निर्धारक और खुलासा को जानबूझकर बनाता है।

अवधारणा

डिस्कवरी एक संकलक पाइपलाइन है

फ़ाइल प्रणाली को स्रोत इनपुट के रूप में व्यवहार करें। कच्चे पथ सीधे मॉडल में प्रकाशित न करें।

प्रत्येक चरण में संरचित डेटा और संरचित विफलताएं उत्पन्न होनी चाहिए। एक खोज लॉग का उत्तर देना चाहिएः

किस मूल की खोज की गई?
कौन-कौन से उम्मीदवार मिले?
किस उम्मीदवार को खारिज कर दिया गया था और क्यों?
किस पैकेज ने टक्कर जीती?
बजट के कारण कौन सी सूची प्रविष्टियों को छोटा या छोड़ दिया गया था?

इस सबूत के बिना, "मॉडल ने मेरी कौशल का उपयोग नहीं किया" निदान करना लगभग असंभव है।

कार्यक्षेत्र रिनटाइम नीति है

पोर्टेबल विनिर्देश एक कौशल पैकेज को परिभाषित करता है, एक सार्वभौमिक स्थापना पथ या प्राथमिकता क्रम नहीं। होस्ट यह तय करता है कि वह कहां खोजता है।

एक सामान्य रनटाइम इन स्कोप का उपयोग कर सकता हैः

Scope	Example root	Intended ownership
Workspace	`<repo>/.agents/skills/`	Project maintainers
User	`<user-data>/skills/`	One developer
Administrator	`<system>/skills/`	Machine or organization policy
Plugin	A signed plugin bundle	Plugin publisher and installer
Built-in	Runtime package	Runtime vendor

अगस्त 2026 तक, कोडेक्स परियोजना की खोज के दस्तावेज $CWD/.agents/skillsपूर्वजों की निर्देशिकाओं के माध्यम से रिपॉजिटरी रूट तक, प्लस उपयोगकर्ता, व्यवस्थापक और अंतर्निहित स्थान। यह समलिंकित कौशल निर्देशिकाओं का समर्थन करता है। डुप्लिकेट नाम दोनों को विलय होने के बजाय दिखाई दे सकते हैं। ये कोडक्स व्यवहार हैं, न कि आवश्यकताएं SKILL.md; वर्तमान की जांच करें Codex skill documentationएक एडाप्टर लिखने के दौरान।

निर्देशिका नामों से कभी प्राथमिकता का आविष्कार न करें। इसे नीति के रूप में घोषित करें और इसका परीक्षण करें। पाठ प्रयोगशाला प्रत्येक के लिए स्पष्ट पूर्णांक रैंक का उपयोग करती हैScopeतो एक ही उम्मीदवार सेट हमेशा एक ही तरीके से हल करता है।

टकरावों को पहचान से परे की आवश्यकता होती है `name`

दो पैकेज नामित release-readinessएक कार्यक्षेत्र ओवरराइड हो सकता है और एक उपयोगकर्ता डिफ़ॉल्ट हो सकता है। इसलिए एक कैटलॉग प्रविष्टि को कम से कम आवश्यकता होती हैः

json{
  "name": "release-readiness",
  "description": "Inspect a release candidate for this repository.",
  "scope": "workspace",
  "source": "/repo/.agents/skills/release-readiness",
  "selected": true
}

आम टकराव नीति में शामिल हैंः

Policy	Benefit	Risk
Keep every candidate	Nothing is hidden	The model sees ambiguous names
Highest-precedence scope wins	Simple invocation	A local package can shadow a trusted one
Reject duplicates	No silent shadowing	Legitimate overrides stop working
Qualify names by source	Explicit identity	User-facing names become longer

मेजबान के लिए एक नीति चुनें। अस्वीकृत या छायांकित उम्मीदवारों को डायग्नोस्टिक्स में बनाए रखें, भले ही वे मॉडल कैटलॉग में अनुपस्थित हों।

तीन खुलासा स्तर

एजेंट कौशल विनिर्देश चरण लोड का वर्णन करता है। कुंजी यह है कि प्रत्येक स्तर का एक अलग उद्देश्य है।

#### स्तर 1: कैटलॉग मेटाडेटा

मॉडल को पड़ोसी कौशल से अलग करने के लिए पर्याप्त जानकारी की आवश्यकता होती है। विनिर्देश का अनुमान है कि कैटलॉग प्रविष्टि के लिए लगभग 100 टोकन हैं, लेकिन वास्तविक क्रमबद्धता और टोकनकरण मेजबान के लिए है।

एक उपयोगी विवरण में दो खंड होते हैंः

yamldescription: Validate a release candidate and produce a readiness report. Use when the user asks whether a version, tag, or package is ready to publish.

पहला खंड क्षमता का उल्लेख करता है, दूसरा ट्रिगर सीमा का उल्लेख करता है। पाठ 25 इस सीमा का मूल्यांकन सकारात्मक और लगभग चूक संकेतों के साथ करता है।

#### स्तर 2: सक्रिय निर्देश

सक्रियण के बाद, शरीर को एक नक्शा और प्रक्रिया के रूप में कार्य करना चाहिए।SKILL.md500 लाइनों से नीचे। यह एक डिजाइन संकेत है, एक लक्ष्य को भरने के लिए नहीं।

शरीर में निम्नलिखित सामग्री होनी चाहिएः

कार्य सीमा;
डिफ़ॉल्ट वर्कफ़्लो;
शाखा की शर्तें;
गहन फ़ाइलों के लिए प्रत्यक्ष संदर्भ;
उपकरण और स्क्रिप्ट अनुबंध;
विफलता और रोकना व्यवहार;
अपेक्षित उत्पादन और इसकी सत्यापन।

केवल प्रविष्टि फ़ाइल को छोटा करने के लिए केंद्रीय कार्यप्रवाह को संदर्भ में न ले जाएं। सक्रियण को मॉडल को सही ढंग से शुरू करने के लिए पर्याप्त संदर्भ देना चाहिए।

#### स्तर 3: सहायता संसाधन

संदर्भ प्रोज या डेटा प्रदान करते हैं। स्क्रिप्ट निर्धारात्मक गणना प्रदान करते हैं। परिसंपत्तियों को निर्देशों के रूप में इलाज किए जाने के बजाय प्रतिलिपि, भरने या डिलीवरी में परिवर्तित किया जाता है।

Directory	Model reads it?	Model executes it?	Typical content
`references/`	Yes, when needed	No	schemas, policies, domain guides
`scripts/`	May inspect it	Through a permitted tool	validators, converters, collectors
`assets/`	Only if useful	No	templates, fixtures, images, starter files

ये नाम कन्वेंशन हैं, जादू की क्षमताओं नहीं. होस्ट को अभी भी फ़ाइल एक्सेस और निष्पादन उपकरण की आवश्यकता है।

विषयों के डंप से शाखा-विशिष्ट संदर्भ बेहतर होते हैं

प्रविष्टि फ़ाइल को निर्णय मानचित्र के रूप में लिखेंः

markdown## Choose the path

- For a Python package, read `references/python-release.md`.
- For a container image, read `references/container-release.md`.
- For a documentation-only release, read `references/docs-release.md`.
- If the release combines artifact types, read only the guides for those artifacts.

यह प्रत्येक संदर्भ को एक अवलोकन योग्य लोड स्थिति देता है।references/अधिक के लिए नहीं है।

संदर्भ ग्राफ को संक्षिप्त रखें। आधिकारिक मार्गदर्शन में सीधे लिंक की सिफारिश की जाती हैSKILL.mdएक कूदने से पहुंच परीक्षण योग्य हो जाती है और यह संभावना कम हो जाती है कि आवश्यक प्रतिबंध कभी भी संदर्भ में प्रवेश नहीं करता है।

कैटलॉग बजट और सक्रिय संदर्भ अलग-अलग बजट हैं

चलोc_iकौशल की सीरियल कैटलॉग लागत हो i,B_cकैटलॉग बजट, b_jसक्रिय शरीर की लागत, तथा r_kसंसाधनों को वास्तव में लोड किया गया।

textcatalog_cost = sum(c_i for every published skill)
active_cost = sum(b_j for every activated skill) + sum(r_k for every disclosed resource)

एक बजट को कम करने से स्वचालित रूप से दूसरा कम नहीं होता है। संक्षिप्त विवरण कैटलॉग स्थान को बचा सकते हैं जबकि सक्रिय 900 लाइनों का निकाय अभी भी कार्य को भारी बनाता है। संदर्भों में निकाय को विभाजित करने से सक्रिय लागत को कम किया जा सकता है जब रनटाइम और निर्देश वास्तव में अप्रासंगिक शाखाओं को लोड करने से बचते हैं।

वर्तमान में कोडेक्स प्रारंभिक कौशल सूची को संदर्भ के 2% पर बजट करता है

विंडो जब संदर्भ विंडो आकार ज्ञात है। 8,000 वर्ण मूल्य एक है

केवल जब यह आकार अज्ञात हो; यह एक दूसरे कैप के साथ संयुक्त नहीं है

2 प्रतिशत नियम। जब सूची लागू बजट से अधिक हो,

विवरणों को छोटा या छोड़ दिया जा सकता है।

कोड नीति, एजेंट कौशल मानक की संपत्ति नहीं है।

संसाधन पथ एक विश्वास सीमा है

एक कौशल को केवल अपने पैकेज के अंदर फ़ाइलों को पढ़ना चाहिए। शाब्दिक स्ट्रिंग-प्रिफिक्स जांच पर्याप्त नहीं हैंः

textreferences/../../../../.ssh/config
references/external-link -> /private/company-secrets

फ़ाइल सिस्टम सेमेटिक के साथ पैकेज रूट और उम्मीदवार को हल करें, पूर्ण इनपुट को अस्वीकार करें, और सत्यापित करें कि हल किया गया उम्मीदवार हल किया गया रूट के तहत रहता है। पता लगाने से पहले यह तय करें कि क्या सिम्लिंक्स की अनुमति है। यदि अनुमति है, तो हर बार हल किए गए लक्ष्य की जांच करें।

पथ को रोकना सामग्री का विश्वास स्थापित नहीं करता है। एक वैध पैकेज में संदर्भ अभी भी दुर्भावनापूर्ण निर्देशों को शामिल कर सकता है। पाठ 26 इस खतरे को संभालता है।

लोड होने का अवलोकन किया जाना चाहिए

गुप्त रिकॉर्डिंग के बिना खुलासा की घटनाओं को रिकॉर्ड करेंः

json{
  "event": "skill.resource.loaded",
  "skill": "release-readiness",
  "resource": "references/python-release.md",
  "reason": "candidate contains pyproject.toml",
  "bytes": 2840
}

इसका कारण संदर्भ विकल्प को समीक्षा योग्य साक्ष्य में बदल देता है। यह निर्देशों की पहचान करने में भी मदद करता है जो एजेंट को हर फ़ाइल को "केवल मामले में" लोड करने के लिए प्रेरित करते हैं।

इसे बनाओ

code/main.pyएक निर्धारात्मक खोज और प्रकटीकरण इंजन बनाता है।

खोज सतह में शामिल हैंः

Scopeस्रोत और प्राथमिकता मेटाडेटा के लिए;
SkillCandidateएक अप्रमाणित फाइल सिस्टम उम्मीदवार के लिए;
discover_scope(scope)तत्काल कौशल निर्देशिकाओं को सूचीबद्ध करना;
resolve_collisions(candidates, precedence)एक घोषित नीति लागू करना;
CatalogEntryऔर build_catalog(...)सीमित मेटाडेटा प्रकाशित करना;
CatalogBudgetबिना अक्षरों का दिखावा किए क्रमबद्ध प्रविष्टियों को खाता बनाना सार्वभौमिक टोकन हैं।

खुलासा सतह में शामिल हैंः

load_skill_body(entry, ...)स्तर 2 सक्रियण के लिए;
validate_reference(skill_dir, reference)मार्ग पर रोक लगाने के लिए;
load_reference(...)सीमांकित स्तर 3 के लिए।

प्रयोगशाला चलाओ:

bashcd "$(git rev-parse --show-toplevel)"
cd phases/13-tools-and-protocols/24-skill-discovery-and-progressive-disclosure
python3 code/main.py
python3 -m unittest discover -s code/tests -v

इस ब्लॉक को स्थानीय क्लोन की आवश्यकता होती है और किसी भी से रिपॉजिटरी रूट को हल करता है

उस क्लोन के अंदर काम कर निर्देशिका.

डेमो अस्थायी परियोजना और उपयोगकर्ता स्कोप बनाता है, एक टकराव डालता है, एक जानबूझकर छोटे बजट के तहत एक कैटलॉग बनाता है, एक कौशल को सक्रिय करता है, और एक मान्य संदर्भ रीड और एक पारगमन भागने दोनों का प्रयास करता है। कोई स्थायी फ़ाइलें स्थापित नहीं की जाती हैं।

क्यों खोज क्षैतिज है

discover_scope के लिए तत्काल बच्चे निर्देशिकाओं की जांच करता हैSKILL.md. यह प्रत्येक घोंसले को पुनरावर्ती रूप से इलाज नहीं करता है .SKILL.mdयह पैकेज की सीमा को संरक्षित करता है और स्थापित कौशल के अंदर गलती से उदाहरण या फिटिंग प्रकाशित करने से बचाता है।

प्रयोगशाला मनमानी यैमएल का विश्लेषण क्यों नहीं करती

प्रयोगशाला अपनी कैटलॉग के लिए आवश्यक स्केलर फ्रंटमैटर का समर्थन करती है। एक उत्पादन रनटाइम को स्पष्ट योजना, आकार सीमाओं और अक्षम कस्टम ऑब्जेक्ट निर्माण के साथ एक सुरक्षित YAML पार्सर का उपयोग करना चाहिए। "Stdlib-only" एक शिक्षण प्रतिबंध है, चुपचाप आंशिक YAML बोली का आविष्कार करने की अनुमति नहीं है।

इसका प्रयोग करें

इस चेकलिस्ट को किसी भी डिस्कवरी एडाप्टर पर लागू करें:

प्रत्येक कॉन्फ़िगर की गई रूट और उस पर कौन लिख सकता है, उसे सूचीबद्ध करें।
बताएं कि क्या समलिंकित पैकेज की अनुमति है।
पैकेज नाम, निर्देशिका नाम, आवश्यक मेटाडेटा और प्रविष्टि-शरीर आकार को मान्य करें।
आंतरिक पहचान में स्रोत और दायरा को संरक्षित करना।
दोहरी-नाम व्यवहार की घोषणा और परीक्षण करें।
मॉडल को भेजे गए सटीक क्रमबद्ध सूची को मापें।
किसी शरीर या संसाधन को क्यों लोड किया गया था, इसका रिकॉर्ड करें।
समाधान पैकेज रूट के अंदर संसाधन रीड्स रखें।
संदर्भित फ़ाइल गायब होने पर स्पष्ट रूप से विफलता।
स्थापना या नीति में परिवर्तन होने पर सूची को पुनर्निर्माण करें।

इसे भेजें

यह सबक skill-catalog-builderबंडल. यह स्पष्ट रूप से क्रमबद्ध जड़ों को स्कैन करता है, समलिंकित प्रविष्टि फ़ाइलों और नाम-निर्देशिका असंगतताओं को अस्वीकार करता है, क्रॉस-स्कोप टकरावों को हल करता है, समान पूर्ववर्ती डुप्लिकेट को अस्वीकार करता है, और चयनित मेटाडेटा को घोषित प्रविष्टि, विवरण और धारावाहिक वर्ण बजट में फिट करता है।

इसकी JSON रिपोर्ट में चयनित प्रविष्टियां, छायांकित उम्मीदवार, छोड़ दिए गए प्रविष्टियां, सत्यापन त्रुटियां, प्राथमिकता और बजट उपयोग शामिल हैं। बॉडी और संदर्भ लोडिंग अलग-अलग रनटाइम ऑपरेशन बने रहते हैं, इसलिए कैटलॉग बिल्डर स्क्रिप्ट निष्पादित नहीं करता है या पूरे पैकेज को संदर्भ में नहीं देता है।

व्यायाम

एक प्लगइन दायरा जोड़ें और इसे उपयोगकर्ता और अंतर्निहित प्राथमिकता के बीच रखें। एक परीक्षण के साथ टक्कर परिणाम साबित करें।
टक्कर नीति को उच्चतम प्राथमिकता से योग्य नामों में बदलें। सूची में दोनों प्रविष्टियों को संरक्षित रखें।
पर बाइट आकार सीमा जोड़ेंload_reference. एक फ़ाइल को सीमा पर और एक बाइट ऊपर से ठीक परीक्षण करें.
दो ऐसे वर्णनात्मक शब्द बनाएं जो लगभग समान लगें। उन्हें फिर से लिखें ताकि ट्रिगर सीमाएं ओवरलैप न हों।
प्रत्येक संदर्भ और स्क्रिप्ट के लिए हैश युक्त एक मैनिफेस्ट जोड़ें. इसे लोड करने से पहले एक संशोधित संसाधन का पता लगाएं.
स्तर 1, स्तर 2, और स्तर 3 बाइट अलग से गिनती रिपोर्ट करने के लिए प्रदर्शन उपकरण।

प्रमुख शर्तें

Term	What people say	What it actually means
Skill discovery	"Find every SKILL.md"	Search configured scopes, validate packages, attach provenance, and apply policy
Skill catalog	"The list of installed skills"	Compact model-visible routing metadata for eligible packages
Collision policy	"Which duplicate wins"	A declared rule for same-name candidates from different sources
Progressive disclosure	"Lazy loading"	Staged context admission from catalog to body to branch-specific resources
Reference graph	"Files linked by the skill"	The reachable resource structure and its load conditions
Path containment	"Stay in the folder"	Verify resolved resource targets remain inside the resolved package root

आगे पढ़ना

Agent Skills specificationपैकेज के आकार और प्रगतिशील प्रकटीकरण स्तर के लिए।
Optimizing skill descriptionsकैटलॉग रूटिंग मेटाडेटा के लिए।
Agent Skills best practicesप्रत्यक्ष संदर्भ और प्रविष्टि फ़ाइल आकार के लिए।
OpenAI: Build skillsवर्तमान कोडेक्स खोज दायरे और कैटलॉग सीमाओं के लिए।

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.