مهارت‌ها: دانش در وقتِ نیاز

شرکت لیلا یک راهنمای برندِ ۳۰ صفحه‌ای دارد، یک فهرست بازبینی برای پیشنهادهایی که برای مشتری‌ها فرستاده می‌شود، یک روش کار برای گزارش ماهانه، و چهار سند دیگر که عاملش مدام به آن‌ها نیاز پیدا می‌کند. لیلا یاد گرفته که فایلِ دستورها کاری می‌کند عامل در همه‌ی نشست‌ها چیزهایی را بداند. پس چرا هر هفت سند را در آن نگذارد؟

لیلا حالا که CLAUDE.md این‌قدر خوب کار می‌کند، هر هفت روش کار را در آن می‌چسبانم. آن‌وقت عامل همیشه آن‌ها را می‌داند.

امید چقدر طولانی می‌شود؟

لیلا حدود ۵۰ صفحه. شاید ۳۰٬۰۰۰ توکن.

امید فهرستِ بازبینیِ پیشنهادها را چند وقت یک بار لازم داری؟

لیلا ماهی یک بار، وقتی پیشنهادی می‌فرستیم. راهنمای برند را شاید هفته‌ای دو بار.

امید پس بیشتر روزها آن ۳۰٬۰۰۰ توکن چه کار می‌کنند؟

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

امید حالا یک کتاب مرجعِ بزرگ را در نظر بگیر. پیش از هر کاری کل آن را از اول تا آخر می‌خوانی؟

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

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

لیلا آن‌وقت روش‌ها تا وقتی لازم نشده‌اند تقریباً هزینه‌ای ندارند. ولی عامل از کجا می‌فهمد کدام جور است؟

امید با خواندنِ خط‌های فهرست مطالب. پس آن خط‌ها باید خوب نوشته شده باشند.

مهارت چیست

مهارت (skill) پوشه‌ای است که یک روش کار یا یک حوزه‌ی دانش را به عامل یاد می‌دهد. قلب آن فایلی است به نام SKILL.md: یک نام و یک توصیفِ کوتاه در بالا، و دستورهای کامل در پایین. پوشه می‌تواند فایل‌های دیگری هم داشته باشد که دستورها به آن‌ها اشاره می‌کنند، مثل یک برگه‌ی مرجع، یک قالب یا یک اسکریپت کوچک.

این مهارتِ بررسیِ برندِ لیلاست، در قالبِ Claude Code:

---
name: brand-check
description: Checks a document or chart against the company brand
  guide (colours, fonts, logo, tone). Use when the user asks to check
  or fix branding, or before anything is sent to a client.
---
 
# Brand check
 
1. Read the document the user names.
2. Compare its colours with colours.md in this folder.
3. Check the logo with: python check_logo.py <file>
4. List each problem with its page, then suggest a fix.

بخشِ میان دو خطِ --- سرآیندِ مهارت است. name نامِ مهارت است (و با همین نام می‌توانید خودتان آن را راه بیندازید). description می‌گوید مهارت چه می‌کند و کِی باید به کار برود: اینجا، بررسیِ یک سند یا نمودار با راهنمای برند (رنگ‌ها، قلم‌ها، نشان و لحن)، وقتی کاربر بررسی یا اصلاحِ برند را می‌خواهد یا پیش از آنکه چیزی برای مشتری فرستاده شود. هر چه پایین‌تر آمده، خودِ روش کار است، به شکل گام‌های روشن: سند را بخوان، رنگ‌هایش را با colours.md مقایسه کن، نشان را با اسکریپت بررسی کن، و هر مشکل را با شماره‌ی صفحه‌اش فهرست کن و راه‌حلی پیشنهاد بده.

فقط آنچه لازم است بارگذاری شود

نکته‌ی اصلی در این است که هر بخش کِی به زمینه می‌رسد. به این کار آشکارسازیِ گام‌به‌گام (progressive disclosure) می‌گویند: اول کمی نشان بده، و بیشتر را فقط وقتی لازم شد.

1. همیشه: در آغاز هر نشست، فقط نام و توصیفِ هر مهارت در زمینه می‌آید. بیست مهارت ممکن است چند هزار توکن بگیرند، نه صد هزار.
2. وقتی کاری جور باشد: عامل کلِ SKILL.md را در زمینه می‌خواند و دنبالش می‌کند.
3. فقط اگر لازم باشد: فایل‌های دیگرِ پوشه یکی‌یکی باز می‌شوند، اگر گام‌ها به آن‌ها نیاز داشته باشند. یک اسکریپت را هم می‌شود فقط اجرا کرد، و عامل نتیجه‌اش را می‌بیند بی‌آنکه هیچ‌وقت کدش را بخواند.

در Claude Code، مهارت‌ها در پوشه‌ی .claude/skills/ یک پروژه (مشترک با تیم) یا در ~/.claude/skills/ خودتان قرار می‌گیرند. وقتی درخواستِ شما با توصیفِ مهارتی جور باشد، عامل تصمیم می‌گیرد آن را به کار ببرد. خودتان هم می‌توانید با نوشتنِ / و نامِ مهارت، مثل /brand-check، آن را راه بیندازید. عامل‌های دیگر هم همین قالبِ SKILL.md را پذیرفته‌اند، پس مهارتی که خوب نوشته شده باشد جای دیگری هم به کار می‌آید.

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

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

• ضعیف: description: Brand stuff. («چیزهای برند»)
• قوی: description: Checks a document or chart against the brand guide (colours, fonts, logo, tone). Use when the user asks to check or fix branding, or before anything is sent to a client.

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

فایلِ دستورها یا مهارت؟

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

یک آزمونِ خوب: اگر بیشترِ نشست‌ها هرگز به آن نیاز ندارند، مهارت است.

امتحان کنید

کاری را انتخاب کنید که بارها و بارها برای عامل (یا یک دستیار گفت‌وگو) توضیحش داده‌اید. گام‌هایش را به شکل یک SKILL.md بنویسید: یک نام، توصیفی که بگوید چه و کِی، و پنج گامِ شماره‌دار. اگر از Claude Code استفاده می‌کنید، آن را در یک پروژه‌ی تمرینی به شکل .claude/skills/<name>/SKILL.md ذخیره کنید، نشست تازه‌ای شروع کنید و آن کار را با کلمه‌های خودتان بخواهید، بی‌آنکه نامِ مهارت را بیاورید. آیا پیدایش کرد؟

درست به کار بردن

1. توصیف را برای لحظه‌ی انتخاب بنویسید. بگویید مهارت چه می‌کند و درخواستی که به آن نیاز دارد چه کلمه‌هایی خواهد داشت.
2. SKILL.md را متمرکز نگه دارید و جزئیات را بیرون ببرید. مطالبِ مرجعِ بلند در فایل جداگانه‌ای در همان پوشه می‌روند، که فقط اگر گامی لازمش داشته باشد باز می‌شود.
3. توضیح‌های تکراری را به مهارت تبدیل کنید. اگر یک روش کار را در سه نشست توضیح داده‌اید، یک بار آن را به شکل مهارت بنویسید.
4. برای بخش‌هایی که باید دقیق باشند، اسکریپت بگذارید. گامی که باید دقیق انجام شود، مثل بررسیِ قالبِ یک فایل، به شکل اسکریپتی کوچک که مهارت اجرایش می‌کند امن‌تر است تا به شکل کلمه‌هایی که مدل دنبالشان می‌کند.

واژه‌های این درس

• مهارت (skill) - پوشه‌ای که یک روش کار را به عامل یاد می‌دهد: فایلی به نام SKILL.md با نام، توصیف و دستورها، به‌اضافه‌ی هر فایل دیگری که لازم دارد
• SKILL.md - فایل اصلیِ یک مهارت؛ سرآیندش نام و توصیف را دارد و بدنه‌اش گام‌ها را
• آشکارسازیِ گام‌به‌گام (progressive disclosure) - اول خلاصه‌ای کوتاه به عامل دادن و جزئیات کامل را فقط وقتی لازم شد، تا زمینه از چیزهایی که شاید هرگز به کار نیایند پر نشود

ایده‌ی اصلی

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