# سیستم پلاگین

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

## پلاگین‌ها چه هستند؟

### مفاهیم اصلی

پلاگین Claude Code یک پوشه با ساختار فایل مشخص است که می‌تواند مؤلفه‌های زیر را اضافه کند:

| مؤلفه | توضیح | قالب فایل |
|-----------|-------------|-------------|
| **دستورها** | دستورهای اسلش سفارشی | فایل‌های `.md` |
| **عامل‌ها** | زیرعامل‌های تخصصی وظیفه | فایل‌های `.md` |
| **مهارت‌ها** | دانش و قابلیت‌های قابل استفاده مجدد | پوشه + `SKILL.md` |
| **هوک‌ها** | خودکارسازی مبتنی بر رویداد | `hooks.json` |

### چرا پلاگین‌ها؟

- **استانداردسازی تیمی**: استانداردهای کدنویسی و معیارهای بازبینی را به‌صورت دستورهای اجرایی کدگذاری کنید.

- **خودکارسازی گردش‌کار**: وظایف تکراری مانند کامیت‌ها، استقرارها و بازبینی‌ها را خودکار کنید.

- **اشتراک دانش**: بهترین روش‌ها و تخصص را میان اعضای تیم به اشتراک بگذارید.

- **تجربه سفارشی**: رفتار Claude را برای نیازهای پروژه سفارشی کنید.

## ساختار پوشه پلاگین

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
│   ├── review.md
│   └── deploy.md
├── agents/                   # Subagent definitions (.md files)
│   └── code-reviewer.md
├── skills/                   # Agent skills (subdirectories)
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions (optional)
└── scripts/                 # Helper scripts (optional)
```

## شروع سریع

### نصب پلاگین‌ها

```bash
# Install from marketplace
/plugin install plugin-name@claude-code-marketplace

# Install from local directory
claude --plugin-dir /path/to/my-plugin
```

### استفاده از ویزارد ساخت پلاگین

```bash
/plugin-dev:create-plugin
```

این دستور شما را طی 8 مرحله برای ساخت یک پلاگین کامل راهنمایی می‌کند.

## ساخت دستورهای سفارشی

### قالب پایه دستور

فایل‌های `.md` را در پوشه `commands/` ایجاد کنید:

```markdown
---
description: Perform code review
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

Please review the code quality of: @$1

Focus on:
1. Code readability
2. Potential bugs
3. Performance issues
4. Security vulnerabilities
```

### پیکربندی فرانت‌متر YAML

| فیلد | توضیح | مثال |
|-------|-------------|---------|
| `description` | توضیح دستور (که در /help نمایش داده می‌شود) | `Perform code review` |
| `argument-hint` | راهنمای پارامترها | `[file-path] [options]` |
| `allowed-tools` | ابزارهای مجاز | `Read, Bash(git:*)` |
| `model` | تعیین مدل | `opus` یا `sonnet` |

### استفاده از آرگومان‌های پویا

- `$1`، `$2`، `$3`... - آرگومان‌های موقعیتی

- `$ARGUMENTS` - همه آرگومان‌ها

- `@path/to/file` - ارجاع به فایل

- `!`command`` - اجرای دستور Bash

### مثال‌های دستور

**دستور بازبینی کد** (`commands/review.md`):

```markdown
---
description: Comprehensive code review
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

Perform a comprehensive code review of @$1.

Checklist:
- [ ] Code style follows project standards
- [ ] No potential security issues
- [ ] Error handling is complete
- [ ] Tests are needed

If it's a directory, first use Glob tool to find all relevant files.
```

**دستور کامیت هوشمند** (`commands/commit.md`):

```markdown
---
description: Smart commit with generated message
allowed-tools: Bash(git:*)
---

1. Run `git status` to see changes
2. Run `git diff --staged` to analyze staged changes
3. Generate a conventional commit message based on changes
4. Execute `git commit`

Commit message format:
- feat: New feature
- fix: Bug fix
- docs: Documentation update
- refactor: Refactoring
- test: Test related
```
## ساخت عامل‌های سفارشی

### قالب تعریف عامل

فایل‌های `.md` را در پوشه `agents/` بسازید:

```markdown
---
description: Specialized code review agent
model: opus
tools: Read, Grep, Glob
---

You are a professional code review agent. Your task is to:

1. Carefully read the provided code
2. Identify potential issues
3. Provide specific improvement suggestions
4. Focus on security and performance

Always be constructive and specific.
```

### انواع عامل

| نوع | هدف | نمونه |
|------|---------|---------|
| عامل بازبینی | بازبینی کد، بازبینی PR | `code-reviewer` |
| عامل آزمون | تولید و اجرای آزمون‌ها | `test-generator` |
| عامل مستندات | تولید مستندات | `doc-writer` |
| عامل بازآرایی | بازآرایی کد | `refactorer` |

## ساخت مهارت‌ها

### ساختار پوشه مهارت

```
skills/
└── coding-standards/
    ├── SKILL.md              # Required: Skill definition
    ├── references/           # Reference materials
    │   └── style-guide.md
    └── examples/             # Example code
        └── good-practices.md
```

### قالب SKILL.md

```markdown
# Coding Standards Skill

## Overview
This skill contains team coding standards and best practices.

## Knowledge Content

### Naming Conventions
- Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Files: kebab-case

### Code Style
- Use 2-space indentation
- Max line width 100 characters
- Use semicolons

### Error Handling
- Always use try-catch
- Log errors
- Provide meaningful error messages
```

## ساخت هوک‌ها

### قالب hooks.json

```json
{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "Run lint check before commit"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "Type check when TypeScript files change"
    }
  ]
}
```

### رویدادهای پشتیبانی‌شده

| رویداد | زمان فعال‌سازی |
|-------|----------------|
| `on_commit` | کامیت کردن کد |
| `on_file_change` | تغییر فایل |
| `on_session_start` | شروع نشست |
| `on_command` | اجرای فرمان |

## مانیفست افزونه

### قالب plugin.json

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}
```
## مثال‌های عملی

### مثال 1: افزونه بازبینی کد تیمی

```
team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR review command
│   ├── security-check.md     # Security check command
│   └── perf-audit.md         # Performance audit command
├── agents/
│   ├── security-reviewer.md  # Security review agent
│   └── perf-analyzer.md      # Performance analysis agent
└── skills/
    └── team-standards/
        └── SKILL.md          # Team standards skill
```

### مثال 2: افزونه خودکارسازی استقرار

```
deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # Deploy to staging
│   ├── deploy-prod.md        # Deploy to production
│   └── rollback.md           # Rollback command
├── hooks/
│   └── hooks.json            # Pre-deploy check hooks
└── .mcp.json                 # Kubernetes MCP config
```

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

### طراحی دستور

1. **تک‌مسئولیتی**: هر دستور یک کار انجام می‌دهد

2. **توضیحات واضح**: توضیحات را مختصر نگه دارید

3. **مستندسازی پارامترها**: از argument-hint برای توضیح پارامترها استفاده کنید

4. **حداقل مجوزها**: فقط ابزارهای لازم را در allowed-tools قرار دهید

5. **مدیریت خطا**: سناریوهای شکست را در نظر بگیرید

### سازمان‌دهی افزونه

1. **ماژولار**: قابلیت‌های مرتبط را کنار هم سازمان‌دهی کنید

2. **قابل استفاده مجدد**: مهارت‌ها باید توسط چندین دستور قابل استفاده باشند

3. **مستندشده**: README و دستورالعمل‌های مصرف را اضافه کنید

4. **نسخه‌بندی‌شده**: از نسخه‌گذاری معنایی استفاده کنید

### ملاحظات امنیتی

1. **بدون اسرار درون کد (hardcoded)**: از متغیرهای محیطی استفاده کنید

2. **محدود کردن دسترسی به فایل**: فقط به مسیرهای لازم دسترسی داشته باشید

3. **اعتبارسنجی ورودی**: پارامترها را اعتبارسنجی کنید

4. **گزارش‌های حسابرسی**: عملیات حساس را ثبت کنید

## اشکال‌زدایی افزونه‌ها

```bash
# View plugin load status
/plugin list

# View command details
/help my-command

# Test command
/my-command test-argument
```

## مراحل بعدی

- درباره [سرورهای MCP](/docs/advanced/mcp) بیاموزید تا یکپارچه‌سازی‌های خارجی را گسترش دهید

- [نکات CLI](/docs/usage/cli-tips) را بررسی کنید تا بهره‌وری را افزایش دهید

- [نکات گردش کار](/docs/usage/workflow-tips) را کاوش کنید تا جریان توسعه را بهینه کنید