SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor · به‌روزرسانی شده 2026-10-20

چطور برای عامل خودتان یک Skill بنویسید

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

نوشتن مهارت عامل (Agent Skill) شخصی بر اساس یک خطای واقعی

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

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

شروع از وظیفه‌ای که عامل (agent) دو بار در آن اشتباه کرده است

یک بار اتفاق است. دو بار الگو است و الگو ارزش ثبت در یک فایل را دارد.

این یک خطای تکرارشونده در سرورهای واقعی است. شما از عامل می‌خواهید یک بلاک reverse proxy به Nginx اضافه کند. او /etc/nginx/conf.d/app.conf را ویرایش می‌کند و سپس sudo systemctl restart nginx را اجرا می‌کند. ویرایش دارای غلط تایپی است، بنابراین Nginx از شروع کار امتناع می‌کند و سایت تا زمانی که شما آن را اصلاح نکنید، از دسترس خارج می‌ماند:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

شما آن را در چت اصلاح می‌کنید. پیش از دست زدن به سرویس، پیکربندی را با sudo nginx -t تست کنید و سپس آن را با reload به جای restart اعمال کنید. یک هفته بعد، در یک وظیفه متفاوت، همان اشتباه تکرار می‌شود. آن بار دوم، نشانه است.

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

راهنمای تألیف خودِ Anthropic این موضوع را در اولویت قرار می‌دهد. عامل را روی وظایف نمونه بدون مهارت اجرا کنید، جایی که شکست می‌خورد را ثبت کنید و سپس حداقل دستورالعمل‌هایی که آن شکست‌ها را برطرف می‌کند، بنویسید. شکست‌ها همان مشخصات فنی هستند، بنابراین مهارتی که نتوانید آن را به یک شکست ردیابی کنید، معمولاً مهارتی است که هیچ‌کس به آن نیاز نداشته است. همین فیلتر روی مهارت‌هایی که نصب می‌کنید (به جای نوشتن) نیز کار می‌کند و 27 مهارت منتشر شده توسط Matt Pocock را به آن‌هایی که یک توسعه‌دهنده انفرادی روی VPS باید نصب کند و آن‌هایی که فقط در تیم بازدهی دارند، تقسیم می‌کند.

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

آناتومی یک مهارت

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

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md با یک بلوک frontmatter شروع می‌شود؛ مجموعه‌ای از تنظیمات که با فرمت YAML (همان فرمت پیکربندی که فایل‌های Docker Compose استفاده می‌کنند) بین نشانگرهای --- نوشته شده‌اند و در ادامه، دستورالعمل‌ها با فرمت markdown می‌آیند. در اینجا کل مهارت مربوط به خطای فوق آمده است.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

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

  • name: حداکثر 64 کاراکتر، فقط شامل حروف کوچک، اعداد و خط تیره؛ و نباید حاوی کلمات claude یا anthropic باشد. در یک مهارت شخصی یا پروژه‌ای، این فقط برچسب نمایشی است. دستوری که تایپ می‌کنید از نام دایرکتوری گرفته می‌شود، بنابراین این مهارت با /nginx-config-changes فراخوانی می‌شود.
  • description: شرح عملکرد مهارت و زمان استفاده از آن، حداکثر 1,024 کاراکتر. این خط کار اصلی را انجام می‌دهد و بخش بعدی صرفاً به همین موضوع می‌پردازد.
  • بدنه: دستورالعمل‌هایی که فقط هنگام اجرای مهارت بارگذاری می‌شوند.
  • reference/: فایل‌های اضافی که عامل (agent) در صورت نیاز می‌خواند. آن‌ها را از SKILL.md لینک کنید و لینک‌ها را در یک سطح نگه دارید، زیرا فایلی که از یک فایل ارجاع‌داده‌شده دیگر فراخوانی شود، اغلب فقط به‌صورت ناقص خوانده می‌شود.
  • scripts/: فایل‌هایی که عامل به‌جای خواندن، آن‌ها را اجرا می‌کند. فقط خروجی آن‌ها از ظرفیت context استفاده می‌کند، بنابراین یک اسکریپت 300 خطی هزینه کمی دارد.

زمانی که رفتار مورد اصلاح، سرسختانه باشد و نیاز به فضای بیشتری داشته باشد، مهارت به ساختار کامل‌تری گسترش می‌یابد و مهارت غیرتنبلی از این فضا برای یک Depth Tree، مجموعه‌ای از فایل‌های gates و یک قرارداد PLAN.md استفاده می‌کند تا از اعلام پایان کار توسط عامل، در حالی که شاخه‌هایی از کار دست‌نخورده باقی مانده‌اند، جلوگیری کند.

اینکه دایرکتوری را کجا قرار می‌دهید، تعیین می‌کند چه کسی به آن مهارت دسترسی داشته باشد.

  • .claude/skills/<name>/SKILL.md در مخزن (repository): فقط برای همین پروژه، و برای هر کسی که مخزن را clone کند در دسترس خواهد بود.
  • ~/.claude/skills/<name>/SKILL.md: برای تمام پروژه‌های موجود در سیستم شما، و نه هیچ‌کس دیگر.
  • <plugin>/skills/<name>/SKILL.md: بسته‌بندی‌شده درون یک پلاگین، که در هر کجا که آن پلاگین فعال باشد، در دسترس است.

یک مهارت را با mkdir -p .claude/skills/nginx-config-changes ایجاد کنید و فایل آن را بنویسید. Claude Code این دایرکتوری‌ها را زیر نظر دارد، بنابراین ویرایش یک مهارت موجود، بلافاصله در نشست (session) در حال اجرا اعمال می‌شود. ایجاد یک دایرکتوری سطح بالای skills که در زمان شروع نشست وجود نداشته است، نیاز به راه‌اندازی مجدد دارد، زیرا در زمان شروع نشست، مسیری برای نظارت وجود نداشته است.

فیلد description تأثیرگذارترین خط در فایل است

در زمان راه‌اندازی، agent مقادیر name و description مربوط به هر skill موجود را در context خود بارگذاری می‌کند. بدنه (body) این skillها بارگذاری نمی‌شود. هنگامی که درخواست شما می‌رسد، همان یک خط، تنها مبنای تصمیم‌گیری برای مرتبط بودن آن skill است؛ بنابراین، یک بدنه عالی که پشت یک توصیف مبهم پنهان شده باشد، هرگز خوانده نخواهد شد.

توصیف را به صورت سوم‌شخص بنویسید. عبارت "Tests and reloads nginx safely" مناسب است. عبارت "I can help you with nginx" مناسب نیست، زیرا این متن در system prompt تزریق می‌شود و در آنجا، اول‌شخص به این معناست که مدل در حال صحبت درباره خودش است.

دو مورد را در آن بگنجانید: کاری که skill انجام می‌دهد و شرایطی که در آن اعمال می‌شود. مورد استفاده مهم را در ابتدا قرار دهید، زیرا Claude Code ورودی لیست را در 1,536 کاراکتر قطع می‌کند. یک فیلد اختیاری when_to_use برای عبارت‌های محرک (trigger phrases) اضافی و درخواست‌های نمونه وجود دارد که تحت همان محدودیت به انتهای توصیف اضافه می‌شود.

سپس از کلماتی استفاده کنید که واقعاً تایپ خواهید کرد. description: Helps with nginx با هیچ‌چیز مطابقت ندارد، زیرا هیچ‌کس عبارت "helps with" را تایپ نمی‌کند. نسخه بالا نام‌های /etc/nginx، server block، reverse proxy و TLS (transport layer security) certificate path را ذکر می‌کند که تقریباً دایره واژگان هر درخواستی است که باید آن را فعال کند.

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

حجم بدنه را کوچک نگه دارید، زیرا در متن باقی می‌ماند

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

Anthropic توصیه می‌کند SKILL.md را زیر 500 خط نگه دارید و جزئیات را به فایل‌های جداگانه منتقل کنید. فشرده‌سازی نشان می‌دهد که چرا این عدد تصادفی نیست. هنگامی که گفتگو برای آزاد کردن context خلاصه می‌شود، Claude Code آخرین فراخوانی هر مهارت را دوباره ضمیمه می‌کند، فقط 5000 توکن اول هر کدام را نگه می‌دارد و یک بودجه ترکیبی 25000 توکنی را با شروع از مهارتی که اخیراً فراخوانی شده است، پر می‌کند. یک مهارت طولانی در میانه راه قطع می‌شود. چندین مهارت طولانی یکدیگر را کاملاً از حافظه خارج می‌کنند.

بنابراین فقط مطالبی را بنویسید که مدل از قبل نمی‌داند. مدل می‌داند nginx چیست و reverse proxy چه کاری انجام می‌دهد. مدل قانون داخلی شما در مورد reload به جای restart را نمی‌داند و آن قانون تنها دلیل وجود این فایل است.

اگر مهارت به عامل دستور می‌دهد که یک اسکریپت بسته‌بندی‌شده را اجرا کند، مسیر را با ${CLAUDE_SKILL_DIR} نام‌گذاری کنید تا در هر کجا که مهارت نصب شده است، شناسایی شود و همان دستور را از قبل تأیید کنید تا اجرا به دلیل درخواست مجوز متوقف نشود.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

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

چگونه فعال شدن مهارت را اثبات کنیم

مشاهده بارگذاری یک مهارت به شما می‌گوید که عامل (agent) آن را پیدا کرده است، اما به این معنی نیست که پاسخ تغییر کرده است. هر دو مورد را بررسی کنید و این کار را در یک نشست (session) جدید انجام دهید؛ زیرا نشستی که در آن مهارت را نوشته‌اید، تمام گفته‌های شما در حین نوشتن را در حافظه دارد. آن زمینه (context) باقی‌مانده، شکاف‌های موجود در فایل را پنهان می‌کند.

  1. یک نشست جدید با claude در پروژه شروع کنید.
  2. درخواست را به همان شکلی که در یک روز کاری عادی مطرح می‌کنید، با کلمات خودتان و بدون نام بردن از مهارت تایپ کنید.
  3. منتظر فراخوانی (invocation) باشید. اگر مهارت فعال نشد، توضیحات (description) را اصلاح کنید. بدنه (body) هنوز مشکل اصلی نیست.
  4. برای کنترل، آن را به‌صورت دستی با /nginx-config-changes فراخوانی کنید. رفتار صحیح هنگام فراخوانی دستی و رفتار نادرست هنگام درخواست عادی، تأیید می‌کند که مشکل از ماشه (trigger) است، نه از دستورالعمل‌ها.
  5. همان درخواست را با مهارت خاموش اجرا کنید و دو پاسخ را مقایسه کنید. در منوی /skills، مهارت را انتخاب کنید، Space را بزنید تا وضعیت آن به off تغییر کند، سپس Enter را برای ذخیره فشار دهید. این کار یک ورودی skillOverrides در .claude/settings.local.json می‌نویسد و فشردن دوباره Space پس از اتمام کار، آن را به on برمی‌گرداند.
  6. چند درخواست بنویسید که نباید مهارت را فعال کنند و مطمئن شوید که در آن موارد مهارت غیرفعال می‌ماند.

برای خودکارسازی این چرخه، افزونه skill-creator را از بازار رسمی نصب کنید.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

اگر خروجی نصب عبارت Run /reload-plugins to activate. را نشان داد، آن دستور را اجرا کنید. سپس از Claude بخواهید مهارت شما را با نام ارزیابی کند. این افزونه موارد آزمون را در evals/evals.json داخل دایرکتوری مهارت ذخیره می‌کند و هر مورد را در زیر-عامل (subagent) مخصوص به خود اجرا می‌کند، بنابراین هر اجرا با یک زمینه پاک شروع می‌شود. سپس مقایسه‌ای بین حالت «با مهارت» و «بدون مهارت» می‌نویسد که عدد واقعی است: بهبود نرخ موفقیت در برابر توکن‌ها و زمانی که مهارت صرف می‌کند.

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

حالت شکست: مهارت هرگز فعال نمی‌شود

شما درخواست را تایپ می‌کنید، اما عامل (agent) همان رفتار قدیمی و اشتباه را انجام می‌دهد و هیچ خطی مربوط به مهارت ظاهر نمی‌شود. این موارد را به ترتیب بررسی کنید.

  • توضیحات مهارت مشخص می‌کند که مهارت چه کاری انجام می‌دهد، اما نمی‌گوید چه زمانی باید از آن استفاده کرد؛ بنابراین هیچ بخشی از درخواست شما با آن مطابقت ندارد.
  • توضیحات مهارت از کلماتی که شما تایپ می‌کنید اجتناب می‌کند. اگر شما "nginx" را تایپ می‌کنید، توضیحات مهارت نیز باید شامل کلمه nginx باشد.
  • گزینه disable-model-invocation: true در frontmatter تنظیم شده است. این کار باعث می‌شود توضیحات مهارت به‌طور کامل از context مدل خارج شود و مهارت فقط توسط شما و با استفاده از /name قابل فراخوانی باشد.
  • یک glob در paths در frontmatter، فعال‌سازی را به فایل‌های منطبق محدود می‌کند و فایلی که روی آن کار می‌کنید با این الگو مطابقت ندارد.
  • این مهارت در یک دایرکتوری تو در توی .claude/skills/ در زیر دایرکتوری شروع شما قرار دارد. این مهارت‌ها تنها پس از آنکه عامل یک فایل را در آن زیردایرکتوری بخواند یا ویرایش کند بارگذاری می‌شوند؛ بنابراین تا آن زمان، مهارت اصلاً در دسترس نیست.

حالت شکست: فعال‌سازی مداوم مهارت

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

توصیف را به شرایطی که واقعاً اهمیت دارد محدود کنید و فایل‌ها یا دستوراتی که پوشش می‌دهد را نام ببرید. اگر مهارت فقط برای فایل‌های خاصی کاربرد دارد، یک paths glob اضافه کنید. برای هر عملیاتی که عوارض جانبی دارد، مانند deploy یا commit، مقدار disable-model-invocation: true را تنظیم کنید و آن را شخصاً با /name فراخوانی کنید تا عامل هرگز به‌طور خودکار تصمیم نگیرد که اکنون زمان مناسبی برای deploy است.

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

یک فایل قوانین مانند CLAUDE.md یا AGENTS.md در ابتدای هر نشست بارگذاری می‌شود و برای هر وظیفه‌ای اعمال می‌گردد. بدنهٔ یک مهارت تنها زمانی بارگذاری می‌شود که آن مهارت فراخوانی شود. تناوب، عامل اصلی تصمیم‌گیری است. حقیقتی که برای تمام وظایف در مخزن صادق است، مانند مدیر بسته‌ای که استفاده می‌کنید، متعلق به فایل قوانین است. رویه‌ای که تنها برای بخش کوچکی از وظایف کاربرد دارد، مانند قانون nginx در بالا، متعلق به یک مهارت است؛ جایی که در روزهایی که کسی nginx را ویرایش نمی‌کند، هیچ هزینه‌ای ندارد.

شکست واقعی، قرار دادن آن در هر دو مکان است. دو نسخه از هم فاصله می‌گیرند و زمانی که عامل (agent) کار اشتباهی انجام می‌دهد، نمی‌توانید تشخیص دهید که از کدام نسخه پیروی کرده است. برای هر دستورالعمل، یک خانه انتخاب کنید. قانونی که در حال حاضر دقیقاً در یک خانه قرار دارد و همچنان نادیده گرفته می‌شود، مسئلهٔ متفاوتی است و بررسی مکانیسم‌های پشت یک دستورالعمل نادیده گرفته شده پیش از انتقال آن به یک مهارت و امید به حل مشکل با این جابه‌جایی، ارزشمند است. مرز بین مهارت‌ها، سرورهای MCP و فایل‌های قوانین موارد پیچیده‌تر را بررسی می‌کند، از جمله زمانی که پاسخ درست، استفاده از یک سرور MCP (پروتکل زمینه مدل) است که به جای یک دستورالعمل جدید، ابزار جدیدی در اختیار عامل قرار می‌دهد.

پس از اثبات کارایی، آن را به اشتراک بگذارید

مهارتی که یک هفته کار واقعی را تاب بیاورد، ارزش ثبت‌کردن دارد. مهارت‌های پروژه در .claude/skills/ مانند کد بازبینی می‌شوند و همراه با مخزن (repository) منتقل می‌گردند؛ بنابراین هم‌تیمی که مخزن را clone می‌کند، اصلاحات شما را بدون نیاز به هیچ مرحلهٔ راه‌اندازی اضافی دریافت خواهد کرد. انتقال یک مهارت بین مخازن بدون استفاده از کپی و پیست، چالش خاص خود را دارد که در نحوه اشتراک‌گذاری مهارت‌های عامل بین مخازن به آن پرداخته شده است.

یک نکته دربارهٔ قابلیت حمل: Claude Code فهرست بلندی از فیلدهای frontmatter را می‌پذیرد، اما استاندارد Agent Skills تنها شش مورد را مجاز می‌داند: name، description، license، compatibility، metadata و allowed-tools. اگر مهارتی را با هر فیلد دیگری در frontmatter به claude.ai آپلود کنید یا برای Skills API بسته‌بندی نمایید، به‌جای نادیده‌گرفتن آن فیلد، کل عملیات با شکست مواجه می‌شود:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

در محدودهٔ همان شش فیلد باقی بمانید تا فایل مشابه در Claude Code و هر ابزار دیگری که از این استاندارد پشتیبانی می‌کند، بارگذاری شود. این‌که فایل کجا بارگذاری می‌شود، تعیین‌کنندهٔ قابلیت‌های آن است، زیرا Cowork در یک sandbox متعلق به Anthropic اجرا می‌شود، در حالی که Claude Code روی دستگاه شخصی یا VPS شما اجرا می‌گردد؛ بنابراین مهارت nginx که در بالا ذکر شد، ارزش انتقال به سیستم هم‌تیمی را دارد اما در sandboxای که به سرور دسترسی ندارد، بی‌فایده است. نوشتن دستورالعمل‌ها به‌گونه‌ای که با انتقال به مدل‌های دیگر همچنان کارآمد باشند، وظیفه‌ای مجزا است که در نوشتن مهارت‌هایی که با هر مدلی کار می‌کنند پوشش داده شده است.

FAQ

فایل SKILL.md باید چقدر طولانی باشد؟

آن را زیر 500 خط نگه دارید و انتظار داشته باشید که اکثر مهارت‌های مفید بسیار کوتاه‌تر از این باشند. بدنهٔ فایل هنگام فراخوانی مهارت وارد گفتگو می‌شود و تا پایان نشست در آن باقی می‌ماند، بنابراین هر خط یک هزینهٔ تکرارشونده است، نه یک هزینهٔ یک‌باره. مطالب مرجع طولانی را به فایل‌های جداگانه در دایرکتوری مهارت منتقل کنید و از طریق SKILL.md به آن‌ها لینک دهید؛ با این کار، عامل (agent) تنها زمانی که به آن‌ها نیاز دارد، فایل‌ها را می‌خواند. اسکریپت‌های همراه (bundled scripts) به‌جای خوانده شدن، اجرا می‌شوند، بنابراین هزینهٔ آن‌ها فقط معادل خروجی‌شان است.

چرا مهارت من هرگز فعال (trigger) نمی‌شود؟

توضیحات (description) معمول‌ترین دلیل این اتفاق است، زیرا تنها بخشی از مهارت است که هنگام تصمیم‌گیری مدل در context قرار دارد. اطمینان حاصل کنید که توضیحات نه تنها عملکرد مهارت، بلکه زمان استفاده از آن را نیز مشخص می‌کند و شامل کلماتی است که واقعاً در درخواست‌های خود تایپ می‌کنید. اگر توضیحات درست به نظر می‌رسد، frontmatter را برای disable-model-invocation: true بررسی کنید که مهارت را به‌طور کامل از دید مدل پنهان می‌کند، و همچنین برای یک glob در paths که آن را به فایل‌هایی که با آن‌ها کار نمی‌کنید محدود کرده است. مهارت موجود در یک دایرکتوری تو در توی .claude/skills/ پایین‌تر از دایرکتوری شروع شما نیز دلیل دیگری است: این مهارت تنها پس از آنکه عامل فایلی را در آن زیرشاخه بخواند یا ویرایش کند، بارگذاری می‌شود.

آیا این باید یک مهارت باشد یا یک خط در فایل قوانین (rules file) من؟

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

از کجا بدانم که یک مهارت واقعاً کمک کرده است؟

آن را با یک مبنا (baseline) مقایسه کنید. چند درخواست واقعی جمع‌آوری کنید، هر کدام را در یک نشست تازه با مهارت فعال اجرا کنید، سپس آن‌ها را دوباره با مهارت غیرفعال‌شده از منوی /skills اجرا کنید و هر دو پاسخ را کنار هم بخوانید. نشست تازه اهمیت دارد، زیرا گفتگویی که در آن مهارت را نوشتید هنوز حاوی توضیحات شماست و باعث می‌شود یک فایل ناقص، کامل به نظر برسد. افزونهٔ skill-creator این مقایسه را برای شما انجام می‌دهد و نرخ موفقیت را در کنار هزینهٔ توکن گزارش می‌کند.

آیا می‌توانم از همان SKILL.md با یک عامل (agent) متفاوت استفاده کنم؟

بله، تا زمانی که در فیلدهایی که استاندارد Agent Skills تعریف کرده است بمانید: name، description، license، compatibility، metadata و allowed-tools. Claude Code فیلدهای بسیار بیشتری را می‌پذیرد و همچنین از ویژگی‌های بدنه مانند تزریق دستورات شل (shell command injection) پشتیبانی می‌کند که سایر ابزارها آن را اجرا نمی‌کنند. بارگذاری مهارتی با یک فیلد خارج از استاندارد، با یک خطای صریح که ویژگی‌های مجاز را فهرست می‌کند، شکست می‌خورد؛ بنابراین از ابتدا تصمیم بگیرید که آیا یک مهارت قرار است در Claude Code باقی بماند یا قابل انتقال باشد.

آیا این مقاله مفید بود؟