Phase 13: Tools & Protocols

مهارت های فراخوان و راه اندازی

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

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 13 · 24 (Skill Discovery and Progressive Disclosure)

Time: ~105 minutes

اهداف یادگیری

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

مشکل

شما نصب کنيدdatabase-migrationمهارت. کاربر می تواند آن را با نام اجرا کند، اما مدل همچنین توصیف آن را می بیند و آن را هنگامی که کسی یک سوال پایگاه داده عمومی را پرسد انتخاب می کند. مهارت سپس تغییر اسکیما را برای یک کار پیشنهاد می کند که فقط نیاز به توضیح دارد.

تو اضافه می کنیuser-invocable: falseدر زمان اجرا دیگر، این میدان نادیده گرفته می شود.disable-model-invocation: trueدر زمان اجرا که آن را درک می کند، کاربر هنوز هم می تواند به طور صریح به آن مراجعه کند.

هیچ مشکلی با نام های زمینه وجود ندارد. مدل اشتباه است. "استفاده کننده می تواند آن را ببیند،" "نموذج می تواند آن را انتخاب کند،" "برنامه می تواند آن را پیش بارگذاری کند،" و "وسائل درون آن می تواند اجرا" حقایق جداگانه هستند. یک واحد boolean نامیده می شود invocableنمیتونه بیانش کنه

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

مفهوم

پنج کانال می توانند چرخه زندگی را آغاز کنند

Actor	Invocation shape	Typical use	Main risk
Human user	Names a skill in the UI or prompt	Deliberate workflow selection	User expects availability or authority the host does not grant
Model or autonomous agent	Selects a catalog entry from task context	Automatic expert procedure	False-positive routing
Application	Activates or preloads a skill through runtime code	Fixed product workflow	Hidden coupling to one host
Another skill or subagent	Requests an exact skill as a workflow dependency	Composition	Cycles, missing dependency, or context bleed
Evaluation harness	Activates an exact skill under a fixed scenario	Repeatable measurement	Tests the skill while accidentally bypassing the production policy under study

مشخصات قابل حمل مهارت های عامل بسته را تعریف می کند. این یک UI فرمان سلش جهانی، پرچم روتینگ ضمنی، API برنامه یا چرخه زندگی زیرکارت را استاندارد نمی کند.

پنج مرحله دعوت

اين کلمات رو درست استفاده کن:

Eligibleیعنی سیاست اجازه می دهد این بازیگر مهارت را درخواست کند.
Selectedیعنی کاربر آن را نام داده است یا روتر آن را مربوطه دانست.
Activatedاین مطلب را به معنای ورود دستورالعمل های آن به زمینه کاری می باشد.
Executingیعنی که عامل با این دستورالعمل ها شروع به کار روی مدل یا ابزار کرد.
Completedیعنی محصول به یک بررسی موفقیت مستقل رسید.

يه رد که فقط ثبت ميکنهskill_used=trueمرز جایی که شکست اتفاق افتاده را پنهان می کند.

درخواست های انسانی و مدل ها یک ماتریس 2×2 را تشکیل می دهند

Human can invoke	Model can invoke	Mode	Suitable examples
Yes	Yes	Shared	Code explanation, test planning, documentation review
Yes	No	Human-only	Publish preparation, billing export, destructive cleanup plan
No	Yes	Model-only	Internal style guide, domain reference, automatic support procedure
No	No	Disabled or application-only	Staged rollout, deprecated package, programmatic preload

ماتریکس یک مدل سیاست است نه YAML استاندارد.

یک میزبان فعلی استفاده می کندdisable-model-invocation: trueبرای خط تنها انسان وuser-invocable: falseبرای خط فقط مدل. پیش فرض هر دو است. میزبان دیگری استفاده می کند agents/openai.yamlباallow_implicit_invocation: falseبرای حفظ دعوت صریح در حالی که غیر فعال کردن انتخاب ضمنی. این ها آداپتورهای زمان اجرا هستند. میزبان نامعلوم ممکن است آنها را نادیده بگیرند.

جزئیات گیج کننده مهمه:user-invocable: falseاین به معنای "نموذج نمی تواند از این استفاده کند". این تماس مستقیم کاربر را در میزبان که آن را تعریف می کند حذف می کند. disable-model-invocation: trueاین به معنای "مهارت غیرفعال شده است". این گزینه انتخاب مدل را حذف می کند و در عین حال دسترسی صریح کاربر را حفظ می کند.

دعوت صریح اول هویت است

یک دعوت صریح به طور مستقیم هویت را فراهم می کند:

text/release-readiness v2.4.0

یا:

textrelease-readiness check v2.4.0 without publishing

سند رابط های کنونی کدکس /skillsبرای انتخاب و نام های مهارت ساده در درخواست های درخواست صریح./skill-nameو گسترش منطق مخصوص میزبان. ترکیب دقیق، دید مینو، قوانین نقل قول و گسترش متغیر متعلق به میزبان است.

یک درخواست صریح هنوز سیاست را تصویب می کند. نامگذاری یک مهارت نباید از مجوزهای گمشده، محدودیت های فضای کار، دروازه های تأیید یا تعزیر زمان اجرا دور شود.

دعوت ضمنی اول توصیف است

برای رویت ضمنی، مدل ابتدا متاداتا کاتالوگ را به جای کل بدن می بیند. بنابراین توصیف رابط رویت مهارت است.

ضعیف:

yamldescription: Helps with releases.

بیش از حد گسترده:

yamldescription: Use for release, version, package, build, deploy, publish, tag, changelog, GitHub, CI, or software tasks.

محدود:

yamldescription: Inspect an already prepared release candidate and produce a readiness report. Use when the user asks whether a version, tag, package, or image is ready to publish; do not use for ordinary build failures or feature development.

نسخه محدود شامل:

Capability:یک کاندیدای آماده را بررسی کنید.
Output:گزارش آماده بودن
Positive boundary:ازش ميپرسي که آيا يه اثر تخليه آماده است
Negative boundary:ساخت و ساز و توسعه معمول از محدوده خارج است.

مرزهای منفی زمانی مفید هستند که دو مهارت نزدیک به هم لغت مشترک داشته باشند. آنها جایگزین ارزیابی های نزدیک به اشتباه نیستند.

رویتینگ طبقه بندی با گزینه خودداری است

براي مهارتsو درخواستx، نمره روتر رو تصور کنيد:

textscore(s, x) = capability_match + trigger_match + context_match - exclusion_match - ambiguity_penalty

امتیاز دقیق ممکن است یک تصمیم LLM باشد نه ریاضی. اصل مهندسی هنوز هم برقرار است: انتخاب باید از یک حد و مهارت رقابتی عبور کند. هنگامی که شواهد ضعیف است، خود را از خودداری کنید.

برای مهارت های با تاثیر بالا، مسیر ضمنی حتی با یک توصیف قوی ممکن است نامناسب باشد. فقط از سیاست های انسانی استفاده کنید زمانی که هزینه مثبت دروغین از راحتی انتخاب خودکار فراتر رود.

واجد شرایط بودن باید قبل از رتبه بندی باشد

هر مهارت کشف شده را نمایه ندهید، قوی ترین مسابقه را انتخاب کنید و بعد از آن سیاست یک مهارت را بررسی کنید. یک مسابقه برتر مسدود شده به طور نادرست مانع از بررسی یک کاندیدای واجد شرایط با امتیاز پایین تر می شود.

برای رویت ضمنی از این ترتیب استفاده کنید:

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

فرض کنincident-triageامتیازات0.80اما افزونه میزبانش نداشتن مدل را غیرفعال می کند. incident-reviewامتیازات0.55و اجازه می دهد تا مدل را دعوت کنید. روتر باید ارزیابی کندincident-reviewبه عنوان بهترین نامزد واجد شرایط.incident-triage، انکارش کن و متوقف شو

این ترتیب همچنین تغییرات سیاست را از تغییر معنی نمره مرتبطی جلوگیری می کند. واجد شرایط بودن مجموعه انتخاب را تعریف می کند. رتبه های مرتبط با آن مجموعه.

ارزیابی های مسیر نیاز به نزدیک misses

موارد مثبت ثابت می کنه که به یاد آوردن:

json{"prompt":"Is version 2.4.0 ready to publish?","expected":"release-readiness"}

منفی های واضح دقت اساسی را ثابت می کنند:

json{"prompt":"Explain rotary position embeddings.","expected":null}

قربان شدن ها به وجود آوردن محدودیت ها منجر می شود:

json{"prompt":"Why did today's package build fail?","expected":"build-diagnostics"}

. به پايان هاي نزديکpackageوbuildیک مجموعه مسیر که فقط از مثبت های آشکار و منفی های غیر مرتبط ساخته شده است کیفیت را بیش از حد ارزیابی می کند.

استدلال ها سه تمثیل دارند

یک استدلال دعوت چند مرز را عبور می کند:

در هر مرز، قصد را حفظ کنید بدون اینکه متن را به عنوان کد در نظر بگیرید.

پارسر میزبان دستورات و نقل قول را تعیین می کند.
مهارت متن یا متغیرهای مرتبط را مطابق با قوانین میزبان دریافت می کند.
دستورالعمل ها ارزش های مورد نیاز و معیارهای پیش فرض را تایید می کنند.
یک تماس ابزار، مقادیر را به یک طرح تایپ شده تبدیل می کند و آنها را اعتبار می دهد.

استدلال های خام را به دستورات shell متمایز کنید. اسکریپت را که با یک ویکتور استدلال یا یک ابزار MCP تایپ شده است ترجیح دهید.

درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست درخواست

یک محصول می تواند یک مهارت را فعال کند زیرا جریان کار آن قبلاً نوع کار را می داند. به عنوان مثال، یک سرویس بررسی pull-request می تواند پیش بارگذاری شود pull-request-risk-reviewبعد از اینکه کاربر Review را فشار دهد.

این باعث حذف عدم اطمینان روتینگ می شود اما به API زمان اجرا بستگی ایجاد می کند. آن آداپتور را خارج از بدن قابل حمل نگه دارید:

مهارت باید در زمانی که توسط یک مشتری متعهد دیگر باز شود قابل درک باشد.

دعوت به مهارت ها یک ابزار است

فرض کنrelease-readinessازش میخوادsecurity-change-reviewوقتی فایل های وابستگی تغییر می کنند.

تماس گیرنده باید:

هویت مهارت های هدف؛
مسیرهای محدودی از وظایف و آثار هنری
قرارداد پاسخ انتظار می رود؛
دلیل درخواست؛
اگر در دسترس نباشد، بازپسین؛
یک قانون عمق یا چرخه حداکثر.

json{
  "target_skill": "security-change-review",
  "task": "Review dependency changes in the candidate diff",
  "inputs": ["artifacts/release.diff"],
  "expected": "risk-report.json",
  "max_depth": 2
}

مهارت دوم به طور نابینا به اولین مهارت پیوند نمی شود. میزبان تصمیم می گیرد که چگونه آن را فعال کند و آیا آن را به اشتراک می گذارد، در یک شکنی اجرا می کند یا از طریق یک نتیجه ابزار باز می گردد.

چرخه زندگی زمینه مخصوص میزبان است

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

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

markdownOn resume, read `artifacts/release-readiness.json` if it exists.
Revalidate the candidate commit before continuing.
Do not repeat an external write whose idempotency key is already recorded.

آن را بسازید

code/main.pyسیاست ها و مسیرها را به عنوان آداپتورهای جداگانه اجرا می کند.

این مدل شامل:

Actorبرای تماس گیرندگان انسانی، مدل، عامل مستقل، کاربرد، مهارت و استفاده از استفاده از ابزار؛
SkillMetadataبرای هویت مسیر؛
InvocationPolicyبرای ماتریس انسان/نمونه
InvocationRequestوInvocationDecisionبرای ورودی و نتایج قابل ردیابی؛
CorePolicyAdapterبرای رفتار قابل حمل بدون تمدید میزبان؛
ExtensionPolicyAdapterبرای زمینه های زمان اجرا شناخته شده؛
build_invocation_matrix(policy)برای نمایش 2×2؛
route_request(skills, request, adapter)برای فیلتر واجد شرایطی قبل از رتبه بندی، انتخاب و انکار اهمیت.

اجرا کن

bashcd phases/13-tools-and-protocols/25-skill-invocation-and-routing
python3 code/main.py
python3 -m unittest discover -s code/tests -v

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

چرا آداپتورهای هسته ای و افزونه ای جدا هستند

اگر یک تجزیه کننده به هر میدان مشاهده شده فرنت ماتر معنی اختصاص دهد، به طور خاموش کنوانسیون های زمان اجرا را به یک استاندارد جعلی تبدیل می کند. آداپتورهای جداگانه به تماس گیرنده مجبور می کنند نامگذاری کند که سیمانیک میزبان فعال است.

.CorePolicyAdapterفقط از سیاست های ارائه شده توسط درخواست استفاده می کند.ExtensionPolicyAdapterیک مجموعه صریح از زمینه های میزبان و سوابق را که در آن زمینه تصمیم را تغییر داده است، تشخیص می دهد.

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

قبل از انتشار مهارت، یک قرارداد دعوت نامه بنویسید:

yamlactors:
  human: allow
  model: deny
  application: allow
  skill: deny
explicit_name: release-readiness
arguments:
  candidate: required
  publish: fixed_false
ambiguity: ask_user
missing_dependency: stop
context:
  durable_state: artifacts/release-readiness.json
  max_composition_depth: 2

این قرارداد اسناد طراحی برای آداپتورها و آزمایشات است.SKILL.mdموضوع اصلی، مگر اینکه یک استاندارد به صراحت آن را تصویب کند.

-باده

این درس باعث می شهskill-invocation-routerاین شامل یک مرجع مدل دعوت، یک سیاست میزبان مثال و یک CLI غیر اجرا کننده است که یک انسان، مدل، عامل مستقل، برنامه، ترکیب مهارت یا درخواست استفاده را ارزیابی می کند و یک تصمیم JSON را با کانال، آداپتور، امتیاز و دلیل باز می گرداند.

CLI یک درخواست یک تحقیق سیاست است، نه یک ارزیابی کامل تگ. از طراحی مثبت و نزدیک به اشتباه در درس 27 برای محاسبه شمارش سردرگمی، دقت، بازپسین و ثبات تکرار استفاده کنید.

تمرینات

تمام چهار ردیف ماتریس انسان/نمونه را ایجاد کنید و برای هر یک یک از موارد استفاده مشروع را بنویسید.
فعال کردن فقط برای اپلیکیشن را به اضافه کنیدCorePolicyAdapterثابت کن که تماس گرفتن انسان ها و مدل ها هنوز رد شده
۱۰ مورد را برای مهارت های پیاده سازی بنویسید. هر یک از آنها باید در حالی که به یک جریان کار متفاوت تعلق دارند، ذخایر لغاتی را با مهارت به اشتراک بگذارند.
یک مرزهای مبهم بین دو امتیاز برتر رویتینگ اضافه کنید.askوقتی که حاشیه خیلی کوچک باشه
به درخواست های مهارت به مهارت حداکثر عمق ترکیب اضافه کنید و چرخه دو مهارت را تشخیص دهید.
همان مجموعه برچسب شده را از طریق آداپتورهای هسته و تمدید اجرا کنید. هر تصمیم تغییر شده را توضیح دهید.

اصطلاحات کلیدی

Term	What people say	What it actually means
Explicit invocation	"Slash command"	An actor supplies skill identity directly, subject to policy
Implicit invocation	"The model chooses"	A router selects from eligible catalog metadata based on task context
User-invocable	"Humans can use it"	A host-specific menu or direct-invocation property, not a core field
Model-invocable	"The agent can use it"	Eligibility for implicit model selection under host policy
Invocation adapter	"Frontmatter parser"	Code that maps a host's fields and APIs into a declared policy model
Near miss	"Hard negative"	A non-triggering request that resembles a skill's intended inputs
Abstention	"No skill selected"	A deliberate routing result when evidence is absent or ambiguous

خواندن بیشتر

Optimizing skill descriptionsبرای عوامل مثبت، مشخصه و ارزیابی.
Evaluating skillsبرای طراحی ارزیابی تگ و خروجی.
OpenAI: Build skillsبرای کنترل های صریح و ضمنی دعوت در حال حاضر در کدوکس.
Claude Code skillsبرای یک میزبانuser-invocable،disable-model-invocation، استدلال ها و زمینه های تفویض شده

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.