آموزش نوشتن Agent Skill اختصاصی برای هوش مصنوعی

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

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

این ترتیب اهمیت دارد. مهارتی که از روی تخیل نوشته شود، مشکلی را مستند می‌کند که هرگز با آن مواجه نشده‌اید و با این حال، در هر نشست (session) بخشی از 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 تست کنید و سپس آن را به‌جای restart با reload اعمال کنید. یک هفته بعد، در یک وظیفه متفاوت، همان اشتباه تکرار می‌شود. آن بار دوم، نشانه است.

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

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

برای یک نمونه عملی از همین خلاصه‌سازی، 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).

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

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

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

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

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

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

فیلد 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) اضافی و درخواست‌های نمونه وجود دارد که تحت همان محدودیت به توصیف اضافه می‌شود.

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

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

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

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

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

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

اگر مهارت به عامل (agent) دستور می‌دهد که یک اسکریپت بسته‌بندی‌شده را اجرا کند، مسیر را با ${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 *)
---

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

نحوه اثبات فعال شدن یک skill

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

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

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

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

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

یک skill می‌تواند به جای واگذاری به یک اجرای ارزیابی جداگانه، اثبات خود را نیز به همراه داشته باشد؛ همان کاری که skill 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 فراخوانی کنید تا عامل (agent) هرگز به‌تنهایی تصمیم نگیرد که اکنون زمان مناسبی برای deploy است.

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

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

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

Share it once it has earned its place

A skill that survives a week of real work is worth committing. Project skills in .claude/skills/ are reviewed like code and arrive with the repository, so a teammate who clones it gets your correction with no setup step. Moving a skill between repositories without copy and paste is its own problem, covered in how to share agent skills across repos.

One portability note. Claude Code accepts a long list of frontmatter fields, but the Agent Skills standard allows only six: name, description, license, compatibility, metadata and allowed-tools. Upload a skill to claude.ai, or package it for the Skills API, with anything else in the frontmatter, and it fails outright instead of ignoring the field:

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

Stay inside those six fields and the same file loads in Claude Code and in everything else that reads the standard. Where the file loads still decides what it can do, because Cowork runs in an Anthropic sandbox while Claude Code runs on your own machine or VPS, so the nginx skill above is worth carrying to a teammate's checkout and pointless in a sandbox that cannot reach the server. Writing the instructions themselves so they survive the move to a different model is a separate job, and writing skills that work with any model covers it.

FAQ

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

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

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

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

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

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

چگونه بفهمم که یک مهارت واقعاً کمک کرده است؟

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

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

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