# راهنمای Skills در Claude Code (SKILL.md) > **آخرین بازبینی**: 2026-10-20 · 📄 طبق مستندات رسمی (Claude Code Skills) یک Skill فایلی به نام `SKILL.md` است: فراداده YAML بین نشانگرهای `---` که به Claude می‌گوید چه زمانی از آن استفاده کند، به‌همراه دستورالعمل‌های Markdown که Claude هنگام اجرا از آن‌ها پیروی می‌کند. Claude وقتی Skills مرتبط باشند از آن‌ها استفاده می‌کند، یا می‌توانید یکی را مستقیماً با `/skill-name` فراخوانی کنید. Skills اجزای لایه دانش در Claude Code هستند که تخصص و راهنمایی حوزه‌محور را در اختیار Claude قرار می‌دهند. Claude آن‌ها را هنگام مرتبط بودن به‌طور خودکار بارگذاری می‌کند و شما هم می‌توانید یکی را مستقیماً با `/skill-name` فراخوانی کنید. ## Skills چیست؟ Skills ماژول‌های دانش تخصصی هستند که در فایل‌های `SKILL.md` ذخیره می‌شوند: - **فعال‌سازی خودکار**: Claude بر اساس زمینه وظیفه از Skills مرتبط به‌طور خودکار استفاده می‌کند - **دانش حوزه‌ای**: بهترین شیوه‌ها و راهنمایی را برای حوزه‌های مشخص ارائه می‌دهد - **قابل توسعه**: Skills سفارشی را برای برآورده کردن نیازهای مشخص ایجاد کنید - **آگاه به زمینه**: فقط در سناریوهای مرتبط فراخوانی می‌شود ### Skills در برابر Commands در برابر Agents | مؤلفه | محرک | هدف | |-----------|---------|---------| | **Commands** | کاربر به‌صورت دستی فراخوانی می‌کند (`/command`) | اجرای وظایف مشخص | | **Skills** | فعال‌سازی خودکار یا `/skill-name` | ارائه دانش حوزه‌ای | | **Agents** | فراخوانی‌های واگذارشده | مدیریت گردش‌کارهای پیچیده | ### Skills، Commands و CLAUDE.md (بازبینی 2026-10-20) Skills در Claude Code از استاندارد باز Agent Skills پیروی می‌کنند که در چندین ابزار هوش مصنوعی کار می‌کند. Commands سفارشی در Skills ادغام شده‌اند: یک فایل در `.claude/commands/deploy.md` و یک Skill در `.claude/skills/deploy/SKILL.md` هر دو `/deploy` را می‌سازند و به یک شکل کار می‌کنند. برخلاف محتوای `CLAUDE.md`، بدنه یک Skill فقط هنگام استفاده بارگذاری می‌شود، بنابراین مطالب مرجع طولانی تا زمانی که به آن نیاز نداشته باشید تقریباً هیچ هزینه‌ای ندارد. ## استفاده از Skills داخلی افزونه‌های Claude Code معمولاً چندین Skill داخلی دارند. وقتی وظیفه شما با توضیحات یک Skill مطابقت داشته باشد، Claude به‌طور خودکار از آن استفاده می‌کند. Claude Code همچنین مجموعه‌ای از Skills همراه را شامل می‌شود، مانند `/doctor`، `/code-review`، `/batch`، `/debug`، `/loop` و `/claude-api` (بازبینی 2026-10-20). یک Skill همراه را مانند هر Skill دیگری فراخوانی می‌کنید: `/` را تایپ کنید و سپس نام Skill را بنویسید. ### مثال: بازبینی کد وقتی می‌گویید «کمکم کن این کد را از نظر مسائل امنیتی بررسی کنم»، اگر افزونه‌ای با Skill بازبینی امنیتی نصب شده باشد، Claude به‌طور خودکار دانش آن Skill را برای بازبینی به کار می‌گیرد. ### مشاهده Skills موجود Skills معمولاً همراه افزونه‌ها نصب می‌شوند: ```bash # Install plugin (plugins may contain multiple Skills) /plugin install plugin-name@marketplace ``` ## ساخت Skillهای سفارشی ### ساختار پایه ساده‌ترین Skill فقط به یک فایل `SKILL.md` نیاز دارد: ```bash my-skill/ └── SKILL.md ``` ### قالب SKILL.md ```markdown --- name: Code Style Guide description: Use this skill when the user asks about "code style", "naming conventions", "code formatting", or discusses coding standards --- # Code Style Guide ## Naming Conventions - Variables use camelCase - Constants use UPPER_SNAKE_CASE - Classes use PascalCase - Private members use underscore prefix ## Formatting Rules - Use 2 spaces for indentation - Line width should not exceed 80 characters - Use trailing commas ## Best Practices - Functions should have single responsibility - Avoid deep nesting - Use meaningful variable names ``` ### فیلدهای Frontmatter همه فیلدها اختیاری‌اند. فقط `description` توصیه می‌شود تا Claude بداند چه زمانی از Skill استفاده کند؛ `name` را می‌توان حذف کرد و به‌طور پیش‌فرض نام پوشه است. نام فیلد باید دقیقاً با مرجع رسمی frontmatter مطابقت داشته باشد، شامل خط تیره‌ها (جدول زیر فقط فیلدهای رایج را فهرست می‌کند؛ مستندات رسمی نیز `model`، `effort`، `hooks`، `user-invocable` و موارد بیشتر را پوشش می‌دهد): Claude Code فیلدی را که تشخیص نمی‌دهد، بدون گزارش خطا نادیده می‌گیرد (بررسی‌شده در 2026-10-20). | فیلد | الزامی | توضیح | |-------|----------|-------------| | `name` | خیر | نام فرمانی که در منوی `/` نمایش داده می‌شود؛ به‌طور پیش‌فرض نام پوشه است | | `description` | توصیه‌شده | این‌که Skill چه کاری انجام می‌دهد و چه زمانی باید از آن استفاده کرد؛ Claude از این فیلد برای تصمیم‌گیری درباره زمان اعمال Skill استفاده می‌کند | | `when_to_use` | خیر | زمینه تکمیلی برای این‌که Claude چه زمانی باید Skill را فراخوانی کند، مانند عبارت‌های محرک یا درخواست‌های نمونه؛ در فهرست Skill به `description` افزوده می‌شود | | `argument-hint` | خیر | راهنمایی که هنگام تکمیل خودکار برای نشان دادن آرگومان‌های مورد انتظار نمایش داده می‌شود، مانند `[issue-number]` یا `[filename] [format]` | | `disable-model-invocation` | خیر | برای جلوگیری از بارگذاری خودکار این Skill توسط Claude، آن را روی `true` تنظیم کنید؛ از آن برای گردش‌کارهایی استفاده کنید که به‌صورت دستی با `/name` اجرا می‌کنید | | `allowed-tools` | خیر | ابزارهایی که Claude می‌تواند در طول نوبتی که این Skill را فراخوانی می‌کند، بدون درخواست مجوز استفاده کند | | `paths` | خیر | الگوهای Glob که زمان فعال‌شدن این Skill را محدود می‌کنند، تا Claude آن را به‌طور خودکار فقط هنگام کار با فایل‌های مطابق بارگذاری کند | | `context` | خیر | برای اجرا در بافت یک زیرعامل fork‌شده، آن را روی `fork` تنظیم کنید | `version` در این جدول فیلد نیست: Claude Code فیلدی را که تشخیص نمی‌دهد، بدون گزارش خطا نادیده می‌گیرد (بررسی‌شده در 2026-10-20). ### نوشتن توضیحات مؤثر فیلد description تعیین می‌کند چه زمانی یک Skill فعال می‌شود و باید شامل عبارت‌های محرک مشخص باشد: **مثال خوب**: ```yaml description: Use this skill when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events ``` **مثال بد**: ```yaml description: Guide about hooks # Too vague ``` ## ساختار کامل Skill برای Skillsهای پیچیده می‌توانید منابع بیشتری بگنجانید: ```bash my-skill/ ├── SKILL.md # Main knowledge document ├── references/ # Detailed references │ ├── patterns.md # Design patterns │ └── advanced.md # Advanced techniques ├── examples/ # Example code │ ├── basic.ts # Basic example │ └── advanced.ts # Advanced example └── scripts/ # Helper scripts └── validate.sh # Validation script ``` ### ارجاع به منابع در SKILL.md به منابع دیگر ارجاع دهید: ```markdown --- name: API Development Guide description: Use when the user asks about "API design", "REST interfaces", "API best practices" --- # API Development Guide See @references/patterns.md for detailed API design patterns ## Quick Example See @examples/basic.ts for basic usage ``` ### تزریق زمینه پویا خطی مانند `` !`git diff HEAD` `` از تزریق زمینه پویا استفاده می‌کند: Claude Code دستور را اجرا می‌کند و پیش از آن‌که Claude محتوای Skill را ببیند، خط را با خروجی آن جایگزین می‌کند، بنابراین دستورالعمل‌ها با diff فعلی که از پیش درون‌خطی شده است می‌رسند (تأییدشده در 2026-10-20). ### محل بارگذاری Skills - **Skills شخصی** در `~/.claude/skills//SKILL.md` قرار دارند. - **Skills پروژه** در `.claude/skills//SKILL.md` درون مخزن قرار دارند. - **Skills افزونه** در `/skills//SKILL.md` درون افزونه قرار دارند. ## استفاده از Skills در افزونه‌ها ### ساختار دایرکتوری Skills در پوشه `skills/` افزونه قرار می‌گیرند: ```bash my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ # Command layer ├── agents/ # Agent layer └── skills/ # Knowledge layer ├── code-style/ │ └── SKILL.md └── api-docs/ ├── SKILL.md └── references/ ``` ### ارجاع به Skills در دستورها دستورها می‌توانند به‌صراحت به دانش Skill ارجاع دهند: ```markdown --- description: Generate standards-compliant API documentation argument-hint: [api-file] --- Generate API documentation for @$1. Use the api-docs skill to ensure documentation includes: - Complete endpoint descriptions - Parameter specifications - Response formats - Error codes - Usage examples ``` ## نمونه‌های عملی ### نمونه 1: Skill استانداردهای پروژه ```markdown --- name: Project Standards description: Use when the user asks about "project structure", "file organization", "directory conventions" --- # Project Standards ## Directory Structure \`\`\` src/ ├── components/ # React components ├── hooks/ # Custom Hooks ├── services/ # API services ├── utils/ # Utility functions └── types/ # TypeScript types \`\`\` ## File Naming - Components: PascalCase (e.g., `UserProfile.tsx`) - Utilities: camelCase (e.g., `formatDate.ts`) - Constants: UPPER_SNAKE_CASE (e.g., `API_ENDPOINTS.ts`) ## Import Order 1. React related 2. Third-party libraries 3. Internal modules 4. Type definitions 5. Style files ``` ### نمونه 2: Skill گردش‌کار Git ```markdown --- name: Git Workflow description: Use when the user asks about "branch strategy", "commit conventions", "Git process" --- # Git Workflow Standards ## Branch Naming - Features: `feature/description` - Fixes: `fix/description` - Hotfixes: `hotfix/description` ## Commit Message Format \`\`\` ():