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 خط زیر. اين يه سيگنال طراحیيه، نه يه هدف براي پر کردن

بدن باید حاوی:

مرز وظایف
جریان کار پیش فرض
شرایط شاخه؛
مرجع مستقیم به پرونده های عمیق تر؛
قراردادهای ابزار و اسکریپت
رفتارهای شکست و توقف؛
تولید انتظار می رود و تأیید آن.

جریان کار مرکزی را به یک مرجع منتقل نکنید فقط برای کوتاه کردن فایل ورودی. فعال سازی باید به مدل زمینه کافی برای شروع صحیح بدهد.

#### سطح سوم: منابع حمایت

مرجع ها پروز یا داده ها را فراهم می کنند. اسکریپت ها محاسبات تعیین کننده ای را فراهم می کنند. دارایی ها به جای دستورالعمل ها به عنوان داده های تحویل داده شده کپی، پر شده یا تبدیل می شوند.

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 درصد از زمینه ها می پردازد

پنجره ای که اندازه پنجره متن شناخته شده است.

بازپسین تنها زمانی که این اندازه ناشناخته باشد؛ این یک کلاه دوم همراه با

قانون 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 را تعسفی تجزیه نمی کند

آزمایشگاه از ماده مقدماتی مقیاس مورد نیاز برای کاتالوگ خود پشتیبانی می کند. یک زمان اجرا تولید باید از یک پارسر YAML ایمن با یک طرح صریح، محدودیت اندازه و غیر فعال ساختن اشیاء سفارشی استفاده کند. "Stdlib-only" یک محدودیت آموزشی است، نه اجازه اختراع یک گویش یامل جزئی به طور خاموش.

ازش استفاده کن

این چک لیست را به هر آداپتور کشف اعمال کنید:

هر ریشه تنظیم شده و چه کسی می تواند به آن بنویسد را لیست کنید.
مشخص کنید که آیا بسته های متناظر مجاز هستند یا خیر.
نام بسته، نام دایرکتوری، متاداتا مورد نیاز و اندازه ورودی را تایید کنید.
حفظ منبع و دامنه در هویت داخلی.
اعلام و آزمایش رفتار نام تکراری
کتالوگ سریالیز شده دقیق را که به مدل فرستاده شده است اندازه گیری کنید.
دلیل بارگذاری یک بدن یا منبع را ثبت کنید.
در داخل ریشه بسته حل شده، خواندن منابع را حفظ کنید.
وقتی یک فایل مرجع داده گم شده، به وضوح شکست می خورد.
وقتی نصب ها یا سیاست ها تغییر می کنند، کاتالوگ را بازسازی کنید.

-باده

این درس باعث می شه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.