مهارت ایجنت (Agent Skill) چیست و چگونه کار می‌کند؟

مهارت ایجنت (Agent Skill) دقیقاً چیست

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

این پوشه ممکن است بیش از یک فایل داشته باشد. مشخصات Agent Skills سه دایرکتوری اختیاری را تعیین کرده است: scripts/ برای کدهایی که ایجنت اجرا می‌کند، references/ برای اسنادی که ایجنت در صورت نیاز می‌خواند، و assets/ برای قالب‌ها و داده‌ها. هیچ‌کدام از این موارد الزامی نیستند. پوشه‌ای که تنها شامل یک فایل SKILL.md باشد، یک مهارت کامل محسوب می‌شود.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

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

چرا یک مهارت تا زمانی که استفاده نشود تقریباً هزینه‌ای ندارد

این استدلالی است که درک این قالب را ارزشمند می‌کند و موضوع آن «زمینه» (context) است، نه قابلیت‌ها. بارگذاری در مراحل مختلف انجام می‌شود که در مشخصات فنی، «افشای تدریجی» (progressive disclosure) نامیده می‌شود.

در هنگام راه‌اندازی، ایجنت فقط name و description هر مهارت نصب‌شده را بارگذاری می‌کند و هیچ چیز دیگری را فراخوانی نمی‌کند. مشخصات فنی Agent Skills این مقدار را تقریباً 100 توکن برای هر مهارت تعیین کرده است (طبق راهنمای منتشرشده تا اوت 2026). اگر دوازده مهارت نصب کنید، تنها به اندازه یک پاراگراف طولانی از فضای زمینه (context) مصرف کرده‌اید.

هنگامی که یک درخواست با توضیحات مهارت مطابقت داشته باشد، ایجنت بدنه آن SKILL.md خاص را می‌خواند. مشخصات فنی توصیه می‌کند که بدنه مهارت زیر 5,000 توکن و فایل آن زیر 500 خط نگه داشته شود. فایل‌های موجود در references/ و scripts/ در این مرحله همچنان هیچ هزینه‌ای ندارند. یک فایل مرجع تنها در صورتی بارگذاری می‌شود که دستورالعمل‌ها ایجنت را به سمت آن هدایت کنند. یک اسکریپت بسته‌بندی‌شده (bundled script) وضعیت متفاوتی دارد: ایجنت آن را از طریق shell اجرا می‌کند، بنابراین کد منبع اسکریپت هرگز وارد پنجره زمینه نمی‌شود و فقط خروجی آن وارد می‌شود.

حال این موضوع را با روشی که افراد ابتدا به سراغ آن می‌روند، یعنی یک پرامپت عظیم، مقایسه کنید. هر خط در یک پرامپت سیستمی یا یک فایل دستورالعمل‌های همیشه فعال، در هر درخواست و در هر نشست (session) هزینه دارد، چه آن کار به آن دستورالعمل نیاز داشته باشد و چه نداشته باشد؛ علاوه بر این، آن دستورالعمل‌ها با پرسش اصلی برای جلب توجه مدل رقابت می‌کنند. ده هزار توکن دستورالعمل ثابت، هزینه‌ای است که حتی برای پرسیدن ساعت هم باید بپردازید. دوازده مهارت در حالت استراحت حدود 1,200 توکن هزینه دارند و فقط برای همان کاری که به آن‌ها نیاز دارد، گسترش می‌یابند. این تمام دلیل برتری مهارت‌هاست و به همین دلیل است که یک کتابخانه کوچک، بهتر از یک پرامپت طولانی عمل می‌کند.

یک نکته مهم وجود دارد که افراد را به اشتباه می‌اندازد. هنگامی که یک مهارت بارگذاری می‌شود، بدنه آن تا پایان نشست در زمینه باقی می‌ماند؛ بنابراین یک SKILL.md طولانی، یک هزینه تکرارشونده است و نه یک هزینه یک‌باره. انتقال جزئیات به references/ فقط برای مرتب‌سازی نیست؛ این دقیقاً همان مکانیزمی است که برای کارکرد صحیح طراحی شده است.

مهارت عامل (Agent Skill) یک فراخوانی ابزار نیست

یک ابزار، که به آن فراخوانی تابع (function call) نیز می‌گویند، چیزی است که مدل می‌تواند آن را اجرا کند. محیط اجرا (harness) یک طرحواره (schema) شامل نام، توضیحات و ساختار آرگومان‌ها را برای مدل ارسال می‌کند. مدل یک فراخوانی صادر می‌کند، کد شما آن را اجرا می‌کند و نتیجه به صورت یک پیام بازگردانده می‌شود. ابزارها کار انجام می‌دهند.

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

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

مهارت یک عامل (Agent Skill) یک سرور MCP نیست

پروتکل MCP (مخفف Model Context Protocol) پروتکلی برای اتصال یک عامل به سیستم‌های خارجی است. سرور MCP یک پردازش در حال اجراست که از این پروتکل استفاده می‌کند و ابزارهایی را در اختیار عامل قرار می‌دهد. این سرور معمولاً به پیکربندی، اعتبارنامه‌ها و یک دستور محلی یا یک نقطه پایانی شبکه نیاز دارد. در مقابل، یک «مهارت» (Skill) صرفاً پوشه‌ای حاوی یک فایل markdown است. در اینجا هیچ پردازش، پورت یا پروتکلی وجود ندارد.

هزینه کانتکست (Context cost) نیز به همین ترتیب متفاوت است. هر ابزاری که یک سرور MCP ارائه می‌دهد، دارای یک نام، یک توضیحات و یک طرحواره (schema) برای آرگومان‌هاست که به‌طور پیش‌فرض در درخواست‌های کل نشست (session) قرار می‌گیرند، چه از آن‌ها استفاده شود و چه نشود. برخی کلاینت‌ها شروع به فراخوانی طرحواره‌های ابزار به‌صورت درخواستی (on-demand) کرده‌اند، اما بارگذاری آن‌ها در ابتدای کار همچنان حالت معمول است. یک مهارت در حالت غیرفعال، تنها یک خط متن است.

این دو مکمل یکدیگرند و قدرتمندترین تنظیمات، هر دو را اجرا می‌کنند. سرور MCP دسترسی را فراهم می‌کند و مهارت، رویه (procedure) را ارائه می‌دهد: اینکه برای گردش‌کار واقعی تیم شما، کدام‌یک از آن ابزارها باید فراخوانی شوند، به چه ترتیبی باشند و نتیجه مطلوب چگونه است. اگر قصد دارید سرویس‌های خود را میزبانی کنید، اجرای سرورهای MCP روی یک VPS این بخش را پوشش می‌دهد.

مهارت عامل (Agent Skill) یک system prompt یا AGENTS.md نیست

هر دو مورد دستورالعمل‌هایی در قالب markdown هستند، بنابراین این سردرگمی قابل درک است. تفاوت در زمان بارگذاری آن‌هاست. AGENTS.md، CLAUDE.md و system prompt همیشه فعال هستند. اما یک مهارت (skill) در صورت نیاز فراخوانی می‌شود.

آزمون تشخیص این است: آیا نادیده گرفتن این پاراگراف در وظیفه‌ای که هیچ ارتباطی با آن ندارد، اشتباه است؟ سبک نگارش (House style)، دستور build و قانون نام‌گذاری branch برای هر وظیفه‌ای اعمال می‌شوند، بنابراین آن‌ها در فایلی قرار می‌گیرند که همیشه فعال است؛ جایی که بارگذاری همیشگی آن‌ها هدف اصلی است. چک‌لیست انتشار که دو بار در ماه اجرا می‌کنید، برای هر وظیفه‌ای کاربرد ندارد، بنابراین باید در یک مهارت قرار گیرد. زمانی که بخشی از فایل همیشه فعال شما به یک دستورالعمل شماره‌گذاری‌شده تبدیل شد، این نشانه‌ای است که باید آن را منتقل کنید.

این فایل‌ها قراردادهای خاص خود را دارند که رعایت آن‌ها ارزشمند است. برای مشاهده دو موردی که ما استفاده می‌کنیم، به آنچه در AGENTS.md قرار می‌گیرد و آنچه در فایل انسانی قرار می‌گیرد و یک design.md که ساختار یک codebase را توضیح می‌دهد مراجعه کنید.

مهارت حداقلی چگونه به نظر می‌رسد

در Claude Code، مهارت‌های شخصی در ~/.claude/skills/<name>/SKILL.md قرار دارند و برای تمام پروژه‌های شما اعمال می‌شوند. مهارت‌های پروژه در .claude/skills/<name>/SKILL.md ذخیره شده و در git کامیت می‌شوند، بنابراین هر فرد و هر عاملی (agent) که روی آن مخزن کار می‌کند، به آن‌ها دسترسی دارد. GitHub Copilot و VS Code مهارت‌های فضای کاری را از .github/skills/ می‌خوانند. فایل موجود در این مسیر، همان فایل قبلی است.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

این یک مهارت کامل است. نام دایرکتوری به دستوری تبدیل می‌شود که شما تایپ می‌کنید، بنابراین این مورد /restore-drill است. در Claude Code، منوی /skills لیست موارد نصب‌شده را نمایش می‌دهد که سریع‌ترین راه برای اطمینان از شناسایی فایل است. اگر این مورد در منو وجود ندارد، نام‌گذاری اشتباه است: فایل باید حتماً SKILL.md نامیده شود و نام دایرکتوری باید شامل حروف کوچک، اعداد و خط‌تیره‌های تکی باشد. همین دستورالعمل که به صورت یک رویه برای اجرای مجدد توسط عامل شما نوشته شده، همراهی طبیعی برای پشتیبان‌گیری زمان‌بندی‌شده restic روی یک VPS است، جایی که اجرای پشتیبان‌گیری با بازیابی آن متفاوت است.

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

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

نخست، سورس‌کد یک اسکریپت هرگز وارد context window نمی‌شود. یک پارسر 300 خطی فقط خروجی خود را به شما می‌دهد و تمام؛ در حالی که همان منطق اگر به صورت دستورالعمل‌های markdown نوشته شود، با هر بار بارگذاری مهارت، تمام طول آن متن مصرف می‌شود.

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

بنابراین کار را بر اساس نوع آن تقسیم کنید. «فایل CSV را تحلیل کن و هر ردیفی که در آن مجموع با اقلام مطابقت ندارد را چاپ کن» یک اسکریپت است. «به ردیف‌هایی که اسکریپت چاپ کرده نگاه کن و توضیح بده کدام‌یک شبیه خطای ورود داده به نظر می‌رسند» یک دستورالعمل مهارتی است. حفظ قضاوت در markdown و قطعیت در کد، همان انضباطی است که در ساخت حلقه‌ای که یک عامل می‌تواند بدون نظارت شما اجرا کند به کار می‌رود.

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

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

خطای معکوس، مهارتی است که دائماً فعال می‌شود. توضیحی مانند «برای هرگونه تغییر کد در این مخزن استفاده شود» با همه چیز تطبیق می‌یابد، بنابراین بدنه مهارت در هر تسک بارگذاری شده و تا پایان نشست در context باقی می‌ماند. توضیحات را به مورد خاصی که مد نظر دارید محدود کنید. در Claude Code می‌توانید disable-model-invocation: true را نیز در frontmatter تنظیم کنید که از بارگذاری خودکار جلوگیری کرده و مهارت را تنها زمانی که نام آن را تایپ می‌کنید، در دسترس قرار می‌دهد.

سومین خطا، مهارتی است که یک ابزار را تکرار می‌کند. دستورالعمل‌هایی که به عامل می‌گویند یک API را curl کند که سرور MCP آن قبلاً در دسترس قرار داده است، یا دستورالعمل‌هایی برای grep کردن فایل‌ها در حالی که harness یک ابزار جستجو دارد، مسیر کندتری را ایجاد کرده و دو مجموعه دستورالعمل متناقض به دست می‌دهند. مورد تکراری را حذف کرده و به جای آن، هدف (intent) را توصیف کنید.

حدس نزنید که کدام‌یک از این سه مورد مشکل شماست. همان prompt را دو بار در یک نشست تازه اجرا کنید؛ یک بار با مهارت فعال و یک بار با مهارت غیرفعال، سپس پاسخ‌ها را مقایسه کنید. نشست تازه اهمیت دارد، زیرا نشستی که در آن مهارت را نوشته‌اید، از قبل شامل تمام گفته‌های آن مهارت است و این موضوع باعث پنهان ماندن شکاف‌های موجود در نسخه مکتوب می‌شود. افزونه skill-creator شرکت Anthropic این مقایسه را در داخل Claude Code خودکار می‌کند، که شامل تولید promptهایی است که باید یا نباید مهارت را فعال کنند و اندازه‌گیری میزان دفعات فعال شدن آن است.

آیا این فرمت متعلق به یک فروشنده خاص است یا یک استاندارد محسوب می‌شود؟

شرکت Anthropic این فرمت را در اواخر سال 2025 منتشر کرد و سپس آن را به عنوان یک استاندارد باز در agentskills.io قرار داد. تا اوت 2026، این مشخصات، فیلدهای الزامی name و description، فیلدهای اختیاری license، compatibility، metadata و allowed-tools، سه دایرکتوری اختیاری و رفتار بارگذاری مرحله‌ای (staged loading) را تعریف کرده است. این استاندارد همچنین شامل یک اعتبارسنج مرجع است، بنابراین می‌توانید پیش از اشتراک‌گذاری یک پوشه، آن را با استفاده از skills-ref validate ./my-skill بر اساس مشخصات فنی بررسی کنید.

لیست کلاینت‌ها نشان‌دهنده واقعی وضعیت است. یک پوشه واحد توسط ابزارهایی نظیر Claude Code، Cursor، OpenAI Codex، Gemini CLI، GitHub Copilot، VS Code، Goose، OpenHands و opencode خوانده می‌شود. مایکروسافت مهارت‌های اختصاصی خود را با این فرمت در github.com/microsoft/skills منتشر می‌کند و ابزاری دسکتاپی به نام Skill Recorder ارائه می‌دهد که عملکرد شما در انجام یک وظیفه را مشاهده کرده، آن را به صورت یک هدف (intent) به همراه مراحل مرتب‌شده بازسازی می‌کند و نتیجه را به عنوان یک مهارت ذخیره می‌نماید. وقتی یک فروشنده ابزاری برای ضبط می‌سازد که خروجی آن با مشخصات فنی شخص دیگری مطابقت دارد، نشانه خوبی است که این فرمت دیگر صرفاً یک قابلیت برای یک محصول خاص نیست.

نخستین گام‌ها برای نوشتن

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

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

FAQ

تفاوت بین مهارت عامل (agent skill) و سرور MCP چیست؟

یک سرور MCP (مخفف Model Context Protocol) یک پردازش در حال اجرا است که ابزارها را از طریق یک پروتکل در اختیار عامل قرار می‌دهد؛ بنابراین به پیکربندی و اعتبارنامه نیاز دارد و تعاریف ابزارهای آن معمولاً در تمام طول نشست (session) بخشی از context را اشغال می‌کنند، فارغ از اینکه استفاده شوند یا خیر. مهارت عامل یک پوشه است که شامل یک فایل SKILL.md است، هیچ پردازش یا پروتکلی ندارد و تا زمانی که عامل تصمیم به خواندن آن نگیرد، حدود 100 توکن هزینه دارد. برای دسترسی دادن به یک عامل جهت کار با یک سیستم، از سرور MCP استفاده کنید. برای آموزش رویهٔ استفادهٔ صحیح از آن دسترسی به عامل، از مهارت استفاده کنید. بسیاری از تنظیمات از هر دو استفاده می‌کنند.

آیا مهارت‌های عامل فقط با Claude Code کار می‌کنند؟

خیر. Anthropic این فرمت را توسعه داد و سپس آن را به عنوان یک استاندارد باز در agentskills.io منتشر کرد. همان پوشه توسط Cursor، OpenAI Codex، Gemini CLI، GitHub Copilot، VS Code، Goose، OpenHands و سایر کلاینت‌ها خوانده می‌شود. تفاوت در این است که هر کلاینت کجا را جستجو می‌کند و کدام فیلدهای اضافی frontmatter را درک می‌کند. Claude Code فایل‌های ~/.claude/skills/ و .claude/skills/ را می‌خواند، در حالی که GitHub Copilot و VS Code فایل .github/skills/ را در مخزن (repository) می‌خوانند. خود فایل SKILL.md بدون تغییر بین آن‌ها جابه‌جا می‌شود.

قبل از اینکه سرعت سیستم کاهش یابد، چند مهارت می‌توانم نصب کنم؟

محدودیت اصلی مربوط به بودجهٔ راه‌اندازی (startup budget) است، نه تعداد مهارت‌ها. هر مهارت نصب‌شده، نام و توضیحات خود را اضافه می‌کند که طبق راهنمای منتشرشدهٔ استاندارد، حدود 100 توکن است؛ بنابراین سی مهارت حدود 3,000 توکن هزینه دارند، حتی پیش از آنکه از هیچ‌کدام استفاده شود. آنچه زودتر از سرعت دچار افت می‌شود، تطبیق‌پذیری (matching) است: وجود مهارت‌های زیاد با توضیحات هم‌پوشان، انتخاب مهارت درست را برای مدل دشوارتر می‌کند. توضیحاتی بنویسید که هم‌پوشانی نداشته باشند و مهارت‌هایی را که دیگر استفاده نمی‌کنید، حذف کنید.

آیا این دستورالعمل باید در یک مهارت قرار بگیرد یا در AGENTS.md؟

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