Agent Skills چیست؟ آموزش ساخت Skill قابل‌حمل برای عامل‌های هوش مصنوعی
Agent Skills روشی استاندارد برای بسته‌بندی دستورالعمل، اسکریپت، نمونه و منابع یک کار تکراری است. در این راهنما یک Skill امن و قابل‌حمل با SKILL.md طراحی، تست و نگهداری می‌کنیم.
اگر هر بار برای Agent توضیح می‌دهید پروژه چگونه تست می‌شود، Release چه مراحلی دارد یا گزارش امنیتی با چه قالبی نوشته می‌شود، احتمالاً به یک Prompt طولانی‌تر نیاز ندارید؛ به یک Skill نیاز دارید. Agent Skills یک روش فایل‌محور برای بسته‌بندی دانش اجرایی است تا عامل هوش مصنوعی آن را هنگام کار مرتبط پیدا کند و فقط بخش لازم را بخواند.
یک Skill معمولاً پوشه‌ای شامل فایل SKILL.md است و می‌تواند اسکریپت، Template، مثال و Reference نیز داشته باشد. مزیت اصلی آن تکرارپذیری است: فرایندی که امروز در یک گفت‌وگو توضیح داده‌اید، فردا برای عضو دیگر تیم یا Agent سازگار نیز قابل استفاده خواهد بود.
Agent Skills چیست و چه مسئله‌ای را حل می‌کند؟
Skill را می‌توان راهنمای عملیاتی یک متخصص دانست. به‌جای اینکه همه دانش پروژه در Prompt اصلی جا داده شود، Agent ابتدا نام و توضیح کوتاه Skillها را می‌بیند. وقتی درخواست کاربر با توضیح یک Skill تطابق داشته باشد، دستورالعمل کامل آن بارگذاری می‌شود و منابع جانبی فقط در صورت نیاز خوانده یا اجرا می‌شوند.
این الگو به کاهش تکرار، کوچک ماندن Context و استانداردشدن خروجی کمک می‌کند. Skill برای کاری مناسب است که چند مرحله مشخص، قواعد ثابت و خروجی قابل ارزیابی دارد؛ مانند اجرای Integration Test، ساخت Migration، آماده‌سازی Release note یا بررسی Pull Request.
| نیاز | انتخاب مناسب | دلیل |
|---|---|---|
| قانون همیشگی کدنویسی | Custom Instructions | در همه درخواست‌های مرتبط اعمال می‌شود |
| فرایند چندمرحله‌ای تکراری | Agent Skill | دستورالعمل و منابع را یکجا و هنگام نیاز بارگذاری می‌کند |
| اتصال به API یا پایگاه داده | MCP یا Tool | قابلیت دسترسی بیرونی و قرارداد فراخوانی می‌دهد |
| نقش تخصصی با ابزار محدود | Custom Agent | هویت، Scope و ابزارهای یک نقش را تعریف می‌کند |
| درخواست یک‌باره | Prompt | هزینه نگهداری بسته دائمی لازم نیست |
Skill و MCP رقیب یکدیگر نیستند. Skill می‌تواند روش درست استفاده از ابزار MCP را توضیح دهد، اما خودش لزوماً اتصال شبکه یا Credential ایجاد نمی‌کند. برای آشنایی با این مرز، راهنمای امن MCP Server را هم ببینید.
ساختار استاندارد یک Skill
حداقل ساختار، یک پوشه با نام مشخص و فایل SKILL.md است. در ابتدای فایل، YAML frontmatter قرار می‌گیرد. فیلد name شناسه Skill و description مهم‌ترین سیگنال برای تشخیص زمان فعال‌شدن آن است. متن بدنه نیز مراحل، محدودیت‌ها، معیار پایان و مسیر منابع را شرح می‌دهد.
---name: release-checkdescription: Validate a release candidate before publishing.--- # Release checkUse this skill before a production release.Run tests, inspect the diff, and stop on any failed gate.نام و description را چگونه بنویسیم؟
نام باید کوتاه، یکتا و با نام پوشه هماهنگ باشد. برای سازگاری بهتر از حروف کوچک انگلیسی، عدد و خط تیره استفاده کنید. توضیح باید هم توانایی و هم زمان استفاده را روشن کند. عبارت کلی «برای کارهای پروژه» سیگنال ضعیفی است؛ عبارت «پیش از انتشار Production، تست، Migration و Rollback plan را کنترل می‌کند» دقیق‌تر است.
در description کلمه‌هایی را قرار دهید که کاربر واقعاً در درخواست خود می‌نویسد، اما فهرست Keyword نسازید. هدف، تشخیص معنایی درست است. اگر Skill بی‌دلیل فعال می‌شود، توضیح را محدودتر کنید؛ اگر فعال نمی‌شود، نشانه‌های واقعی درخواست و مرز استفاده را اضافه کنید.
چه فایل‌هایی کنار SKILL.md قرار می‌گیرند؟
- scripts: فرمان‌های قطعی برای اعتبارسنجی، تبدیل یا ساخت خروجی.
- references: قرارداد API، Schema، Policy یا راهنمایی که فقط هنگام نیاز باید خوانده شود.
- templates: اسکلت خروجی مانند Issue، Report یا فایل تنظیمات.
- examples: نمونه ورودی و خروجی خوب برای کم‌کردن ابهام.
- assets: فایل ثابت موردنیاز خروجی، نه داده محرمانه یا Credential.
هر فایل جانبی را با مسیر نسبی و دلیل استفاده در SKILL.md معرفی کنید. انباشتن فایل‌هایی که Agent نمی‌داند چه زمانی باید بخواند، هم Context را هدر می‌دهد و هم نتیجه را غیرقابل پیش‌بینی می‌کند.
افشای تدریجی چگونه Context را کنترل می‌کند؟
در معماری Skills، اطلاعات مرحله‌ای وارد Context می‌شود. Metadata برای کشف همیشه سبک می‌ماند؛ بدنه SKILL.md فقط پس از انتخاب Skill خوانده می‌شود؛ و فایل‌های بزرگ‌تر هنگامی باز می‌شوند که همان مرحله به آن‌ها احتیاج دارد. این روش را Progressive Disclosure یا افشای تدریجی می‌نامند.
بنابراین بدنه Skill نباید نسخه فشرده کل Wiki تیم باشد. مسیر تصمیم‌گیری و مراحل اصلی را در فایل اصلی نگه دارید، جزئیات تخصصی را به Reference جدا منتقل کنید و خروجی حجیم ابزار را خلاصه کنید. هر بخش باید پاسخ دهد: چه زمانی خوانده شود، چه کاری انجام شود و موفقیت چگونه سنجیده شود.
طراحی اولین Agent Skill به‌صورت مرحله‌ای
- یک کار تکراری، محدود و قابل سنجش انتخاب کنید؛ مثلاً بررسی آمادگی Release.
- ورودی‌های لازم، خروجی مورد انتظار و شرایط توقف را بنویسید.
- مراحل تصمیم‌گیری را از دستورهای قطعی جدا کنید.
- پوشه Skill و
SKILL.mdرا بسازید و description دقیق بنویسید. - اسکریپت و Template را فقط وقتی اضافه کنید که واقعاً تکرار یا خطا را کاهش می‌دهد.
- همه مسیرها را نسبی و مستقل از سیستم شخصی نگه دارید.
- یک درخواست مثبت و چند درخواست نامرتبط برای تست Trigger آماده کنید.
- خروجی، Diff، فرمان‌ها و Failure path را بازبینی کنید.
- Skill را Version control کنید و تغییر رفتاری را در Review تیمی قرار دهید.
نمونه سناریوی مناسب برای اولین Skill
فرض کنید تیم پیش از انتشار باید نسخه Package، تست‌ها، Migration، Secret scan و Rollback plan را کنترل کند. Skill می‌تواند ترتیب این بررسی‌ها را تعریف کند، یک اسکریپت فقط‌خواندنی برای جمع‌آوری وضعیت داشته باشد و Template گزارش را تحویل دهد. اگر هر Gate شکست خورد، دستورالعمل باید انتشار را متوقف کند و دلیل را گزارش دهد؛ نه اینکه Gate را خاموش کند.
معیار پایان باید شفاف باشد
عبارت «همه چیز را بررسی کن» قابل آزمون نیست. بهتر است پایان کار با شروط روشن تعریف شود: فرمان تست با Exit code صفر تمام شده، فایل Migration بازبینی شده، Secret تازه‌ای در Diff نیست و Rollback plan وجود دارد. Agent باید موارد بررسی‌نشده را صریحاً با وضعیت نامعلوم گزارش کند.
تست فعال‌سازی و کیفیت Skill
Skill خوب فقط متن خوبی ندارد؛ رفتار قابل پیش‌بینی دارد. ابتدا با درخواست دقیقی که باید Skill را فعال کند آزمایش کنید. سپس عبارت متفاوتی با همان Intent بنویسید. در مرحله بعد درخواست نزدیک اما خارج از Scope را بدهید تا مطمئن شوید Skill بی‌دلیل وارد Context نمی‌شود.
| آزمون | انتظار | نشانه مشکل |
|---|---|---|
| درخواست مستقیم | Skill انتخاب و مراحل اجرا شود | description بیش از حد مبهم است |
| عبارت هم‌معنی | همان Skill پیدا شود | توضیح به یک کلیدواژه وابسته است |
| درخواست نامرتبط | Skill بارگذاری نشود | Scope بیش از حد گسترده است |
| ورودی ناقص | توقف یا سؤال هدفمند | Agent با حدس خطرناک ادامه می‌دهد |
| شکست اسکریپت | خطا و اثر آن گزارش شود | Failure پنهان یا نادیده گرفته می‌شود |
| اجرای دوباره | نتیجه پایدار یا Idempotent | تغییر ناخواسته تکرار می‌شود |
در ابزارهایی مانند VS Code و Copilot CLI، مسیرهای کشف Skill و قابلیت‌های اضافی ممکن است با نسخه تغییر کنند. مستندات همان Client را مرجع نهایی قرار دهید و صرفاً به قابل‌حمل بودن قالب برای یکسان‌بودن همه رفتارها تکیه نکنید. اگر Agent را از ترمینال اجرا می‌کنید، راهنمای نصب و استفاده امن GitHub Copilot CLI نیز مفید است.
امنیت Agent Skills؛ فایل راهنما هم کد محسوب می‌شود
Skill می‌تواند Agent را به خواندن فایل، اجرای Script، دسترسی شبکه یا استفاده از Tool هدایت کند. بنابراین Skill دریافتی از Repository عمومی را مانند Dependency بررسی کنید. متن Markdown بی‌خطر به نظر می‌رسد، اما ممکن است دستور حذف فایل، ارسال داده یا دورزدن Approval داشته باشد.
- منبع و تاریخ آخرین تغییر Skill را بررسی کنید.
- تمام Scriptها و مسیرهای فراخوانی‌شده را پیش از اجرا بخوانید.
- Secret، Token و فایل
.envرا داخل Skill قرار ندهید. - دسترسی Agent را به کمترین فایل، فرمان و شبکه لازم محدود کنید.
- برای فرمان‌های تغییردهنده Approval انسانی نگه دارید.
- Skill خارجی را Pin و تغییر نسخه را در Code Review بررسی کنید.
- ورودی و خروجی حساس را Log نکنید و از داده واقعی برای تست اولیه استفاده نکنید.
اگر Skill از MCP یا ابزار بیرونی استفاده می‌کند، مجوز هر دو لایه مهم است. Skill می‌گوید Agent چه کار کند و Tool تعیین می‌کند واقعاً به چه چیزی دسترسی دارد. محدودیت فقط در متن دستورالعمل، کنترل امنیتی قطعی نیست.
قابل‌حمل بودن؛ چه چیزی واقعاً منتقل می‌شود؟
استاندارد پوشه و SKILL.md انتقال دانش را ساده می‌کند، اما همه Clientها دقیقاً یک قابلیت ندارند. مسیر کشف، فیلدهای اختیاری، Slash command، Sandbox، مدل Permission و اجرای Script ممکن است متفاوت باشد. بخش مشترک را استاندارد نگه دارید و نکات Client-specific را در Reference جدا بنویسید.
از مسیر مطلق ویندوز یا macOS، نام کاربری، Dependency نصب‌نشده و فرض دسترسی Administrator پرهیز کنید. پیش‌نیازها را صریح بنویسید، فرمان بررسی محیط داشته باشید و در صورت نبود Dependency با پیام روشن متوقف شوید. این رفتار از اجرای ناقص و تغییر نیمه‌تمام جلوگیری می‌کند.
نگهداری و نسخه‌بندی Skill در تیم
Skill بخشی از فرایند مهندسی است و باید Owner، Review و تاریخچه تغییر داشته باشد. وقتی Build command، ساختار Repository یا Policy انتشار عوض می‌شود، Skill قدیمی می‌تواند خروجی ظاهراً معتبر اما اشتباه تولید کند. برای هر Skill یک مسئول، دامنه پشتیبانی و آزمون دوره‌ای تعیین کنید.
تغییر description نیز تغییر رفتاری است، چون زمان فعال‌شدن Skill را عوض می‌کند. در Pull Request علاوه بر متن، نمونه Triggerهای مثبت و منفی را ثبت کنید. اگر Script تغییر کرده، خروجی Dry run و مجوزهای تازه را بررسی کنید.
اشتباه‌های رایج در ساخت Agent Skill
- Scope بسیار بزرگ: یک Skill همه کارهای توسعه را پوشش می‌دهد و انتخاب آن غیرقابل پیش‌بینی می‌شود.
- description مبهم: Agent نمی‌فهمد چه زمانی بسته را بارگذاری کند.
- دفن‌کردن دستور مهم در Reference: Agent ممکن است فایل را در زمان لازم نخواند.
- وابستگی پنهان به محیط: Skill فقط روی لپ‌تاپ سازنده کار می‌کند.
- اجرای Script بدون بازبینی: زنجیره تأمین دستورالعمل به مسیر حمله تبدیل می‌شود.
- نبود Failure path: Agent پس از شکست Gate با حدس یا دورزدن آن ادامه می‌دهد.
- اعتماد به خروجی بدون Verification: اجرای Skill جای تست و Review مستقل را نمی‌گیرد.
جمع‌بندی
Agent Skills راهی منظم برای تبدیل دانش پراکنده تیم به قابلیت قابل استفاده مجدد است. یک پوشه کوچک با SKILL.md دقیق می‌تواند Context را سبک‌تر، خروجی را یکدست‌تر و فرایند تکراری را قابل آزمون کند. ارزش Skill از تعداد فایل‌های آن نمی‌آید؛ از Scope روشن، Trigger درست، معیار پایان و کنترل دسترسی می‌آید.
از یک کار کم‌ریسک شروع کنید، رفتار مثبت و منفی را تست کنید و Scriptهای همراه را مانند کد Production بازبینی کنید. سپس Skill را همراه Repository نسخه‌بندی و برای Clientهای هدف به‌صورت جدا اعتبارسنجی کنید.
امروز یک فرایند تکراری و کم‌ریسک تیم را انتخاب کنید، پوشه Skill و فایل SKILL.md آن را بسازید و پیش از اشتراک‌گذاری، فعال‌سازی، Failure path و همه اسکریپت‌های همراه را در یک مخزن آزمایشی بررسی کنید.