Skill چیه و چطور یه ایجنت عمومی رو متخصص می‌کنه؟

Skill دقیقاً چه مسئله‌ای رو حل می‌کنه؟

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

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

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

یه Skill از چی ساخته شده

در ساده‌ترین شکل، یه Skill یه پوشه‌ست با یه فایل SKILL.md داخلش. اون فایل یه سربرگ YAML داره و بعدش متن دستورالعمل. همین.

---
name: monthly-report
description: >-
  گزارش ماهانه فروش را به قالب رسمی شرکت تبدیل می‌کند.
  وقتی کاربر فایل خام فروش می‌دهد و گزارش ماهانه،
  خلاصه مدیریتی یا گزارش رسمی می‌خواهد استفاده شود.
---

# گزارش ماهانه

## ترتیب کار
1. فایل خام را با `scripts/normalize.py` مرتب کن.
2. قالب `assets/template.md` را پر کن.
3. هر عددی که با ماه قبل بیش از ۲۰٪ فرق دارد را علامت بزن.

## قواعدی که همیشه رعایت می‌شود
- مبلغ‌ها با جداکننده هزارگان و واحد تومان.
- ردیفی که داده ندارد حذف نمی‌شود؛ خالی می‌ماند.

کنار SKILL.md می‌تونی هر چیزی بذاری که کار لازمش داره: یه پوشه‌ی assets برای قالب‌ها، یه پوشه‌ی scripts برای کدی که باید اجرا بشه، یا فایل‌های مرجع طولانی که فقط گاهی لازم می‌شن.

• name — شناسه‌ی کوتاه و یکتا. معمولاً هم‌نام پوشه.
• description — تنها چیزی که مدل از اول می‌بینه. اینکه Skill کِی فعال بشه یا نشه، کاملاً به این متن بستگی داره.
• بدنه‌ی SKILL.md — دستورالعمل واقعی. وقتی خونده می‌شه که مدل تصمیم گرفته باشه این Skill به کار میاد.
• فایل‌های جانبی — قالب، مرجع، اسکریپت. فقط وقتی خونده می‌شن که بدنه بهشون ارجاع بده.

بارگذاری تدریجی: چرا Skill کانتکست رو پر نمی‌کنه

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

الگوی بارگذاری تدریجی این مسئله رو در سه لایه حل می‌کنه:

1. در شروع گفت‌وگو، فقط name و description هر Skill بارگذاری می‌شه. چند ده کلمه برای هر کدوم، نه بیشتر.
2. وقتی کار کاربر با توضیح یه Skill جور دراومد، بدنه‌ی SKILL.md خونده می‌شه.
3. اگه بدنه به فایل دیگه‌ای ارجاع داده باشه، اون فایل فقط در همون لحظه خونده می‌شه.

نتیجه‌ی عملی‌ش اینه که می‌تونی ده‌ها Skill داشته باشی بدون اینکه هزینه‌ی هر گفت‌وگو بالا بره. همون منطق just-in-time که در مهندسی کانتکست هم جواب می‌ده: شناسه رو نگه دار، محتوا رو وقتی لازم شد بیار.

توضیح خوب، تفاوت بین Skill مرده و زنده

بیشترین وقتی که آدم‌ها روی نوشتن Skill می‌ذارن صرف بدنه می‌شه، در حالی که چیزی که تعیین می‌کنه Skill اصلاً استفاده بشه یا نه، توضیحشه. توضیح بد یعنی یه فایل عالی که هیچ‌وقت خونده نمی‌شه.

توضیحی که کار نمی‌کنه

«کمک به گزارش‌نویسی» — این نه می‌گه چه نوع گزارشی، نه می‌گه کاربر چه جمله‌ای ممکنه بگه، نه می‌گه چه ورودی‌ای لازمه. مدل هیچ نشانه‌ای برای تطبیق نداره.

توضیحی که کار می‌کنه

«گزارش ماهانه فروش را به قالب رسمی شرکت تبدیل می‌کند. وقتی کاربر فایل خام فروش می‌دهد و گزارش ماهانه، خلاصه مدیریتی یا گزارش رسمی می‌خواهد استفاده شود.» — این هم کار رو می‌گه، هم شرایط فعال‌شدن، هم واژه‌هایی که کاربر واقعاً به کار می‌بره.

• فعل مشخص بنویس، نه اسم کلی: «تبدیل می‌کند»، نه «کمک به».
• شرط فعال‌شدن رو صریح بگو: «وقتی کاربر ... می‌خواهد».
• واژه‌های واقعی کاربر رو بیار، نه اصطلاح داخلی تیم.
• مرز رو بگو. اگه Skill برای گزارش فروشه و نه گزارش مالی، همین رو بنویس.

چه‌وقت Skill بنویسی و چه‌وقت ننویسی

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

این نشانه‌ها می‌گن Skill ارزشش رو داره:

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

و این‌ها می‌گن Skill لازم نیست: کار یک‌باره‌ست؛ یا آن‌قدر ساده‌ست که یه جمله کافیه؛ یا هنوز خودت هم نمی‌دونی روش درستش چیه. Skill نوشتن قبل از اینکه روش تثبیت شده باشه، یعنی تثبیت‌کردن یه روش اشتباه.

از کار تکراری تا Skill: یک مثال کامل

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

قدم اول: کاری که واقعاً می‌کنی رو بنویس

قبل از هر چیز، یه بار کار رو انجام بده و همزمان هر تصمیمی که می‌گیری رو یادداشت کن. کدوم فایل رو باز کردی؟ چرا اون خطا رو نادیده گرفتی؟ از کجا فهمیدی این یکی مهمه؟ این یادداشت خام، ماده‌ی اصلی Skillه. اکثر Skillهای بد نوشته می‌شن چون نویسنده از حافظه نوشته، نه از مشاهده.

قدم دوم: قطعی رو از قضاوتی جدا کن

حالا یادداشت رو دو تکه کن. کارهایی که همیشه یه شکلن و هیچ تصمیمی نمی‌خوان، باید بشن اسکریپت؛ مثل فیلترکردن لاگ بر اساس تاریخ و سطح خطا. کارهایی که قضاوت می‌خوان، باید بشن دستورالعمل؛ مثل تشخیص اینکه کدوم خطا برای تیم مهمه.

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

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

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

امنیت و بازبینی

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

• Skillها رو مثل کد توی گیت نگه دار و تغییراتشون رو بازبینی کن.
• دستورالعملی که رفتار حساس داره (حذف، ارسال، پرداخت) رو با تأیید انسان همراه کن.
• هر چند ماه یه بار بازبینی کن: Skillی که با فرایند فعلی نمی‌خونه، بدتر از نبودنشه.