‏SKILL.md چیه و چطور کار می‌کنه؟

یه اشتباه رایج اینه که آدم‌ها فکر می‌کنن SKILL.md یه پرامپت طولانیه که agent هر بار کل‌شو می‌خونه. اما واقعیت اینه که Skills یه loader specification هستن — یعنی داری مشخص می‌کنی چه چیزی، کِی، و با چه هزینه‌ای باید وارد context بشه.

نویسنده تعریف می‌کنه که اولین اسکیلش ۱۲۰۰ خط بود، شامل workflow، نقشه‌ی ماژول‌ها، کد نمونه و انواع نکات. نتیجه؟ ۲۰٪ از context window قبل از اینکه agent یه کار واقعی انجام بده مصرف می‌شد. بعد از بازنویسی با همون دستورات اما معماری متفاوت — یه SKILL.md 180 خطی که به سه فایل مرجع و یه اسکریپت اشاره می‌کرد — مصرف به ۷٪ رسید. محتوا عوض نشد، فقط ساختار تغییر کرد.

قلب ماجرا چیزیه که Anthropic بهش می‌گه «progressive disclosure». سه لایه‌ی لودینگ وجود داره که هر کدوم در زمان متفاوتی اجرا می‌شن:

لایه اول — Metadata: همون frontmatter YAML، یعنی نام و توضیح اسکیل. این بخش همیشه و در هر ترن لود می‌شه، حدود ۱۰۰ توکن. agent از این توضیح استفاده می‌کنه تا تصمیم بگیره آیا اسکیل مرتبطه یا نه. اگه این توضیح اشتباه باشه، بقیه‌ی اسکیل عملاً وجود نداره.

لایه دوم — SKILL.md body: دستورالعمل‌های اصلی. فقط وقتی agent تشخیص بده اسکیل مرتبطه لود می‌شه. سقف پیشنهادی Anthropic ۵۰۰ خطه. اینجاست که اکثر نویسنده‌ها محتوای اضافه تپ می‌دن.

لایه سوم — References و Scripts: فایل‌های مرجع Markdown که فقط وقتی body بهشون اشاره کنه خونده می‌شن؛ و اسکریپت‌های اجرایی که output‌شون وارد context می‌شه، نه سورس‌کدشون. این لایه عملاً بدون سقفه.

نویسنده برای توضیح این معماری از یه تشبیه آشپزخانه استفاده می‌کنه: تابلوی یادداشت با خلاصه‌ی دستورپخت‌ها (frontmatter)، کارت دستورپخت کامل که فقط وقتی سفارش میاد برداشته می‌شه ، بایندر مرجع که فقط صفحه‌ی مورد نیاز باز می‌شه (references/)، و همزن برقی که فقط نتیجه‌اش مهمه نه مدار داخلیش (scripts/).

یکی از antipattern‌های مهمی که نویسنده بهش می‌رسه اینه که frontmatter رو به فایل‌های مرجع اضافه کنیم. این کار باعث می‌شه اون فایل‌ها مثل یه اسکیل مستقل به system prompt اضافه بشن — انگار یه زیرصفحه رو چسبوندی روی تابلوی اصلی. نتیجه؟ agent ممکنه مستقیماً اون فایل مرجع رو فراخونی کنه، بدون اینکه context اصلی اسکیل رو داشته باشه، و خروجی به شکل نامحسوسی اشتباه می‌شه.

antipattern دوم همون monolithic skill یا اسکیل یکپارچه‌ست — ریختن همه چیز توی یه فایل بزرگ. این دقیقاً همون داستان ۲۰٪ هزینه‌ی اضافیه. وقتی همه چیز توی SKILL.md باشه، agent مجبوره هر بار همه‌شو بخونه، حتی بخش‌هایی که اصلاً ربطی به task فعلی ندارن.

نکته‌ی جالب اینه که SKILL.md دیگه فقط برای Claude نیست. Anthropic این فرمت رو در دسامبر ۲۰۲۵ به عنوان یه استاندارد باز منتشر کرد و الان توی Claude Code، Kiro، Cursor، Codex CLI و ابزارهای دیگه هم کار می‌کنه.

نکات کلیدی:

• Skills یه loader specification هستن، نه پرامپت — ساختار مهم‌تر از محتواست
• Progressive disclosure سه لایه داره: frontmatter (همیشه)، body (موقع فراخوانی)، references/scripts (موقع نیاز)
• سقف پیشنهادی body اسکیل ۵۰۰ خطه
• frontmatter رو به فایل‌های مرجع اضافه نکن — باعث می‌شه به اشتباه مثل اسکیل مستقل رفتار بشن
• اسکریپت‌ها فقط output‌شون وارد context می‌شه، نه سورس‌کدشون — از این برای عملیات سنگین استفاده کن
• SKILL.md یه استاندارد باز شده و روی چندین ابزار مختلف کار می‌کنه