مرجع پلاگین‌ها

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

یک پلاگین یک پوشه‌ی خودبسنده از کامپوننت‌هاست که Claude Code را با قابلیت‌های سفارشی گسترش می‌دهد. کامپوننت‌های یک پلاگین شامل skillها، agentها، hookها، MCP serverها، LSP serverها و monitorهاست.

مرجع کامپوننت‌های پلاگین

Skills

پلاگین‌ها به Claude Code skill اضافه می‌کنند و میان‌برهای /name می‌سازند که تو یا Claude می‌توانید فراخوانی‌شان کنید.

محل: پوشه‌ی skills/ یا commands/ در ریشه‌ی پلاگین، یا یک فایل تکیِ SKILL.md در ریشه‌ی پلاگین

قالب فایل: skillها پوشه‌هایی با SKILL.md هستند؛ commandها فایل‌های ساده‌ی markdown هستند

ساختار skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

رفتار یکپارچه‌سازی:

skillها و commandها هنگام نصب پلاگین به‌صورت خودکار کشف می‌شوند
Claude می‌تواند بر اساس کانتکستِ کار، خودکار آن‌ها را فراخوانی کند
skillها می‌توانند فایل‌های کمکی را در کنار SKILL.md داشته باشند

اگر پلاگینی نه پوشه‌ی skills/ داشته باشد و نه فیلد مانیفستِ skills، آنگاه یک SKILL.md در ریشه‌ی پلاگین به‌عنوان یک skill تکی بارگذاری می‌شود. فیلد frontmatterِ name را تنظیم کن تا نام فراخوانیِ skill را کنترل کنی. بدون آن، Claude Code به نام پوشه‌ی نصب برمی‌گردد که برای پلاگین‌های نصب‌شده از بازارچه یک رشته‌ی نسخه است که در هر به‌روزرسانی تغییر می‌کند. برای پلاگین‌هایی که بیش از یک skill عرضه می‌کنند، از چیدمان پوشه‌ی skills/ که بالا نشان داده شد استفاده کن.

برای جزئیات کامل، Skills را ببین.

Agents

پلاگین‌ها می‌توانند ساب‌ایجنت‌های تخصصی برای کارهای مشخص فراهم کنند که Claude بتواند هرجا مناسب بود خودکار فراخوانی‌شان کند.

محل: پوشه‌ی agents/ در ریشه‌ی پلاگین

قالب فایل: فایل‌های Markdown که توانمندی‌های agent را توصیف می‌کنند

ساختار agent:

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

agentهای پلاگین از فیلدهای frontmatterِ name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background و isolation پشتیبانی می‌کنند. تنها مقدار معتبر برای isolation، "worktree" است. به دلایل امنیتی، hooks, mcpServers و permissionMode برای agentهایی که با پلاگین عرضه می‌شوند پشتیبانی نمی‌شوند.

نقاط یکپارچه‌سازی:

agentها در رابط /agents ظاهر می‌شوند
Claude می‌تواند بر اساس کانتکستِ کار، خودکار agentها را فراخوانی کند
کاربران می‌توانند agentها را به‌صورت دستی فراخوانی کنند
agentهای پلاگین در کنار agentهای داخلیِ Claude کار می‌کنند

برای جزئیات کامل، Subagents را ببین.

Hooks

پلاگین‌ها می‌توانند هندلرهای رویداد فراهم کنند که خودکار به رویدادهای Claude Code پاسخ می‌دهند.

محل: hooks/hooks.json در ریشه‌ی پلاگین، یا به‌صورت درون‌خطی در plugin.json

قالب: پیکربندی JSON با matcherها و اکشن‌های رویداد

پیکربندی hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

hookهای پلاگین به همان رویدادهای چرخه‌ی حیات پاسخ می‌دهند که hookهای تعریف‌شده توسط کاربر:

رویداد	کِی شلیک می‌شود
`SessionStart`	وقتی یک نشست آغاز یا از سر گرفته می‌شود
`Setup`	وقتی Claude Code را با `--init-only`، یا با `--init` یا `--maintenance` در حالت `-p` اجرا می‌کنی. برای آماده‌سازیِ یک‌باره در CI یا اسکریپت‌ها
`UserPromptSubmit`	وقتی پرامپت می‌فرستی، پیش از آنکه Claude پردازشش کند
`UserPromptExpansion`	وقتی یک command تایپ‌شده‌ی کاربر به یک پرامپت بسط می‌یابد، پیش از آنکه به Claude برسد. می‌تواند بسط را مسدود کند
`PreToolUse`	پیش از اجرای فراخوانیِ یک ابزار. می‌تواند آن را مسدود کند
`PermissionRequest`	وقتی دیالوگ مجوز ظاهر می‌شود
`PermissionDenied`	وقتی فراخوانیِ یک ابزار توسط دسته‌بندِ حالت خودکار رد می‌شود. مقدار `{retry: true}` را برگردان تا به مدل بگویی می‌تواند فراخوانیِ ردشده را دوباره امتحان کند
`PostToolUse`	پس از موفقیتِ فراخوانیِ یک ابزار
`PostToolUseFailure`	پس از شکستِ فراخوانیِ یک ابزار
`PostToolBatch`	پس از حل‌شدنِ یک دسته‌ی کاملِ فراخوانی‌های موازیِ ابزار، پیش از فراخوانیِ بعدیِ مدل
`Notification`	وقتی Claude Code یک اعلان می‌فرستد
`MessageDisplay`	حین نمایش متنِ پیامِ دستیار
`SubagentStart`	وقتی یک ساب‌ایجنت ساخته می‌شود
`SubagentStop`	وقتی یک ساب‌ایجنت تمام می‌شود
`TaskCreated`	وقتی یک task از طریق `TaskCreate` در حال ساخته‌شدن است
`TaskCompleted`	وقتی یک task در حال علامت‌خوردن به‌عنوان تمام‌شده است
`Stop`	وقتی Claude پاسخ‌دادن را تمام می‌کند
`StopFailure`	وقتی نوبت به دلیل خطای API پایان می‌یابد. خروجی و کد خروج نادیده گرفته می‌شوند
`TeammateIdle`	وقتی یک هم‌تیمیِ تیمِ agent در آستانه‌ی بی‌کارشدن است
`InstructionsLoaded`	وقتی یک فایل CLAUDE.md یا `.claude/rules/*.md` به کانتکست بارگذاری می‌شود. در شروع نشست و هنگام بارگذاریِ تنبلانه‌ی فایل‌ها در طول نشست شلیک می‌شود
`ConfigChange`	وقتی یک فایل پیکربندی در طول نشست تغییر می‌کند
`CwdChanged`	وقتی پوشه‌ی کاری تغییر می‌کند، مثلاً وقتی Claude یک دستور `cd` اجرا می‌کند. برای مدیریت واکنشیِ محیط با ابزارهایی مثل direnv مفید است
`FileChanged`	وقتی یک فایلِ تحت‌نظر روی دیسک تغییر می‌کند. فیلد `matcher` مشخص می‌کند کدام نام‌فایل‌ها تحت نظر باشند
`WorktreeCreate`	وقتی یک worktree از طریق `--worktree` یا `isolation: "worktree"` در حال ساخته‌شدن است. جایگزین رفتار پیش‌فرض git می‌شود
`WorktreeRemove`	وقتی یک worktree در حال حذف‌شدن است، چه در خروج از نشست و چه وقتی یک ساب‌ایجنت تمام می‌شود
`PreCompact`	پیش از فشرده‌سازیِ کانتکست
`PostCompact`	پس از کامل‌شدنِ فشرده‌سازیِ کانتکست
`Elicitation`	وقتی یک MCP server در طول فراخوانیِ یک ابزار، ورودیِ کاربر را درخواست می‌کند
`ElicitationResult`	پس از آنکه کاربر به یک elicitationِ MCP پاسخ می‌دهد، پیش از آنکه پاسخ به سرور بازگردانده شود
`SessionEnd`	وقتی یک نشست خاتمه می‌یابد

انواع hook:

command: اجرای دستورها یا اسکریپت‌های shell
http: ارسال JSONِ رویداد به‌عنوان یک درخواست POST به یک URL
mcp_tool: فراخوانی یک ابزار روی یک MCP server پیکربندی‌شده
prompt: ارزیابیِ یک پرامپت با یک LLM (از جای‌نگهدارِ $ARGUMENTS برای کانتکست استفاده می‌کند)
agent: اجرای یک راستی‌آزمایِ ایجنتیک با ابزارها برای کارهای راستی‌آزماییِ پیچیده

MCP servers

پلاگین‌ها می‌توانند MCP serverها (Model Context Protocol) را بسته‌بندی کنند تا Claude Code را به ابزارها و سرویس‌های بیرونی وصل کنند.

محل: .mcp.json در ریشه‌ی پلاگین، یا به‌صورت درون‌خطی در plugin.json

قالب: پیکربندی استاندارد MCP server

پیکربندی MCP server:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

رفتار یکپارچه‌سازی:

MCP serverهای پلاگین وقتی پلاگین فعال است خودکار راه می‌افتند
serverها به‌عنوان ابزارهای استاندارد MCP در جعبه‌ابزار Claude ظاهر می‌شوند
توانمندی‌های server بی‌درز با ابزارهای موجودِ Claude یکپارچه می‌شوند
serverهای پلاگین می‌توانند مستقل از MCP serverهای کاربر پیکربندی شوند

LSP servers

پلاگین‌ها می‌توانند serverهای Language Server Protocol (LSP) فراهم کنند تا حین کار روی کدبیست، هوشِ کدِ بلادرنگ به Claude بدهند.

یکپارچه‌سازی LSP این‌ها را فراهم می‌کند:

تشخیص‌های آنی: Claude بلافاصله پس از هر ویرایش، خطاها و هشدارها را می‌بیند
پیمایش کد: رفتن به تعریف، یافتن ارجاع‌ها، و اطلاعاتِ hover
آگاهی از زبان: اطلاعات نوع و مستندات برای نمادهای کد

محل: .lsp.json در ریشه‌ی پلاگین، یا به‌صورت درون‌خطی در plugin.json

قالب: پیکربندی JSON که نام serverهای زبان را به پیکربندی‌شان نگاشت می‌کند

قالب فایلِ .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

درون‌خطی در plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

فیلدهای الزامی:

فیلد	توضیح
`command`	باینریِ LSP برای اجرا (باید در PATH باشد)
`extensionToLanguage`	پسوندهای فایل را به شناسه‌های زبان نگاشت می‌کند

فیلدهای اختیاری:

فیلد	توضیح
`args`	آرگومان‌های خط فرمان برای LSP server
`transport`	روش انتقالِ ارتباط: `stdio` (پیش‌فرض) یا `socket`
`env`	متغیرهای محیطی که هنگام راه‌اندازیِ server تنظیم شوند
`initializationOptions`	گزینه‌هایی که حین مقداردهیِ اولیه به server پاس داده می‌شوند
`settings`	تنظیماتی که از طریق `workspace/didChangeConfiguration` پاس داده می‌شوند
`workspaceFolder`	مسیر پوشه‌ی فضای‌کاری برای server
`startupTimeout`	حداکثر زمان انتظار برای راه‌اندازیِ server (بر حسب میلی‌ثانیه)
`maxRestarts`	حداکثر تعداد تلاش‌های راه‌اندازیِ مجدد پیش از تسلیم‌شدن
`diagnostics`	اینکه آیا تشخیص‌ها پس از ویرایش به کانتکستِ Claude تزریق شوند (پیش‌فرض `true`). آن را روی `false` بگذار تا پیمایش کد حفظ شود ولی تزریق خودکارِ تشخیص‌ها سرکوب شود.

پلاگین‌های LSPِ موجود:

پلاگین	Language server	دستور نصب
`pyright-lsp`	Pyright (Python)	`pip install pyright` or `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-analyzer-lsp`	rust-analyzer	See rust-analyzer installation

اول language server را نصب کن، بعد پلاگین را از بازارچه نصب کن.

Monitors

پلاگین‌ها می‌توانند monitorهای پس‌زمینه اعلام کنند که Claude Code وقتی پلاگین فعال است خودکار راه‌شان می‌اندازد. هر monitor برای تمام طول عمرِ نشست یک دستور shell اجرا می‌کند و هر خطِ stdout را به‌عنوان یک اعلان به Claude تحویل می‌دهد، تا Claude بتواند بدون آنکه از او خواسته شود خودش watch را شروع کند، به ورودی‌های لاگ، تغییرات وضعیت، یا رویدادهای poll‌شده واکنش نشان دهد.

monitorهای پلاگین از همان مکانیزم ابزار Monitor استفاده می‌کنند و محدودیت‌های در دسترس بودنِ آن را به اشتراک می‌گذارند. آن‌ها فقط در نشست‌های تعاملیِ CLI اجرا می‌شوند، بدون sandbox و در همان سطح اعتمادِ hookها اجرا می‌شوند، و روی میزبان‌هایی که ابزار Monitor در دسترس نیست نادیده گرفته می‌شوند.

محل: monitors/monitors.json در ریشه‌ی پلاگین، یا به‌صورت درون‌خطی در plugin.json

قالب: آرایه‌ی JSON از ورودی‌های monitor

monitors/monitors.jsonِ زیر یک endpointِ وضعیتِ استقرار و یک لاگ خطای محلی را تحت نظر می‌گیرد:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

برای اعلام درون‌خطیِ monitorها، experimental.monitors را در plugin.json روی همان آرایه بگذار. برای بارگذاری از مسیری غیرپیش‌فرض، experimental.monitors را روی یک رشته‌ی مسیر نسبی مانند "./config/monitors.json" بگذار. monitorها یک کامپوننت آزمایشی هستند.

فیلدهای الزامی:

فیلد	توضیح
`name`	شناسه‌ای یکتا درون پلاگین. وقتی پلاگین دوباره بارگذاری می‌شود یا یک skill دوباره فراخوانی می‌شود، از پردازش‌های تکراری جلوگیری می‌کند
`command`	دستور shell که به‌عنوان یک پردازشِ پس‌زمینه‌ی پایدار در پوشه‌ی کاریِ نشست اجرا می‌شود
`description`	خلاصه‌ی کوتاهِ آنچه تحت نظر است. در پنل task و در خلاصه‌های اعلان نشان داده می‌شود

فیلدهای اختیاری:

فیلد	توضیح
`when`	کنترل می‌کند که monitor کِی شروع شود. `"always"` آن را در شروع نشست و هنگام بارگذاریِ مجددِ پلاگین شروع می‌کند و پیش‌فرض است. `"on-skill-invoke:<skill-name>"` آن را اولین باری که skillِ نام‌برده‌شده در این پلاگین فراخوانی شود شروع می‌کند

مقدار command از همان جای‌گذاری‌های متغیرِ پیکربندیِ MCP و LSP server پشتیبانی می‌کند: ${CLAUDE_PLUGIN_ROOT}، ${CLAUDE_PLUGIN_DATA}، ${CLAUDE_PROJECT_DIR}، ${user_config.*} و هر ${ENV_VAR} از محیط. اگر اسکریپت لازم است از پوشه‌ی خودِ پلاگین اجرا شود، دستور را با cd "${CLAUDE_PLUGIN_ROOT}" && پیشوند بزن.

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

Themes

پلاگین‌ها می‌توانند تم‌های رنگی عرضه کنند که در /theme در کنار پیش‌تنظیم‌های داخلی و تم‌های محلیِ کاربر ظاهر می‌شوند. یک تم یک فایل JSON در themes/ است با یک پیش‌تنظیمِ base و یک نگاشتِ پراکنده‌ی overrides از توکن‌های رنگ. تم‌ها یک کامپوننت آزمایشی هستند.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

انتخاب یک تم پلاگین، custom:<plugin-name>:<slug> را در پیکربندیِ کاربر ماندگار می‌کند. تم‌های پلاگین فقط‌خواندنی هستند؛ فشردنِ Ctrl+E روی یکی از آن‌ها در /theme، آن را در ~/.claude/themes/ کپی می‌کند تا کاربر بتواند کپی را ویرایش کند.

دامنه‌های نصب پلاگین

وقتی یک پلاگین نصب می‌کنی، یک دامنه (scope) انتخاب می‌کنی که تعیین می‌کند پلاگین کجا در دسترس است و چه کسِ دیگری می‌تواند از آن استفاده کند:

دامنه	فایل تنظیمات	مورد استفاده
`user`	`~/.claude/settings.json`	پلاگین‌های شخصیِ در دسترس در همه‌ی پروژه‌ها (پیش‌فرض)
`project`	`.claude/settings.json`	پلاگین‌های تیمیِ به‌اشتراک‌گذاشته‌شده از طریق کنترل نسخه
`local`	`.claude/settings.local.json`	پلاگین‌های مختصِ پروژه، gitignore‌شده
`managed`	تنظیمات مدیریت‌شده	پلاگین‌های مدیریت‌شده (فقط‌خواندنی، فقط به‌روزرسانی)

پلاگین‌ها از همان سیستم دامنه‌ای استفاده می‌کنند که سایر پیکربندی‌های Claude Code. برای دستورالعمل‌های نصب و پرچم‌های دامنه، نصب پلاگین‌ها را ببین. برای توضیح کامل دامنه‌ها، دامنه‌های پیکربندی را ببین.

پلاگین‌های پوشه‌ی skills

هر پوشه‌ای زیرِ یک پوشه‌ی skills که شامل یک مانیفستِ .claude-plugin/plugin.json باشد، در نشست بعدی به‌عنوان پلاگینی با نام <name>@skills-dir بارگذاری می‌شود، بدون بازارچه و بدون گام نصب. یکی را با plugin init داربست‌بندی کن. برخلاف نصب از بازارچه، پلاگین به‌جای کپی‌شدن به کشِ پلاگین، در محل خودش کشف می‌شود.

درختِ یک پوشه‌ی skills از سه چیزِ متمایز پشتیبانی می‌کند:

چیزی که داری	چیست
`<skills-dir>/foo/SKILL.md` بدون مانیفست	یک skillِ ساده با نام `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	یک پلاگین `foo@skills-dir` که می‌تواند skillها، agentها، hookها و بیشتر را خودش بسته‌بندی کند
`<plugin>/skills/bar/SKILL.md`	یک skill با نام `bar` که درون یک پلاگین بسته‌بندی شده

انتخاب اینکه پلاگین از کجا بارگذاری شود

پوشه‌ی skills	دامنه	بارگذاری می‌شود
`~/.claude/skills/`	شخصی	در هر پروژه، چون این محل فقط مال خودِ توست
`<cwd>/.claude/skills/`	پروژه	فقط پس از آنکه برای آن پوشه دیالوگ اعتمادِ فضای‌کاری را بپذیری

یک پلاگینِ دامنه‌ی پروژه درون مخزن چک‌این می‌شود و به دست هر همکاری که آن را clone می‌کند می‌رسد. چون آن محتوا به‌جای آنکه از تو باشد از مخزن می‌آید، فقط پس از همان دروازه‌ی اعتمادی بارگذاری می‌شود که .claude/settings.json را اداره می‌کند، و کامپوننت‌هایی که کد اجرا می‌کنند بیشتر محدود می‌شوند:

MCP serverهایی که اعلام می‌کند از همان تأییدِ هر-سرور عبور می‌کنند که یک .mcp.jsonِ پروژه
LSP serverها فقط پس از آنکه به فضای‌کاری اعتماد کنی راه می‌افتند
monitorهای پس‌زمینه بارگذاری نمی‌شوند

پلاگین‌های دامنه‌ی شخصی هیچ‌یک از این محدودیت‌ها را ندارند.

ویرایش، بارگذاریِ مجدد، و غیرفعال‌کردنِ یک پلاگینِ پوشه‌ی skills

تغییراتی که در SKILL.mdِ یک skill می‌دهی بلافاصله در نشست جاری اثر می‌کنند. تغییرات در سایر کامپوننت‌های پلاگین، مثل hooks/، .mcp.json، agents/ و output-styles/، اثر نمی‌کنند. برای دریافت آن‌ها /reload-plugins را اجرا کن یا Claude Code را راه‌اندازی مجدد کن. تشخیص تغییرِ زنده را ببین.

برای آنکه بارگذاریِ یک پلاگینِ پوشه‌ی skills را متوقف کنی، پوشه‌اش را حذف کن یا آن را با نام غیرفعال کن. گام uninstall وجود ندارد چون چیزی از بازارچه نصب نشده بود.

claude plugin disable my-tool@skills-dir

اسکیمای مانیفست پلاگین

فایل .claude-plugin/plugin.json فراداده و پیکربندیِ پلاگین تو را تعریف می‌کند. این بخش همه‌ی فیلدها و گزینه‌های پشتیبانی‌شده را مستند می‌کند.

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

اسکیمای کامل

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

فیلدهای الزامی

اگر مانیفست بگذاری، name تنها فیلد الزامی است.

فیلد	نوع	توضیح	مثال
`name`	string	شناسه‌ی یکتا (kebab-case، بدون فاصله)	`"deployment-tools"`

این نام برای فضای‌نامیِ کامپوننت‌ها استفاده می‌شود. مثلاً، در رابط کاربری، agentِ agent-creator برای پلاگینی با نام plugin-dev به‌صورت plugin-dev:agent-creator ظاهر می‌شود.

فیلدهای ناشناخته

Claude Code فیلدهای سطح‌بالایی را که نمی‌شناسد نادیده می‌گیرد. می‌توانی فراداده‌ای از یک اکوسیستم دیگر را در plugin.json نگه داری و پلاگین همچنان بارگذاری می‌شود. این کار باعث می‌شود عملی باشد که یک مانیفستِ واحد را نگه داری که هم‌زمان نقشِ مانیفستِ افزونه‌ی VS Code یا Cursor، یک package.jsonِ npm، یا مانیفستِ یک بسته‌ی MCPB/DXT را هم بازی کند.

claude plugin validate فیلدهای ناشناخته را به‌عنوان هشدار گزارش می‌کند، نه خطا. اگر یک فیلد یکی-دو کاراکتر با یک فیلدِ شناخته‌شده فاصله داشته باشد، هشدار نامِ محتملِ موردنظر را پیشنهاد می‌دهد. پلاگینی که فقط هشدارهای فیلدِ ناشناخته دارد همچنان از اعتبارسنجی می‌گذرد و در زمان اجرا بارگذاری می‌شود.

فیلدهایی با نوع نادرست همچنان شکست می‌خورند. مثلاً، یک مقدار keywords که به‌جای آرایه یک رشته باشد، یک خطای بارگذاری است و claude plugin validate آن را به‌عنوان خطا گزارش می‌کند.

--strict را پاس بده تا هشدارها به‌عنوان خطا در نظر گرفته شوند. در CI از آن استفاده کن تا پیش از انتشار، یک نام فیلدِ غلط‌املایی یا فیلدی به‌جامانده از مانیفستِ ابزاری دیگر را بگیری، حتی اگر پلاگین در زمان اجرا بارگذاری می‌شد.

claude plugin validate ./my-plugin --strict

فیلدهای فراداده

فیلد	نوع	توضیح	مثال
`$schema`	string	آدرسِ JSON Schema برای تکمیل خودکار و اعتبارسنجی در ویرایشگر. Claude Code این فیلد را در زمان بارگذاری نادیده می‌گیرد.	`"https://json.schemastore.org/claude-code-plugin-manifest.json"`
`displayName`	string	{/* min-version: 2.1.143 */}نامِ خوانا برای انسان که در انتخابگرِ `/plugin` و سطوح دیگرِ UI نشان داده می‌شود. وقتی حذف شود به `name` برمی‌گردد. برخلاف `name`، می‌تواند فاصله و هر نوع بزرگی/کوچکیِ حروف داشته باشد. برای فضای‌نامی یا جستجو استفاده نمی‌شود. به Claude Code نسخه‌ی v2.1.143 یا بالاتر نیاز دارد.	`"Deployment Tools"`
`version`	string	اختیاری. نسخه‌ی معنایی. تنظیم آن، پلاگین را به آن رشته‌ی نسخه پین می‌کند، پس کاربران فقط وقتی آن را بالا ببری به‌روزرسانی دریافت می‌کنند. اگر حذف شود، Claude Code به SHAِ کامیتِ git برمی‌گردد، پس هر کامیت به‌عنوان یک نسخه‌ی جدید تلقی می‌شود. اگر در ورودیِ بازارچه هم تنظیم شده باشد، `plugin.json` برنده است. مدیریت نسخه را ببین.	`"2.1.0"`
`description`	string	توضیح کوتاهِ هدفِ پلاگین	`"Deployment automation tools"`
`author`	object	اطلاعات نویسنده	`{"name": "Dev Team", "email": "dev@company.com"}`
`homepage`	string	آدرسِ مستندات	`"https://docs.example.com"`
`repository`	string	آدرسِ کد منبع	`"https://github.com/user/plugin"`
`license`	string	شناسه‌ی مجوز	`"MIT"`, `"Apache-2.0"`
`keywords`	array	برچسب‌های کشف	`["deployment", "ci-cd"]`
`defaultEnabled`	boolean	{/* min-version: 2.1.154 */}اینکه آیا پلاگین وقتی کاربر حالتی تنظیم نکرده در حالت فعال شروع شود. پیش‌فرض `true`. فعال‌سازیِ پیش‌فرض را ببین. به Claude Code نسخه‌ی v2.1.154 یا بالاتر نیاز دارد.	`false`

فعال‌سازیِ پیش‌فرض

defaultEnabled: false را در plugin.json بگذار تا پلاگینی عرضه کنی که غیرفعال نصب شود. کاربر آن را با claude plugin enable <plugin> یا رابط /plugin روشن می‌کند. این را برای پلاگین‌هایی استفاده کن که هزینه یا دامنه‌ای اضافه می‌کنند که کاربر باید آگاهانه واردش شود، مثل پلاگینی که به یک سرویس بیرونی وصل می‌شود. این به Claude Code نسخه‌ی v2.1.154 یا بالاتر نیاز دارد. نسخه‌های قدیمی‌تر این فیلد را نادیده می‌گیرند و پلاگین را هنگام نصب فعال می‌کنند.

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

تنظیم کاربر: یک ورودی برای پلاگین در enabledPlugins در هر دامنه‌ی تنظیمات. وقتی نوشته شد، در طول به‌روزرسانی‌ها و نصب‌های مجدد پلاگین ماندگار می‌ماند، پس تغییر defaultEnabled در یک نسخه‌ی بعدی، کاربر موجود را عوض نمی‌کند.
یک الزامِ وابستگی: وقتی یک پلاگین توسط پلاگینِ فعالِ دیگری لازم باشد، Claude Code در زمان نصب یا فعال‌سازی برایش true می‌نویسد. این به آن یک تنظیمِ صریح می‌دهد، پس دیگر پیش‌فرضِ خودش اعمال نمی‌شود. فعال یا غیرفعال‌کردن یک پلاگین با وابستگی‌ها را ببین.

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

فیلدهای مسیر کامپوننت

فیلد	نوع	توضیح	مثال
`skills`	string\|array	پوشه‌های سفارشیِ skill که شامل `<name>/SKILL.md` هستند (علاوه بر `skills/`ِ پیش‌فرض)	`"./custom/skills/"`
`commands`	string\|array	فایل‌ها یا پوشه‌های سفارشیِ skill به‌صورت `.md`ِ تخت (جایگزین `commands/`ِ پیش‌فرض)	`"./custom/cmd.md"` or `["./cmd1.md"]`
`agents`	string\|array	فایل‌های سفارشیِ agent (جایگزین `agents/`ِ پیش‌فرض)	`"./custom/agents/reviewer.md"`
`hooks`	string\|array\|object	مسیرهای پیکربندیِ hook یا پیکربندیِ درون‌خطی	`"./my-extra-hooks.json"`
`mcpServers`	string\|array\|object	مسیرهای پیکربندیِ MCP یا پیکربندیِ درون‌خطی	`"./my-extra-mcp-config.json"`
`outputStyles`	string\|array	فایل‌ها/پوشه‌های سفارشیِ سبکِ خروجی (جایگزین `output-styles/`ِ پیش‌فرض)	`"./styles/"`
`lspServers`	string\|array\|object	پیکربندی‌های Language Server Protocol برای هوشِ کد (رفتن به تعریف، یافتن ارجاع‌ها و غیره)	`"./.lsp.json"`
`experimental.themes`	string\|array	فایل‌ها/پوشه‌های تم رنگی (جایگزین `themes/`ِ پیش‌فرض). Themes را ببین	`"./themes/"`
`experimental.monitors`	string\|array	پیکربندی‌های Monitorِ پس‌زمینه که وقتی پلاگین فعال است خودکار شروع می‌شوند. Monitors را ببین	`"./monitors.json"`
`userConfig`	object	مقادیر قابل‌پیکربندیِ کاربر که هنگام فعال‌سازی پرسیده می‌شوند. پیکربندی کاربر را ببین	پایین را ببین
`channels`	array	اعلام‌های channel برای تزریق پیام (سبکِ Telegram، Slack، Discord). Channels را ببین	پایین را ببین
`dependencies`	array	پلاگین‌های دیگری که این پلاگین لازم دارد، به‌اختیار با محدودیت‌های نسخه‌ی semver. محدودکردن نسخه‌های وابستگیِ پلاگین را ببین	`[{ "name": "secrets-vault", "version": "~2.1.0" }]`

کامپوننت‌های آزمایشی

کامپوننت‌های زیرِ کلیدِ experimental، یعنی themes و monitors، اسکیمای مانیفستی دارند که ممکن است حین پایدارشدن، بین نسخه‌ها تغییر کند. اینکه آن‌ها را کجا اعلام می‌کنی یک مهاجرتِ جداست: سطح بالا هنوز کار می‌کند، claude plugin validate هشدار می‌دهد، و نسخه‌ای در آینده experimental.* را الزامی خواهد کرد.

پیکربندی کاربر

فیلد userConfig مقادیری را اعلام می‌کند که Claude Code هنگام فعال‌شدنِ پلاگین از کاربر می‌پرسد. این را به‌جای آنکه کاربران را وادار کنی settings.json را دستی ویرایش کنند استفاده کن.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

کلیدها باید شناسه‌های معتبر باشند. هر گزینه از این فیلدها پشتیبانی می‌کند:

فیلد	الزامی	توضیح
`type`	بله	یکی از `string`, `number`, `boolean`, `directory` یا `file`
`title`	بله	برچسبی که در دیالوگ پیکربندی نشان داده می‌شود
`description`	بله	متن راهنما که زیرِ فیلد نشان داده می‌شود
`sensitive`	خیر	اگر `true` باشد، ورودی را ماسک می‌کند و مقدار را به‌جای `settings.json` در حافظه‌ی امن ذخیره می‌کند
`required`	خیر	اگر `true` باشد، وقتی فیلد خالی باشد اعتبارسنجی شکست می‌خورد
`default`	خیر	مقداری که وقتی کاربر چیزی فراهم نکند استفاده می‌شود
`multiple`	خیر	برای نوع `string`، اجازه‌ی آرایه‌ای از رشته‌ها
`min` / `max`	خیر	کران‌ها برای نوع `number`

هر مقدار برای جای‌گذاری به‌صورت ${user_config.KEY} در پیکربندیِ MCP و LSP server، دستورهای hook و دستورهای monitor در دسترس است. مقادیر غیرحساس را می‌توان در محتوای skill و agent نیز جای‌گذاری کرد. همه‌ی مقادیر به‌صورت متغیرهای محیطیِ CLAUDE_PLUGIN_OPTION_<KEY> به زیرپردازش‌های پلاگین صادر می‌شوند.

مقادیر غیرحساس در settings.json زیرِ pluginConfigs[<plugin-id>].options ذخیره می‌شوند. مقادیر حساس به keychainِ سیستم (یا ~/.claude/.credentials.json جایی که keychain در دسترس نیست) می‌روند. ذخیره‌سازیِ keychain با توکن‌های OAuth مشترک است و یک سقف کلیِ تقریباً ۲ کیلوبایتی دارد، پس مقادیر حساس را کوچک نگه دار.

Channels

فیلد channels به یک پلاگین اجازه می‌دهد یک یا چند کانالِ پیام اعلام کند که محتوا را به مکالمه تزریق می‌کنند. هر کانال به یک MCP server که پلاگین فراهم می‌کند بسته می‌شود.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

فیلد server الزامی است و باید با یک کلید در mcpServersِ پلاگین مطابقت داشته باشد. userConfigِ اختیاریِ هر-کانال از همان اسکیمای فیلدِ سطح‌بالا استفاده می‌کند و به پلاگین اجازه می‌دهد هنگام فعال‌شدن، توکن‌های بات یا شناسه‌های مالک را بپرسد.

قواعد رفتار مسیر

اینکه یک مسیر سفارشی، پوشه‌ی پیش‌فرضِ پلاگین را جایگزین می‌کند یا گسترش می‌دهد، به فیلد بستگی دارد:

جایگزین پیش‌فرض می‌شود: commands, agents, outputStyles, experimental.themes, experimental.monitors. مثلاً، وقتی مانیفست commands را مشخص می‌کند، پوشه‌ی پیش‌فرضِ commands/ اسکن نمی‌شود. برای نگه‌داشتنِ پیش‌فرض و افزودنِ بیشتر، آن را صریحاً فهرست کن: "commands": ["./commands/", "./extras/"]
به پیش‌فرض اضافه می‌شود: skills. پوشه‌ی پیش‌فرضِ skills/ همیشه اسکن می‌شود، و پوشه‌های فهرست‌شده در skills در کنار آن بارگذاری می‌شوند
قواعد ادغامِ مخصوصِ خود: hooks، MCP servers و LSP servers. برای اینکه چند منبع چگونه با هم ترکیب می‌شوند، هر بخش را ببین

وقتی یک پلاگین هم پوشه‌ی پیش‌فرض و هم کلیدِ مانیفستِ متناظر را داشته باشد، Claude Code نسخه‌ی v2.1.140 و بالاتر، پوشه‌ی نادیده‌گرفته‌شده را در /doctor، claude plugin list و نمای جزئیاتِ /plugin نشانه‌گذاری می‌کند. پلاگین همچنان با استفاده از مسیرهای مانیفست بارگذاری می‌شود. وقتی کلیدِ مانیفست به درون پوشه‌ی پیش‌فرض اشاره کند، مثلاً "commands": ["./commands/deploy.md"]، هیچ هشداری نشان داده نمی‌شود، چون در آن حالت پوشه به‌صورت صریح آدرس‌دهی شده.

برای همه‌ی فیلدهای مسیر:

همه‌ی مسیرها باید نسبت به ریشه‌ی پلاگین باشند و با ./ شروع شوند
کامپوننت‌های مسیرهای سفارشی از همان قواعد نام‌گذاری و فضای‌نامی استفاده می‌کنند
چند مسیر را می‌توان به‌صورت آرایه مشخص کرد
وقتی یک مسیر skill به پوشه‌ای اشاره کند که مستقیماً یک SKILL.md دارد، مثلاً "skills": ["./"] که به ریشه‌ی پلاگین اشاره می‌کند، فیلد frontmatterِ name در SKILL.md نام فراخوانیِ skill را تعیین می‌کند. این صرف‌نظر از پوشه‌ی نصب، یک نام پایدار می‌دهد. اگر name در frontmatter تنظیم نشده باشد، basenameِ پوشه به‌عنوان جایگزین استفاده می‌شود.

پلاگینی که یک SKILL.md در ریشه‌اش دارد، هیچ زیرپوشه‌ی skills/ ندارد، و هیچ فیلد مانیفستِ skills ندارد، در Claude Code نسخه‌ی v2.1.142 و بالاتر خودکار به‌عنوان یک پلاگینِ تک‌skill بارگذاری می‌شود. برای این چیدمان لازم نیست "skills": ["./"] را در plugin.json بگذاری. نام فراخوانیِ skill از همان قاعده‌ی بالا پیروی می‌کند: فیلد frontmatterِ name، یا basenameِ پوشه به‌عنوان جایگزین.

مثال‌های مسیر:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

متغیرهای محیطی

Claude Code سه متغیر برای ارجاع به مسیرها فراهم می‌کند. هر سه هرجا که در محتوای skill، محتوای agent، دستورهای hook، دستورهای monitor و پیکربندیِ MCP یا LSP server ظاهر شوند به‌صورت درون‌خطی جای‌گذاری می‌شوند. هر سه همچنین به‌عنوان متغیرهای محیطی به پردازش‌های hook و زیرپردازش‌های MCP یا LSP server صادر می‌شوند.

${CLAUDE_PLUGIN_ROOT}: مسیر مطلق به پوشه‌ی نصبِ پلاگین تو. از این برای ارجاع به اسکریپت‌ها، باینری‌ها و فایل‌های پیکربندیِ بسته‌بندی‌شده با پلاگین استفاده کن. در دستورهای hook، از فرم exec با args استفاده کن تا مسیر به‌عنوان یک آرگومانِ واحد و بدون نقل‌قول پاس داده شود. در hookهای فرم-shell و دستورهای monitor، آن را در دابل‌کوتیشن بگذار، مثل "${CLAUDE_PLUGIN_ROOT}". این مسیر وقتی پلاگین به‌روزرسانی می‌شود تغییر می‌کند. پوشه‌ی نسخه‌ی قبلی حدود هفت روز پس از یک به‌روزرسانی، پیش از پاک‌سازی، روی دیسک می‌ماند، ولی آن را زودگذر تلقی کن و وضعیت را اینجا ننویس.

وقتی یک پلاگین در میانه‌ی نشست به‌روزرسانی می‌شود، دستورهای hook، monitorها، MCP serverها و LSP serverها از مسیر نسخه‌ی قبلی استفاده می‌کنند. /reload-plugins را اجرا کن تا hookها، MCP serverها و LSP serverها به مسیر جدید سوییچ کنند؛ monitorها به راه‌اندازی مجددِ نشست نیاز دارند.

${CLAUDE_PLUGIN_DATA}: یک پوشه‌ی پایدار برای وضعیتِ پلاگین که از به‌روزرسانی‌ها جان به در می‌برد. از این برای وابستگی‌های نصب‌شده مثل node_modules یا محیط‌های مجازیِ Python، کدِ تولیدشده، کش‌ها، و هر فایل دیگری که باید در طول نسخه‌های پلاگین ماندگار بماند استفاده کن. این پوشه اولین باری که به این متغیر ارجاع شود خودکار ساخته می‌شود.

${CLAUDE_PROJECT_DIR}: ریشه‌ی پروژه. این همان پوشه‌ای است که hookها در متغیر CLAUDE_PROJECT_DIRِ خود دریافت می‌کنند. از این برای ارجاع به اسکریپت‌ها یا فایل‌های پیکربندیِ محلیِ پروژه استفاده کن. برای مدیریت مسیرهای دارای فاصله، آن را در نقل‌قول بگذار، مثلاً "${CLAUDE_PROJECT_DIR}/scripts/server.sh". MCP serverها همچنین می‌توانند درخواستِ MCPِ roots/list را فراخوانی کنند، که پوشه‌ای را برمی‌گرداند که Claude Code از آن راه‌اندازی شده بود.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

پوشه‌ی داده‌ی پایدار

پوشه‌ی ${CLAUDE_PLUGIN_DATA} به ~/.claude/plugins/data/{id}/ تبدیل می‌شود، که {id} شناسه‌ی پلاگین است که کاراکترهای خارج از a-z، A-Z، 0-9، _ و - در آن با - جایگزین شده‌اند. برای پلاگینی که به‌صورت formatter@my-marketplace نصب شده، پوشه ~/.claude/plugins/data/formatter-my-marketplace/ است.

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

این hookِ SessionStart، در اولین اجرا و دوباره هرگاه یک به‌روزرسانیِ پلاگین شامل یک package.jsonِ تغییریافته باشد، node_modules را نصب می‌کند:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff وقتی کپیِ ذخیره‌شده گم باشد یا با کپیِ بسته‌بندی‌شده تفاوت داشته باشد با کدِ ناصفر خارج می‌شود، که هم اولین اجرا و هم به‌روزرسانی‌های تغییردهنده‌ی وابستگی را پوشش می‌دهد. اگر npm install شکست بخورد، rmِ انتهایی مانیفستِ کپی‌شده را حذف می‌کند تا نشست بعدی دوباره تلاش کند.

اسکریپت‌های بسته‌بندی‌شده در ${CLAUDE_PLUGIN_ROOT} می‌توانند سپس در برابر node_modulesِ پایدارشده اجرا شوند:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

پوشه‌ی داده وقتی پلاگین را از آخرین دامنه‌ای که در آن نصب است حذف نصب کنی خودکار حذف می‌شود. رابط /plugin اندازه‌ی پوشه را نشان می‌دهد و پیش از حذف می‌پرسد. CLI به‌صورت پیش‌فرض حذف می‌کند؛ برای حفظ آن --keep-data را پاس بده.

کش‌کردنِ پلاگین و حلِ فایل

پلاگین‌ها به یکی از دو روش مشخص می‌شوند:

از طریق claude --plugin-dir یا claude --plugin-url، برای مدت یک نشست.
از طریق یک بازارچه، نصب‌شده برای نشست‌های آینده.

به دلایل امنیتی و راستی‌آزمایی، Claude Code پلاگین‌های بازارچه‌ای را به‌جای استفاده در محل، به کشِ پلاگینِ محلیِ کاربر (~/.claude/plugins/cache) کپی می‌کند. درکِ این رفتار هنگام توسعه‌ی پلاگین‌هایی که به فایل‌های بیرونی ارجاع می‌دهند مهم است.

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

ابزارهای Glob و Grepِ Claude در طول جستجوها از پوشه‌های نسخه‌ی یتیم صرف‌نظر می‌کنند، پس نتایجِ فایل شامل کدِ قدیمیِ پلاگین نمی‌شوند.

محدودیت‌های پیمایش مسیر

پلاگین‌های نصب‌شده نمی‌توانند به فایل‌های خارج از پوشه‌ی خود ارجاع دهند. مسیرهایی که خارج از ریشه‌ی پلاگین می‌روند (مثل ../shared-utils) پس از نصب کار نمی‌کنند، چون آن فایل‌های بیرونی به کش کپی نمی‌شوند.

اشتراک‌گذاریِ فایل‌ها درون یک بازارچه با symlinkها

اگر پلاگینت لازم دارد فایل‌ها را با سایر بخش‌های همان بازارچه به اشتراک بگذارد، می‌توانی پیوندهای نمادین (symbolic links) درون پوشه‌ی پلاگینت بسازی. اینکه یک symlink وقتی پلاگین به کش کپی می‌شود چگونه اداره می‌شود، بستگی به این دارد که هدفش به کجا حل می‌شود:

درون پوشه‌ی خودِ پلاگین: symlink به‌عنوان یک symlinkِ نسبی در کش حفظ می‌شود، پس همچنان در زمان اجرا به هدفِ کپی‌شده حل می‌شود.
جای دیگری درون همان بازارچه: symlink dereference می‌شود. محتوای هدف به‌جای آن در کش کپی می‌شود. این به پوشه‌ی skills/ِ یک متا-پلاگین اجازه می‌دهد به skillهایی که پلاگین‌های دیگرِ بازارچه تعریف کرده‌اند پیوند بزند.
خارج از بازارچه: symlink به دلایل امنیتی صرف‌نظر می‌شود. این جلوی پلاگین‌ها را می‌گیرد که فایل‌های دلخواهِ میزبان مثل مسیرهای سیستمی را به کش بکشند.

برای پلاگین‌هایی که با --plugin-dir یا از یک مسیر محلی نصب می‌شوند، فقط symlinkهایی حفظ می‌شوند که درون پوشه‌ی خودِ پلاگین حل می‌شوند. بقیه صرف‌نظر می‌شوند.

دستور زیر از درون یک پلاگینِ بازارچه به یک skillِ مشترک که توسط یک پلاگینِ هم‌سطح تعریف شده پیوند می‌سازد. در ویندوز، از mklink /D در یک Command Promptِ بالابرده‌شده استفاده کن یا Developer Mode را فعال کن:

ln -s ../../shared-plugin/skills/foo ./skills/foo

این انعطاف فراهم می‌کند ضمن حفظ مزایای امنیتیِ سیستم کش.

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

چیدمان استاندارد پلاگین

یک پلاگینِ کامل این ساختار را دارد:

enterprise-plugin/
├── .claude-plugin/           # Metadata directory (optional)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills as flat .md files
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Output style definitions
│   └── terse.md
├── themes/                   # Color theme definitions
│   └── dracula.json
├── monitors/                 # Background monitor configurations
│   └── monitors.json
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── bin/                      # Plugin executables added to PATH
│   └── my-tool               # Invokable as bare command in Bash tool
├── settings.json            # Default settings for the plugin
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history

یک فایل CLAUDE.md در ریشه‌ی پلاگین به‌عنوان کانتکستِ پروژه بارگذاری نمی‌شود. پلاگین‌ها به‌جای CLAUDE.md، از طریق skillها، agentها و hookها به کانتکست کمک می‌کنند. برای عرضه‌ی دستورالعمل‌هایی که به کانتکستِ Claude بارگذاری می‌شوند، آن‌ها را در یک skill بگذار.

مرجع محل‌های فایل

کامپوننت	محل پیش‌فرض	هدف
مانیفست	`.claude-plugin/plugin.json`	فراداده و پیکربندیِ پلاگین (اختیاری)
Skills	`skills/`	skillها با ساختار `<name>/SKILL.md`
Commands	`commands/`	skillها به‌صورت فایل‌های Markdownِ تخت. برای پلاگین‌های جدید از `skills/` استفاده کن
Agents	`agents/`	فایل‌های Markdownِ ساب‌ایجنت
Output styles	`output-styles/`	تعریف‌های سبکِ خروجی
Themes	`themes/`	تعریف‌های تم رنگی
Hooks	`hooks/hooks.json`	پیکربندیِ hook
MCP servers	`.mcp.json`	تعریف‌های MCP server
LSP servers	`.lsp.json`	پیکربندی‌های language server
Monitors	`monitors/monitors.json`	پیکربندی‌های monitorِ پس‌زمینه
Executables	`bin/`	فایل‌های اجراییِ افزوده‌شده به `PATH`ِ ابزار Bash. فایل‌های اینجا تا وقتی پلاگین فعال است در هر فراخوانیِ ابزار Bash به‌صورت دستورِ ساده قابل فراخوانی‌اند
Settings	`settings.json`	پیکربندیِ پیش‌فرض که هنگام فعال‌شدنِ پلاگین اعمال می‌شود. در حال حاضر فقط کلیدهای `agent` و `subagentStatusLine` پشتیبانی می‌شوند

مرجع دستورهای CLI

Claude Code دستورهای CLI برای مدیریت غیرتعاملیِ پلاگین فراهم می‌کند که برای اسکریپت‌نویسی و خودکارسازی مفیدند.

plugin init

داربست‌بندیِ یک پلاگین جدید در ~/.claude/skills/<name>/. در نشست بعدیِ Claude Code خودکار به‌صورت <name>@skills-dir بارگذاری می‌شود و بدون گام نصب در /plugin و claude plugin list ظاهر می‌شود.

برای الزامات دامنه و اعتماد، پلاگین‌های پوشه‌ی skills را ببین.

claude plugin init <name> [options]

آرگومان‌ها:

<name>: نام پلاگین. تبدیل به فضای‌نامِ skill و نام پوشه زیرِ ~/.claude/skills/ می‌شود، پس نمی‌تواند شامل فاصله یا جداکننده‌ی مسیر باشد.

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`--description <text>`	توضیحِ مانیفست
`--author <name>`	نام نویسنده	`git config user.name`
`--author-email <email>`	ایمیل نویسنده	`git config user.email`
`--with <components...>`	همچنین پوشه‌های کامپوننت را داربست‌بندی کن. مقادیر معتبر: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel`
`-f, --force`	بازنویسیِ یک `.claude-plugin/`ِ موجود در مقصد
`-h, --help`	نمایش راهنمای دستور

نام‌های مستعار: new

هر مقدار --with یک فایلِ آغازین برای آن کامپوننت اضافه می‌کند، آماده‌ی ویرایش:

کامپوننت	چه چیزی را داربست‌بندی می‌کند
`skills`	یک skillِ فضای‌نام‌دارِ اضافیِ `<name>:example` در کنار skillِ پیش‌فرض
`agents`	یک تعریفِ ساب‌ایجنتِ `agents/`
`hooks`	یک `hooks/hooks.json` با یک نمونه هندلر رویداد
`mcp`	یک `.mcp.json` با مثال‌های serverِ HTTP و stdio
`lsp`	یک مثالِ language-serverِ `.lsp.json`
`output-style`	یک `output-styles/<name>.md` که تا وقتی پلاگین فعال است خودکار اعمال می‌شود
`channel`	یک channelِ مبتنی بر MCP: یک serverِ stdio (`server.ts`)، `.mcp.json`ِ آن، و یک `package.json`

پلاگینِ داربست‌بندی‌شده به‌جای یک بازارچه از منبع @skills-dir استفاده می‌کند. مدیران می‌توانند این منبع را با strictKnownMarketplaces یا با افزودنِ {"source": "skills-dir"} به blockedMarketplaces در تنظیمات مدیریت‌شده مسدود کنند. وقتی مسدود شود، plugin init پیش از نوشتن شکست می‌خورد.

مثال‌ها:

# Scaffold a minimal plugin
claude plugin init my-helper

# Scaffold with skill and hook folders
claude plugin init my-helper --with skills hooks

# Overwrite an existing scaffold
claude plugin init my-helper --force

plugin install

نصب یک پلاگین از بازارچه‌های موجود.

claude plugin install <plugin> [options]

آرگومان‌ها:

<plugin>: نام پلاگین یا plugin-name@marketplace-name برای یک بازارچه‌ی مشخص

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	دامنه‌ی نصب: `user`, `project` یا `local`	`user`
`-h, --help`	نمایش راهنمای دستور

دامنه تعیین می‌کند پلاگینِ نصب‌شده به کدام فایل تنظیمات اضافه شود. مثلاً، --scope project در enabledPlugins در .claude/settings.json می‌نویسد و پلاگین را برای هر کسی که مخزن پروژه را clone می‌کند در دسترس می‌سازد.

مثال‌ها:

# Install to user scope (default)
claude plugin install formatter@my-marketplace

# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project

# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

حذف یک پلاگینِ نصب‌شده.

claude plugin uninstall <plugin> [options]

آرگومان‌ها:

<plugin>: نام پلاگین یا plugin-name@marketplace-name

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	حذف نصب از دامنه: `user`, `project` یا `local`	`user`
`--keep-data`	حفظ پوشه‌ی داده‌ی پایدارِ پلاگین
`--prune`	همچنین وابستگی‌های خودکار-نصب‌شده‌ای را که هیچ پلاگین دیگری لازمشان ندارد حذف کن. plugin prune را ببین
`-y, --yes`	رد کردن از تأییدیه‌ی `--prune`. وقتی stdin یا stdout یک TTY نباشد الزامی است
`-h, --help`	نمایش راهنمای دستور

نام‌های مستعار: remove, rm

به‌صورت پیش‌فرض، حذف نصب از آخرین دامنه‌ی باقی‌مانده، پوشه‌ی ${CLAUDE_PLUGIN_DATA}ِ پلاگین را هم حذف می‌کند. از --keep-data برای حفظ آن استفاده کن، مثلاً وقتی پس از آزمایشِ یک نسخه‌ی جدید دوباره نصب می‌کنی.

plugin prune

حذف وابستگی‌های خودکار-نصب‌شده‌ی پلاگین که دیگر توسط هیچ پلاگینِ نصب‌شده‌ای لازم نیستند. وابستگی‌هایی که Claude Code برای برآورده‌کردنِ فیلد dependenciesِ پلاگینِ دیگری کشیده بود حذف می‌شوند؛ پلاگین‌هایی که خودت مستقیماً نصب کرده‌ای هرگز دست نمی‌خورند.

claude plugin prune [options]

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	پاک‌سازی در دامنه: `user`, `project` یا `local`	`user`
`--dry-run`	فهرست‌کردنِ آنچه حذف می‌شد بدون حذفِ چیزی
`-y, --yes`	رد کردن از تأییدیه. وقتی stdin یا stdout یک TTY نباشد الزامی است
`-h, --help`	نمایش راهنمای دستور

نام‌های مستعار: autoremove

این دستور وابستگی‌های یتیم را فهرست می‌کند و پیش از حذفشان تأییدیه می‌خواهد. برای حذف یک پلاگین و پاک‌سازیِ وابستگی‌هایش در یک گام، claude plugin uninstall <plugin> --prune را اجرا کن.

plugin enable

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

claude plugin enable <plugin> [options]

آرگومان‌ها:

<plugin>: نام پلاگین یا plugin-name@marketplace-name

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	دامنه‌ای که فعال شود: `user`, `project` یا `local`	`user`
`-h, --help`	نمایش راهنمای دستور

plugin disable

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

claude plugin disable <plugin> [options]

آرگومان‌ها:

<plugin>: نام پلاگین یا plugin-name@marketplace-name

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	دامنه‌ای که غیرفعال شود: `user`, `project` یا `local`	`user`
`-h, --help`	نمایش راهنمای دستور

plugin update

به‌روزرسانی یک پلاگین به آخرین نسخه.

claude plugin update <plugin> [options]

آرگومان‌ها:

<plugin>: نام پلاگین یا plugin-name@marketplace-name

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-s, --scope <scope>`	دامنه‌ای که به‌روزرسانی شود: `user`, `project`, `local` یا `managed`	`user`
`-h, --help`	نمایش راهنمای دستور

plugin list

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

claude plugin list [options]

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`--json`	خروجی به‌صورت JSON
`--available`	شامل پلاگین‌های موجود از بازارچه‌ها. به `--json` نیاز دارد
`-h, --help`	نمایش راهنمای دستور

درون یک نشست تعاملی، /plugin list همان فهرست را به‌صورت درون‌خطی چاپ می‌کند. فرم تعاملی --enabled یا --disabled را می‌پذیرد تا فقط پلاگین‌های آن وضعیت را نشان دهد، و ls را به‌عنوان کوتاه‌نوشتِ list.

plugin details

نمایش فهرست کامپوننت‌های یک پلاگین و هزینه‌ی توکنِ پیش‌بینی‌شده. خروجی، همه‌ی کامپوننت‌هایی را که پلاگین کمک می‌کند فهرست می‌کند، گروه‌بندی‌شده به‌صورت Skillها، Agentها، Hookها، MCP serverها و LSP serverها، همراه با برآوردی از اینکه چند توکن به هر نشست اضافه می‌کند. گروهِ Skillها هم ورودی‌های skills/ و هم commands/ را در بر می‌گیرد.

claude plugin details <name>

آرگومان‌ها:

<name>: نام پلاگین یا plugin-name@marketplace-name

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`-h, --help`	نمایش راهنمای دستور

خروجی برای هر کامپوننت دو رقمِ هزینه نشان می‌دهد:

همیشه-روشن (Always-on): توکن‌هایی که متنِ فهرستِ پلاگین — مثل توصیف‌های skill، توصیف‌های agent و نام commandها — صرف‌نظر از اینکه هیچ کامپوننتی شلیک شود یا نه، به هر نشست اضافه می‌کند.
در-فراخوانی (On-invoke): توکن‌هایی که یک کامپوننت هنگام شلیک هزینه می‌کند. به‌ازای هر کامپوننت نشان داده می‌شود، نه به‌صورت یک کلِ پلاگین، چون یک نشست معمولی فقط زیرمجموعه‌ای از کامپوننت‌ها را فراخوانی می‌کند.

این مثال نشان می‌دهد خروجی برای پلاگینی با دو skill چه شکلی است:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

کلِ همیشه-روشن از طریق API ِ count_tokens برای مدلِ فعالت محاسبه می‌شود. اعداد هر-کامپوننت به‌نسبت از آن کل مقیاس‌گذاری می‌شوند. اگر API در دسترس نباشد، دستور به یک برآوردِ مبتنی بر کاراکتر برمی‌گردد.

plugin tag

ساختِ یک تگِ گیتِ انتشار برای پلاگینِ پوشه‌ی جاری. از درون پوشه‌ی پلاگین اجرا کن. تگ‌کردنِ انتشارهای پلاگین را ببین.

claude plugin tag [options]

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`--push`	پس از ساختِ تگ، آن را به remote پوش کن
`--dry-run`	چاپِ آنچه تگ می‌شد بدون ساختِ تگ
`-f, --force`	حتی اگر درختِ کاری کثیف باشد یا تگ از قبل وجود داشته باشد، تگ را بساز
`-h, --help`	نمایش راهنمای دستور

ابزارهای عیب‌یابی و توسعه

دستورهای عیب‌یابی

از claude --debug استفاده کن تا جزئیات بارگذاریِ پلاگین را ببینی:

این موارد را نشان می‌دهد:

اینکه کدام پلاگین‌ها در حال بارگذاری‌اند
هر خطایی در مانیفست‌های پلاگین
ثبتِ skill، agent و hook
مقداردهیِ اولیه‌ی MCP server

مشکلات رایج

مشکل	علت	راه‌حل
پلاگین بارگذاری نمی‌شود	`plugin.json`ِ نامعتبر	`claude plugin validate` یا `/plugin validate` را اجرا کن تا `plugin.json`، frontmatterِ skill/agent/command و `hooks/hooks.json` را از نظر خطاهای نحو و اسکیما بررسی کنی
skillها ظاهر نمی‌شوند	ساختار پوشه‌ی نادرست	مطمئن شو `skills/` یا `commands/` در ریشه‌ی پلاگین است، نه درون `.claude-plugin/`
hookها شلیک نمی‌شوند	اسکریپت اجرایی نیست	`chmod +x script.sh` را اجرا کن
MCP server شکست می‌خورد	نبودِ `${CLAUDE_PLUGIN_ROOT}`	برای همه‌ی مسیرهای پلاگین از متغیر استفاده کن
خطاهای مسیر	استفاده از مسیرهای مطلق	همه‌ی مسیرها باید نسبی باشند و با `./` شروع شوند
LSPِ `Executable not found in $PATH`	language server نصب‌نشده	باینری را نصب کن (مثلاً `npm install -g typescript-language-server typescript`)

نمونه پیام‌های خطا

خطاهای اعتبارسنجیِ مانیفست:

Invalid JSON syntax: Unexpected token } in JSON at position 142: کاما‌های گم‌شده، کاما‌های اضافی، یا رشته‌های بدون نقل‌قول را بررسی کن
Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: یک فیلد الزامی گم است
Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: خطای نحو JSON

خطاهای بارگذاریِ پلاگین:

Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: مسیر command وجود دارد ولی شامل هیچ فایل commandِ معتبری نیست
Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: مسیر source در marketplace.json به یک پوشه‌ی ناموجود اشاره می‌کند
Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: تعریف‌های تکراریِ کامپوننت را حذف کن یا strict: false را در ورودیِ بازارچه بردار

عیب‌یابی hook

اسکریپتِ hook اجرا نمی‌شود:

بررسی کن اسکریپت اجرایی باشد: chmod +x ./scripts/your-script.sh
خطِ shebang را راستی‌آزمایی کن: خط اول باید #!/bin/bash یا #!/usr/bin/env bash باشد
بررسی کن مسیر از ${CLAUDE_PLUGIN_ROOT} استفاده کند: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
اسکریپت را دستی تست کن: ./scripts/your-script.sh

hook روی رویدادهای موردانتظار شلیک نمی‌شود:

راستی‌آزمایی کن نام رویداد درست باشد (حساس به بزرگی/کوچکی): PostToolUse, نه postToolUse
بررسی کن الگوی matcher با ابزارهایت مطابقت دارد: "matcher": "Write|Edit" برای عملیات فایل
تأیید کن نوع hook معتبر است: command, http, mcp_tool, prompt یا agent

عیب‌یابی MCP server

server راه نمی‌افتد:

بررسی کن دستور وجود دارد و اجرایی است
راستی‌آزمایی کن همه‌ی مسیرها از متغیر ${CLAUDE_PLUGIN_ROOT} استفاده می‌کنند
لاگ‌های MCP server را بررسی کن: claude --debug خطاهای مقداردهیِ اولیه را نشان می‌دهد
server را به‌صورت دستی بیرون از Claude Code تست کن

ابزارهای server ظاهر نمی‌شوند:

مطمئن شو server به‌درستی در .mcp.json یا plugin.json پیکربندی شده
راستی‌آزمایی کن server پروتکل MCP را درست پیاده‌سازی می‌کند
در خروجی debug، timeoutهای اتصال را بررسی کن

اشتباهات ساختار پوشه

نشانه‌ها: پلاگین بارگذاری می‌شود ولی کامپوننت‌ها (skillها، agentها، hookها) گم‌اند.

ساختار درست: کامپوننت‌ها باید در ریشه‌ی پلاگین باشند، نه درون .claude-plugin/. فقط plugin.json در .claude-plugin/ جا دارد.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Only manifest here
├── commands/            ← At root level
├── agents/              ← At root level
└── hooks/               ← At root level

اگر کامپوننت‌هایت درون .claude-plugin/ هستند، آن‌ها را به ریشه‌ی پلاگین منتقل کن.

فهرست بررسیِ debug:

claude --debug را اجرا کن و دنبال پیام‌های “loading plugin” بگرد
بررسی کن هر پوشه‌ی کامپوننت در خروجی debug فهرست شده باشد
راستی‌آزمایی کن مجوزهای فایل اجازه‌ی خواندنِ فایل‌های پلاگین را می‌دهند

مرجع توزیع و نسخه‌گذاری

مدیریت نسخه

Claude Code از نسخه‌ی پلاگین به‌عنوان کلید کش استفاده می‌کند که تعیین می‌کند آیا به‌روزرسانی‌ای در دسترس است. وقتی /plugin update را اجرا می‌کنی یا به‌روزرسانیِ خودکار شلیک می‌شود، Claude Code نسخه‌ی جاری را محاسبه می‌کند و اگر با آنچه از قبل نصب شده مطابق باشد از به‌روزرسانی صرف‌نظر می‌کند.

نسخه از اولینِ این‌ها که تنظیم شده باشد حل می‌شود:

فیلد version در plugin.jsonِ پلاگین
فیلد version در ورودیِ بازارچه‌ی پلاگین در marketplace.json
SHAِ کامیتِ گیتِ منبعِ پلاگین، برای منابع github، url، git-subdir و مسیرهای نسبی در یک بازارچه‌ی میزبانی‌شده روی git
unknown، برای منابع npm یا پوشه‌های محلی که درون یک مخزن git نیستند

این به تو دو راه برای نسخه‌گذاریِ یک پلاگین می‌دهد:

رویکرد	چگونه	رفتار به‌روزرسانی	بهترین برای
نسخه‌ی صریح	`"version": "2.1.0"` را در `plugin.json` بگذار	کاربران فقط وقتی این فیلد را بالا ببری به‌روزرسانی می‌گیرند. پوش‌کردنِ کامیت‌های جدید بدون بالابردنش اثری ندارد، و `/plugin update` گزارش می‌دهد «از قبل در آخرین نسخه».	پلاگین‌های منتشرشده با چرخه‌های انتشارِ پایدار
نسخه‌ی SHA-کامیت	`version` را هم از `plugin.json` و هم از ورودیِ بازارچه حذف کن	کاربران در هر کامیتِ جدید به منبعِ گیتِ پلاگین به‌روزرسانی می‌گیرند	پلاگین‌های داخلی یا تیمیِ تحت توسعه‌ی فعال

اگر از نسخه‌های صریح استفاده می‌کنی، از نسخه‌گذاریِ معنایی (MAJOR.MINOR.PATCH) پیروی کن: MAJOR را برای تغییرات شکننده، MINOR را برای قابلیت‌های جدید، و PATCH را برای رفعِ باگ بالا ببر. تغییرات را در یک CHANGELOG.md مستند کن.

همچنین ببین

Plugins - آموزش‌ها و استفاده‌ی عملی
بازارچه‌های پلاگین - ساخت و مدیریت بازارچه‌ها
Skills - جزئیات توسعه‌ی skill
Subagents - پیکربندی و توانمندی‌های agent
Hooks - مدیریت رویداد و خودکارسازی
MCP - یکپارچه‌سازیِ ابزار بیرونی
Settings - گزینه‌های پیکربندی برای پلاگین‌ها