راهنمای Skills در Claude Code (SKILL.md)

ساخت و استفاده از Skills در Claude Code: ساختار SKILL.md، فیلدهای فراداده، مکان‌های بارگذاری، فراخوانی خودکار و با /skill-name، و Skills همراه (2026).

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

آخرین بازبینی: 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¶

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 معمولاً همراه افزونه‌ها نصب می‌شوند:

# Install plugin (plugins may contain multiple Skills)
/plugin install plugin-name@marketplace

ساخت Skillهای سفارشی¶

ساختار پایه¶

ساده‌ترین Skill فقط به یک فایل SKILL.md نیاز دارد:

my-skill/
└── SKILL.md

قالب SKILL.md¶

---
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).

version در این جدول فیلد نیست: Claude Code فیلدی را که تشخیص نمی‌دهد، بدون گزارش خطا نادیده می‌گیرد (بررسی‌شده در 2026-10-20).

نوشتن توضیحات مؤثر¶

فیلد description تعیین می‌کند چه زمانی یک Skill فعال می‌شود و باید شامل عبارت‌های محرک مشخص باشد:

مثال خوب:

description: Use this skill when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events

مثال بد:

description: Guide about hooks  # Too vague

ساختار کامل Skill¶

برای Skillsهای پیچیده می‌توانید منابع بیشتری بگنجانید:

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 به منابع دیگر ارجاع دهید:

---
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-name>/SKILL.md قرار دارند.
• Skills پروژه در .claude/skills/<skill-name>/SKILL.md درون مخزن قرار دارند.
• Skills افزونه در <plugin>/skills/<skill-name>/SKILL.md درون افزونه قرار دارند.

استفاده از Skills در افزونه‌ها¶

ساختار دایرکتوری¶

Skills در پوشه skills/ افزونه قرار می‌گیرند:

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 ارجاع دهند:

---
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 استانداردهای پروژه¶

---
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¶

---
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

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

### Type Values

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code formatting
- `refactor`: Refactoring
- `test`: Testing
- `chore`: Build/tooling

نمونه 3: Skill بازبینی امنیتی¶

---
name: Security Review
description: Use when the user asks about "security check", "vulnerability scan", "security best practices", or reviewing code security
---

# Security Review Guide

## Common Vulnerability Checks

### SQL Injection

- Check for parameterized queries
- Avoid string concatenation in SQL

### XSS Attacks

- Check if user input is escaped
- Use CSP headers

### Sensitive Data

- Ensure passwords are not stored in plaintext
- Don't hardcode API keys
- Check logs for sensitive data leaks

## Review Checklist

- [ ] Input validation
- [ ] Output encoding
- [ ] Authentication mechanism
- [ ] Authorization checks
- [ ] Encryption usage
- [ ] Error handling

بهترین شیوه‌ها¶

1. توضیحات واضح برای محرک‌ها¶

از عبارت‌های محرک مشخص استفاده کنید، نه توضیحات مبهم:

# Good
description: Use when the user asks about "create component", "React component template", "component best practices"

# Bad
description: React component related

2. دانش ساختاریافته¶

دانش را در سلسله‌مراتب واضح سازماندهی کنید:

• از سطوح عنوان استفاده کنید

• نمونه‌های کد ارائه دهید

• فهرست‌های بررسی را بگنجانید

3. به‌روز نگه دارید¶

• محتوای Skill را به‌طور منظم به‌روزرسانی کنید

• شماره‌های نسخه تغییرات را بازتاب می‌دهند

• به‌روزرسانی‌های مهم را مستند کنید

4. طراحی ماژولار¶

• هر Skill بر یک حوزه تمرکز می‌کند

• از پوشه references برای مطالب تفصیلی استفاده کنید

• نمونه‌های عملی ارائه دهید

اشکال‌زدایی Skill‌ها¶

اگر یک Skill همان‌طور که انتظار دارید فعال نمی‌شود:

1. توضیحات را بررسی کنید: مطمئن شوید عبارت‌های محرک با ورودی کاربر مطابقت دارند

2. قالب را بررسی کنید: مطمئن شوید بخش آغازین YAML به‌درستی قالب‌بندی شده است

3. محرک‌ها را آزمایش کنید: عبارت‌های دقیق موجود در توضیحات را امتحان کنید

گام‌های بعدی¶

• سیستم افزونه - توسعه کامل افزونه را بیاموزید

• سرورهای MCP - قابلیت‌های ابزاری Claude را گسترش دهید

• نکات CLI - کارایی خط فرمان را بهبود دهید

سازمانی ←