اسکیل‌های ایجنت: قرارداد پورت‌پذیر و مرزهای زمان اجرا

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

مفهوم «اسکیل ایجنت» (Agent Skill) این مشکل را با معرفی یک بستهٔ استاندارد بر پایهٔ `SKILL.md` حل می‌کند؛ ساختاری که دانش رویه‌ای، ابزارهای کمکی و پیش‌نیازها را در قالبی پورت‌پذیر و مستقل از یک هاست خاص در اختیار مدل قرار می‌دهد. این درس تفاوت اسکیل را با پرامپت، ابزارهای پروتکل کانتکست مدل (MCP)، هوک‌ها و زیرایجنت‌ها روشن می‌کند و چرخهٔ دقیق کشف، فعال‌سازی و اجرای امن آن را آموزش می‌دهد.

اسکیل (Skill) یک پرامپت طولانی با اسمی قشنگ‌تر نیست؛ بسته‌ای قابل‌کشف از دستورالعمل‌ها، منابع و فایل‌های کمکیِ قابل‌اجراست که بر اساس یک قرارداد زمان اجرا (runtime contract) وارد کانتکست ایجنت می‌شود.

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

• تعریف دقیق اسکیل ایجنت بدون اشتباه گرفتن آن با پرامپت، دستورالعمل‌های مخزن، ابزار، هوک (hook)، زیرایجنت (subagent) یا پلاگین.
• خواندن قرارداد پورت‌پذیر SKILL.md و تفکیک آن از اکستنشن‌های اختصاصی هر محیط اجرا (runtime).
• توضیح مراحل کشف (discovery)، انتخاب (selection)، فعال‌سازی (activation)، بارگذاری منابع، فراخوانی ابزار (tool use) و اعتبارسنجی به‌منزلهٔ گام‌های مجزای چرخهٔ حیات.
• اعتبارسنجی بستهٔ اسکیل پیش از قرار گرفتن در کاتالوگ ایجنت توسط محیط اجرا.
• انتخاب درست میان اسکیل، ابزار MCP، هوک، زیرایجنت یا کد معمولی برای یک تسک واقعی.

نتیجه‌گیری سریع در 10 دقیقه

این بخش را پیش از خواندن توضیحات مفصل انجام دهید. یک اسکیل کوچک می‌سازید، بستهٔ کامل بازبین (reviewer bundle) را روی یک میزبان (host) واقعی ایجنت نصب می‌کنید، آن را فرامی‌خوانید، نتیجه را می‌سنجید و در پایان حذفش می‌کنید. این کار چرخهٔ حیات اسکیل را با یک نتیجهٔ ملموس اثبات می‌کند.

پیش‌نیازهای آزمایش روی میزبان واقعی

این چک‌پوینت نیازمند Node.js، دستور npx، پایتون 3، یک میزبانِ با قابلیت پشتیبانی از اسکیل و دسترسی نوشتن روی پروژه یا دامنهٔ (scope) کاربریِ انتخابی شما در نصاب است. ابتدا در دسترس بودن دستورات محلی را بسنجید:

node --version
npx --version
python3 --version

پیش از نصب، میزبان و دامنه‌ای را که استفاده خواهید کرد مشخص کنید. اگر هر کدام از نیازمندی‌ها فراهم نیست، درس را از روی وب‌سایت بخوانید یا با تمرین دستی بسته‌ها در ادامه پیش بروید. روش جایگزینْ قرارداد را به شما می‌آموزد، اما کشف توسط میزبان، فراخوانی، اجرای اسکریپت‌های همراه یا رفتار هنگام حذف را نشان نمی‌دهد؛ این مشاهدات را در وضعیت در انتظار بررسی (pending) نگه دارید.

1. شروع در یک دایرکتوری کاری خالی

این دستورات را در هر دایرکتوری والدی که کارهای آموزشی‌تان را در آن نگه می‌دارید اجرا کنید:

mkdir -p agent-skills-first-run
cd agent-skills-first-run
TARGET_ROOT="$(pwd -P)"
printf 'TARGET_ROOT=%s\n' "$TARGET_ROOT"
ls -A

دستور آخر نباید هیچ خروجی‌ای چاپ کند. اگر فایلی چاپ شد، دایرکتوری خالی دیگری انتخاب کنید تا مرزهای بازبینی شفاف بماند.

دایرکتوری اسکیل اول‌تان را بسازید:

mkdir -p my-first-skill

فایل my-first-skill/SKILL.md را با این محتوا ایجاد کنید:

---
name: my-first-skill
description: Turn rough meeting notes into a compact decision record when the user asks to capture a technical decision.
---

# Decision record

Extract the decision, context, alternatives, owner, and next review date.
If the notes do not contain a decision, ask one clarifying question instead
of inventing one.

بررسی کنید که فایل در همان دایرکتوری مورد نظر ساخته شده باشد:

test -f my-first-skill/SKILL.md

نبود خروجی و کد خروج 0 یعنی فایل وجود دارد.

2. نصب بستهٔ کامل بازبین

در پوشهٔ agent-skills-first-run بمانید و اجرا کنید:

npx skills add rohitg00/ai-engineering-from-scratch --skill skill-contract-reviewer --full-depth

میزبان ایجنت و دامنه‌ای را که استفاده می‌کنید انتخاب کنید. نصاب باید نام skill-contract-reviewer و مسیر مقصدی را که نوشته است نمایش دهد. آرگومان --full-depth الزامی است، چون اسکیل این درس یک بستهٔ تو در تو شامل ارجاعات، یک اسکریپت و یک دارایی (asset) است.

متغیر SKILL_ROOT را برابر با مسیر مطلقی قرار دهید که نصاب گزارش کرده است. این مسیر باید دقیقاً دایرکتوری حاوی SKILL.md نصب‌شده باشد، نه دایرکتوری سورس درس و نه ورک‌اسپیس فعلی:

# جاگذاری را با مقصد چاپ‌شده توسط نصاب جایگزین کنید.
SKILL_ROOT="$(cd "/absolute/path/to/skill-contract-reviewer" && pwd -P)"
test -f "$SKILL_ROOT/SKILL.md"
printf 'SKILL_ROOT=%s\n' "$SKILL_ROOT"

اگر نشست (session) ایجنت از قبل باز بوده، نشست جدیدی باز کنید یا دستور اسکن مجدد (rescan) اسکیل‌ها را در آن میزبان اجرا کنید. فرض نکنید همهٔ میزبان‌ها کاتالوگ‌شان را درجا و آنی به‌روزرسانی (hot-reload) می‌کنند.

3. فراخوانی صریح

در ایجنت نصب‌شده، درحالی‌که agent-skills-first-run دایرکتوری کاری شماست، از سینتکس مورد پشتیبانی آن میزبان استفاده کنید:

در درخواست خود، مقادیر مطلقی را بگذارید که برای SKILL_ROOT و TARGET_ROOT چاپ شده بودند. از میزبان بخواهید پیش از اجرا آن‌ها را بسط دهد و دستور نهایی پردازش‌شده را نمایش دهد، نه دستوری که به دایرکتوری کاری پروسه وابسته باشد:

Use skill-contract-reviewer to review <TARGET_ROOT>/my-first-skill. The installed bundle root is <SKILL_ROOT>. Run python3 <SKILL_ROOT>/scripts/check_skill.py <TARGET_ROOT>/my-first-skill. Before running it, show the fully resolved argv. Return the validation report, selected primitives, and one sentence for each selection. Include the resolved script path, resolved target path, cwd, argv, and exit code as execution evidence.

دستور نهایی باید به این شکل باشد و هیچ جای‌نگهداری در آن نماند:

python3 "/absolute/install/path/skill-contract-reviewer/scripts/check_skill.py" \
  "/absolute/workspace/path/agent-skills-first-run/my-first-skill"

یک اجرای موفق هر سه ویژگی زیر را دارد:

1. میزبان skill-contract-reviewer را با نام پیدا کند.
2. بازبینْ قرارداد بسته را بخواند و اعتبارسنجِ (validator) همراهش را اجرا کند.
3. پاسخ حاوی یک گزارش اعتبارسنجی بدون خطای ساختاری برای نمونهٔ ورودی باشد، به‌همراه انتخابی مستدل از نوع المان مناسب (primitive).

شواهد اجرا (execution evidence) باید مسیر اسکریپت، مسیر هدف، دایرکتوری کاری جاری (cwd)، بردار آرگومان‌های دقیق و کد خروج را هم مشخص کند. یک گزارش روان بدون این فیلدها اثبات نمی‌کند که اسکریپت همراهِ نصب‌شده واقعاً اجرا شده است.

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

4. آزمودن انتخاب خودکار (ضمنی)

یک نوبت گفت‌وگوی (turn) تازه باز کنید و همان تسک را بدون آوردن نام اسکیل بنویسید:

Review <TARGET_ROOT>/my-first-skill as a reusable agent package and tell me whether its package contract is valid.

اگر میزبان اسکیل‌های انتخاب‌شده را نمایش می‌دهد، ثبت کنید که آیا skill-contract-reviewer را برگزیده است یا خیر. اگر میزبان فرایند مسیریابی را نشان نمی‌دهد، انتخاب ضمنی را در وضعیت «اثبات‌نشده» ثبت کنید. فراخوانی صریح، راهکار جایگزین پورت‌پذیر است.

5. پاک‌سازی

فقط بستهٔ بازبینِ نصب‌شده را حذف کنید:

npx skills remove skill-contract-reviewer

همان میزبان و دامنه‌ای را که موقع نصب داده بودید انتخاب کنید. بعد از اسکن مجدد یا در یک نشست جدید، درخواست صریح برای skill-contract-reviewer باید بگوید که این اسکیل در دسترس نیست. پوشهٔ my-first-skill را برای درس‌های بعد نگه دارید، یا بعد از پایان این دوره کل دایرکتوری آزمایش را پاک کنید.

صورت‌مسئله

فرض کنید تیم شما فرایند ریلیز مطمئنی دارد: تغییرات merge شده را پیدا می‌کند، یادداشت‌های مایگریشن را می‌خواند، گزارش تغییرات (changelog) را به‌روز می‌کند، دستور بسته‌بندی را اجرا می‌کند و چک‌لیست بازبینی می‌سازد.

گذاشتن این فرایند در دل یک پرامپت شاید برای کپی‌پیست راحت باشد، اما به‌کارگیری و نگهداری آن دشوار است. این پرامپت هویت ثابتی ندارد، قاعدهٔ کشفی برایش تعریف نشده، مرز منابعش نامشخص است، ساختار بسته‌ای قابل‌آزمایشی ندارد و به پرسش‌های بنیادی پاسخ نمی‌دهد: چه کسی اجازهٔ فراخوانی‌اش را دارد؟ مدل چه زمانی باید انتخابش کند؟ کدام اسکریپت‌ها را می‌تواند اجرا کند؟ کدام فایل‌ها قابل‌اعتمادند؟ وقتی کانتکست خلاصه و فشرده می‌شود چه چیزهایی باقی می‌ماند؟

اشتباه برعکس این است که هر دستورالعمل با قابلیت استفادهٔ مجدد را اسکیل بدانیم. قراردادهای مخزن، اتوماسیون‌های قطعی، ابزارهای خارجی، هوک‌های رویداد و ایجنت‌های محول‌شده (subagent) هرکدام مسئلهٔ متفاوتی را حل می‌کنند. چپاندن همهٔ این‌ها درون SKILL.md دایرکتوری‌ای می‌سازد که ظاهرش پورت‌پذیر است، اما به رفتار ثبت‌نشدهٔ یک میزبان خاص وابسته است.

نخستین وظیفهٔ مهندسی، دسته‌بندی است. پیش از آنکه به فکر نحوهٔ بسته‌بندی بروید، نوع دست‌سازه (artifact) را مشخص کنید.

مفهوم

اسکیل‌ها دانش رویه‌ای را کدگذاری می‌کنند

یک اسکیل ایجنت، دایرکتوری‌ای است که نقطهٔ ورودش SKILL.md است. این فایل ورودی شامل بخش سرآیند YAML (فرانت‌متر یا frontmatter) و به‌دنبال آن دستورالعمل‌های Markdown است. این دایرکتوری می‌تواند شامل ارجاعات، اسکریپت‌ها و دارایی‌ها هم باشد.

واحد قابل‌استقرار، کل همین دایرکتوری است نه صرفاً فایل Markdown. کپی کردن SKILL.md با ارجاعات ناقص، حتی اگر فرانت‌متر آن به‌درستی پارس شود، یک بستهٔ خراب تحویل می‌دهد.

مفاهیم همسایه

یک اسکیل ریلیز می‌تواند به ایجنت بگوید چطور یک نسخه را بازرسی کند. یک سرور MCP می‌تواند رجیستری ریلیز را در دسترس قرار دهد. یک هوک می‌تواند جلوی push مستقیم را بگیرد. یک زیرایجنت هم می‌تواند کاندیدای ریلیز را مستقل ممیزی کند. این قطعات در کنار هم می‌نشینند چون مسئولیت‌های متفاوتی را حفظ می‌کنند.

کلمهٔ «اسکیل» به دو ایدهٔ کاملاً متفاوت اشاره دارد

سیستم‌های پژوهشی گاهی به یک برنامهٔ یادگرفته‌شده، مسیر موفق پیشین، یا قطعه‌ای از خط‌مشیِ وابسته به محیط، اسکیل می‌گویند. ایجنت می‌تواند هنگام کاوش چنین چیزهایی بسازد، آن‌ها را بر اساس شباهت به تسک بازیابی کند، به اجرا بگذارد و با دریافت بازخورد کتابخانه‌اش را اصلاح کند. در درس Phase 14 · 10 چنین کتابخانه‌ای برای یادگیری مادام‌العمر می‌سازیم.

اما اسکیل ایجنت در این بخش از دوره فرق دارد. این یک بستهٔ تالیف‌شده با قرارداد سیستم‌فایلیِ معین، متادیتای کاتالوگ، افشای تدریجی (progressive disclosure)، فراخوانی با واسطهٔ محیط اجرا و ابزارهای تحت کنترل میزبان است. اسکیل می‌تواند توسط ایجنت تولید شود یا ارتقا یابد، اما یادگیریْ شرط لازم برای این قالب نیست.

هر دو مفهوم به‌نوعی توانمندیِ بازکاربردپذیر را بسته‌بندی می‌کنند. اما نباید صرفاً به‌خاطر اشتراک در نام، ادعاهای پیاده‌سازی یکسانی برایشان متصور شد.

هستهٔ پورت‌پذیر

مشخصات استاندارد اسکیل‌های ایجنت دو فیلد اجباری در فرانت‌متر تعریف می‌کند:

---
name: release-readiness
description: Inspect a release candidate when the user asks whether a version is ready to publish.
---

فیلد name شناسهٔ پایدار اسکیل است. این فیلد باید قوانین نام‌گذاری استاندارد را برآورده کند و نامش با نام دایرکتوری والد یکی باشد. فیلد description هم مستندات است و هم متادیتای مسیریابی؛ باید بگوید اسکیل چه می‌کند و چه زمانی کاربرد دارد.

فیلدهای اختیاریِ پورت‌پذیر عبارتند از:

بدنهٔ Markdown شامل دستورالعمل‌های عملیاتی است. این بخش باید فرایند کار، نقاط تصمیم‌گیری، رفتار در صورت شکست و مسیرهای مستقیم به منابع پشتیبان را مشخص کند.

# Release readiness

Use this workflow for a release candidate, not for ordinary development builds.

1. Read `references/release-policy.md`.
2. Run `python3 scripts/inspect_release.py --format json`.
3. Stop if the report contains a blocking failure.
4. Produce the checklist from `assets/release-checklist.md`.
5. Ask for approval before any publish or tag action.

اکستنشن‌های محیط اجرا لایهٔ دوم هستند

برخی میزبان‌ها فرانت‌مترهای اضافه یا تنظیمات جانبی می‌پذیرند. این فیلدها شاید مفید باشند، اما لزوماً پورت‌پذیر نیستند.

با هر اکستنشن مانند یک تطبیق‌دهنده (adapter) رفتار کنید. فرایند اصلی کار را طوری بنویسید که بدون آن هم معتبر باشد، حالت جایگزین را مستند کنید و میزبانی را که از آن استفاده می‌کند بیازمایید. یک محیط اجرا ممکن است فیلد ناشناخته را نادیده بگیرد، رد کند، یا آن را بدون پیاده‌سازی رفتارش نگه دارد.

فرانت‌متر، متادیتای اجرایی است

متادیتا پیش از آنکه بدنهٔ اسکیل خوانده شود، رفتار سیستم را تغییر می‌دهد:

• یک name نامعتبر می‌تواند باعث شکست در مرحلهٔ کشف شود.
• یک description مبهم می‌تواند درخواست‌های نادرست را به سمت اسکیل هدایت کند.
• یک فلگ فقط‌مخصوص‌انسان می‌تواند اسکیل را از کاتالوگ مدل حذف کند.
• اعطای دسترسی به ابزار می‌تواند تعیین کند که آیا میزبان از کاربر تایید می‌خواهد یا نه.
• تنظیم کانتکست می‌تواند اجرا را به نشست ایجنت دیگری منتقل کند.

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

چرخهٔ حیات اسکیل

هر فلش نشان‌دهندهٔ یک مرز با حالت‌های شکست (failure modes) خاص خودش است.

1. کشف (Discovery) بسته‌های محتمل را در مسیرهای پیکربندی‌شده پیدا می‌کند.
2. اعتبارسنجی (Validation) بسته‌های معیوب یا ناامن را قبل از انتشار در کاتالوگ رد می‌کند.
3. کاتالوگ‌سازی (Cataloging) فیلدهای جمع‌وجور name و description را ثبت می‌کند، نه کل بسته را.
4. انتخاب (Selection) مرتبط بودن اسکیل را ارزیابی می‌کند.
5. فعال‌سازی (Activation) بدنهٔ اسکیل را وارد کانتکستِ قابل‌مشاهدهٔ مدل می‌کند.
6. افشا (Disclosure) فقط وقتی شاخه‌ای از کار نیاز داشت، ارجاعات یا دارایی‌ها را می‌خواند.
7. اجرا (Execution) از ابزارهای میزبان تحت قوانین مجوزدهی و ایزولاسیون همان میزبان استفاده می‌کند.
8. راستی‌آزمایی (Verification) دست‌سازهٔ خروجی را مستقل از ادعای مدل بررسی می‌کند.

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

اسکیل‌ها و ابزارها بر هم عمودند

پروتکل MCP پاسخ می‌دهد: «این برنامه چه قابلیت‌هایی را می‌تواند فراخوانی کند و شمای آن‌ها چیست؟» اسکیل پاسخ می‌دهد: «ایجنت چگونه باید با این رده از تسک‌ها برخورد کند؟»

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

تفاوت دامنهٔ اسکیل‌ها و دستورالعمل‌های مخزن

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

وقتی هر دو حاضرند، درخواست کاربر و قوانین مخزن اسکیل را مقید می‌کنند. یک اسکیل عمومیِ بازآرایی (refactoring) نباید قاعدهٔ مخزن مبنی بر ممنوعیت ویرایش فایل‌های تولیدشده (generated) را زیر پا بگذارد.

اسکیل‌ها یکدیگر را Import نمی‌کنند

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

وابستگی‌های بین اسکیل‌ها را به‌صورت یال‌های شفاف در فرایند بنویسید:

After producing the candidate changelog, invoke the `release-risk-review` skill.
Pass the candidate path and require a blocking or non-blocking verdict.
If that skill is unavailable, stop and report the missing dependency.

این ساختار وابستگی را تست‌پذیر می‌کند و به میزبان امکان می‌دهد خط‌مشی‌هایش را اعمال کند.

پیاده‌سازی

فایل code/main.py یک اعتبارسنجِ منطبق بر استاندارد و یک انتخاب‌گر دست‌سازه پیاده کرده است. این کد فقط از کتابخانهٔ استاندارد پایتون (stdlib) استفاده می‌کند تا تمام قوانین شفاف باشند.

بخش اعتبارسنج این موارد را فراهم می‌کند:

• parse_frontmatter(text) برای جدا کردن متادیتا از بدنه.
• validate_skill_text(text, directory_name, allowed_runtime_extensions=()) برای کنترل فیلدهای اجباری، نام‌گذاری، اکستنشن‌های ناشناخته، وجود بدنه و محدودیت‌های پورت‌پذیر.
• ValidationIssue و SkillReport برای بازگرداندن شواهد ساختاریافته به‌جای یک مقدار بولیِ مات.
• FrontmatterSyntaxError برای ورودی‌هایی که نمی‌توان آن‌ها را به‌صورت ایمن تفسیر کرد.

بخش انتخاب‌گرْ TaskShape و select_primitives(task) را فراهم می‌کند که نیازهای یک تسک را به کد معمولی، دستورالعمل مخزن، اسکیل، هوک، زیرایجنت یا ابزار MCP نگاشت می‌کند.

آزمایشگاه را اجرا کنید:

cd "$(git rev-parse --show-toplevel)"
cd phases/13-tools-and-protocols/22-skills-and-agent-sdks
python3 code/main.py
python3 -m unittest discover -s code/tests -v

این بلوک دستوری نیازمند یک کلون محلی است و باید از هر نقطه‌ای داخل آن کلون اجرا شود تا git rev-parse --show-toplevel بتواند ریشهٔ مخزن را پیدا کند.

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

ترتیب اعتبارسنجی مهم است

ابتدا فکت‌های ساختاریِ ارزان را بررسی کنید، سپس به سراغ قوانین محتوایی عمیق‌تر بروید:

این اولویت‌بندی مانع از آن می‌شود که خطاهای ثانویه خطای اصلی و ریشه‌ای را بپوشانند.

استفاده از ابزارها

پیش از نوشتن یک اسکیل، این برگهٔ تصمیم‌گیری را پر کنید:

بسیاری از فرایندهای پروداکشن از ترکیب چند ردیف استفاده می‌کنند. این جدول جلوی این را می‌گیرد که یک دست‌سازه ادعا کند همهٔ ویژگی‌ها را تامین می‌کند.

خروجی این درس

این درس بستهٔ skill-contract-reviewer را در مسیر outputs/ می‌سازد که شامل موارد زیر است:

• یک SKILL.md پورت‌پذیر که بستهٔ اسکیل پیشنهادی را بازبینی می‌کند؛
• چک‌لیست‌های مرجع برای قرارداد پورت‌پذیر و انتخاب المان مناسب؛
• یک اسکریپت اعتبارسنجی قطعی؛
• نمونه‌های آزمایشیِ شکل تسک (task-shape fixtures) که پرامپت‌ها، اسکیل‌ها، ابزارها، هوک‌ها، کدهای معمولی و زیرایجنت‌ها را پوشش می‌دهند.

بسته را به‌طور کامل نصب کنید، نه فقط فایل ورودی آن را:

cd "$(git rev-parse --show-toplevel)"
python3 scripts/install_skills.py /tmp/aiefs-skills --phase 13 --type skill

نصاب دوره هر اسکیل کپی‌شده از Phase 13 را گزارش می‌کند و فایل /tmp/aiefs-skills/manifest.json را می‌نویسد. این مقصد تمیز برای بررسی ساختار بسته مناسب است؛ چرخهٔ ده دقیقه‌ای ابتدای درس، کشف و فراخوانی را در یک میزبان واقعی سنجید.

درس‌های آینده به هر مرحله از چرخهٔ حیات عمق می‌بخشند. درس 24 کشف و افشای تدریجی را پیاده می‌کند. درس 25 به خط‌مشی‌های فراخوانی و مسیریابی می‌پردازد. درس 26 مرز مجوزها را از سندباکس تفکیک می‌کند و درس 27 کل بسته را به یک دست‌سازهٔ ریلیز ارزیابی‌شده تبدیل می‌کند.

تمرین‌ها

1. پنج فرایند کاری تیم خود را با استفاده از TaskShape دسته‌بندی کنید. هر جا بیش از یک المان انتخاب کردید، از دلیل آن دفاع کنید.
2. تست‌های مرزی بنویسید که ثابت کنند مقدار 500 کاراکتری برای compatibility قبول می‌شود و مقدار 501 کاراکتری خطای استاندارد می‌دهد.
3. یک اکستنشنِ محیط اجرا به لیست مجاز اضافه کنید. تستی بنویسید که نشان دهد همین فایل همچنان از یک اسکیلِ صرفاً پورت‌پذیر قابل تشخیص است.
4. یک پرامپت 400 خطی را به فایل SKILL.md، یک مرجع، یک قرارداد اسکریپت و یک قالب خروجی تفکیک کنید. هر فایل باید فقط پاسخگوی یک نوع اطلاعات باشد.
5. برای اسکیلی که به یک ابزار MCP ناموجود ارجاع می‌دهد، یک پاسخ شکست طراحی کنید. ابزاری با دسترسی‌های بازتر را بی‌سر‌و‌صدا جایگزین آن نکنید.
6. یکی از اسکیل‌های فعلی‌تان را بازبینی کنید و هر جملهٔ آن را به یکی از این برچسب‌ها منتسب کنید: مسیریابی، رویه، خط‌مشی، ارجاع، یا قرارداد خروجی. هر موردی را که تعلق ندارد منتقل کنید.

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

برای مطالعهٔ بیشتر

• مستندات استاندارد Agent Skills برای مطالعهٔ قرارداد دایرکتوری و فرانت‌متر پورت‌پذیر.
• بهترین الگوهای Agent Skills برای آشنایی با تعیین دامنه، نوشتن دستورالعمل‌ها و سازمان‌دهی منابع.
• مستندات OpenAI: ساخت اسکیل‌ها برای رفتار فعلی کشف و فراخوانی در Codex.
• اسکیل‌های Claude Code برای بررسی اکستنشن‌های یک محیط اجرا در فراخوانی، آرگومان‌ها، ابزارها و کانتکست‌های واگذارشده.