ساخت و توزیعِ یک مارکت‌پلیسِ پلاگین

یک مارکت‌پلیسِ پلاگین کاتالوگی است که می‌گذارد پلاگین‌ها را به دیگران توزیع کنی. مارکت‌پلیس‌ها کشفِ متمرکز، ردگیریِ نسخه، به‌روزرسانیِ خودکار و پشتیبانی از چند نوع منبع (مخازنِ git، مسیرهای محلی و بیشتر) را فراهم می‌کنند. این راهنما نشانت می‌دهد چطور مارکت‌پلیسِ خودت را بسازی تا پلاگین‌ها را با تیم یا جامعه‌ات به اشتراک بگذاری.

دنبالِ نصبِ پلاگین از یک مارکت‌پلیسِ موجود هستی؟ کشف و نصبِ پلاگین‌های آماده را ببین.

مرورِ کلی

ساخت و توزیعِ یک مارکت‌پلیس شاملِ این‌هاست:

ساختِ پلاگین‌ها: یک یا چند پلاگین با skillها، agentها، hookها، سرورهای MCP یا سرورهای LSP بساز. این راهنما فرض می‌کند که از قبل پلاگین‌هایی برای توزیع داری؛ برای جزئیاتِ ساختشان ساختِ پلاگین‌ها را ببین.
ساختِ یک فایلِ مارکت‌پلیس: یک marketplace.json تعریف کن که پلاگین‌هایت و جای پیداکردنشان را فهرست کند (ساختِ فایلِ مارکت‌پلیس را ببین).
میزبانیِ مارکت‌پلیس: به GitHub، GitLab یا میزبانِ گیتِ دیگری push کن (میزبانی و توزیعِ مارکت‌پلیس‌ها را ببین).
اشتراک با کاربران: کاربران مارکت‌پلیست را با /plugin marketplace add اضافه می‌کنند و پلاگین‌های جداگانه نصب می‌کنند (کشف و نصبِ پلاگین‌ها را ببین).

وقتی مارکت‌پلیست زنده شد، می‌توانی با push کردنِ تغییرات به مخزنت به‌روزش کنی. کاربران نسخه‌ی محلیشان را با /plugin marketplace update تازه می‌کنند.

گام‌به‌گام: یک مارکت‌پلیسِ محلی بساز

این مثال یک مارکت‌پلیس با یک پلاگین می‌سازد: یک skill با نامِ quality-review برای بازبینیِ کد. ساختارِ دایرکتوری را می‌سازی، یک skill اضافه می‌کنی، مانیفستِ پلاگین و کاتالوگِ مارکت‌پلیس را می‌سازی، سپس نصب و تستش می‌کنی.

ساختارِ دایرکتوری را بساز

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

skill را بساز

یک فایلِ SKILL.md بساز که تعریف کند skillِ quality-review چه می‌کند.

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

مانیفستِ پلاگین را بساز

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

{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0"
}

فایلِ مارکت‌پلیس را بساز

کاتالوگِ مارکت‌پلیس را که پلاگینت را فهرست می‌کند بساز.

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

اضافه و نصب کن

مارکت‌پلیس را اضافه و پلاگین را نصب کن.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

امتحانش کن

در ویرایشگرت مقداری کد انتخاب کن و skillِ جدیدت را اجرا کن. skillهای پلاگین با نامِ پلاگین namespace می‌شوند.

/quality-review-plugin:quality-review

برای دانستنِ بیشتر درباره‌ی آنچه پلاگین‌ها می‌توانند انجام دهند، شاملِ hookها، agentها، سرورهای MCP و سرورهای LSP، پلاگین‌ها را ببین.

فایلِ مارکت‌پلیس را بساز

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

هر ورودیِ پلاگین دستِ‌کم به یک name و source (جای fetch کردنش) نیاز دارد. برای همه‌ی فیلدهای موجود اسکیمای کامل را در پایین ببین.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

اسکیمای مارکت‌پلیس

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

فیلد	نوع	توضیح	مثال
`name`	string	شناسه‌ی مارکت‌پلیس (kebab-case، بدونِ فاصله). این عمومی است: کاربران هنگامِ نصبِ پلاگین‌ها آن را می‌بینند (برای مثال، `/plugin install my-tool@your-marketplace`). هر کاربر می‌تواند فقط یک مارکت‌پلیس به‌ازای هر نام ثبت کند: افزودنِ مارکت‌پلیسِ دومی با همان نام جایگزینِ اولی می‌شود. برای انتشارِ چند پلاگین زیرِ یک نامِ مارکت‌پلیس، همه را در یک `marketplace.json` واحد فهرست کن.	`"acme-tools"`
`owner`	object	اطلاعاتِ نگه‌دارنده‌ی مارکت‌پلیس (فیلدها را در پایین ببین)
`plugins`	array	فهرستِ پلاگین‌های موجود	پایین را ببین

فیلدهای owner

فیلد	نوع	الزامی	توضیح
`name`	string	بله	نامِ نگه‌دارنده یا تیم
`email`	string	خیر	ایمیلِ تماسِ نگه‌دارنده

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

فیلد	نوع	توضیح
`$schema`	string	آدرسِ JSON Schema برای تکمیلِ خودکار و اعتبارسنجیِ ویرایشگر. Claude Code این فیلد را در زمانِ بارگذاری نادیده می‌گیرد.
`description`	string	توضیحِ کوتاهِ مارکت‌پلیس
`version`	string	نسخه‌ی مانیفستِ مارکت‌پلیس
`metadata.pluginRoot`	string	دایرکتوریِ پایه‌ای که به مسیرهای منبعِ نسبیِ پلاگین پیشوند می‌شود (برای مثال، `"./plugins"` می‌گذارد به‌جای `"source": "./plugins/formatter"` بنویسی `"source": "formatter"`)
`allowCrossMarketplaceDependenciesOn`	array	مارکت‌پلیس‌های دیگری که پلاگین‌های این مارکت‌پلیس می‌توانند به آن‌ها وابسته باشند. وابستگی‌ها از مارکت‌پلیسی که اینجا فهرست نشده، هنگامِ نصب مسدود می‌شوند. به یک پلاگین از مارکت‌پلیسی دیگر وابسته شو را ببین.

description و version برای سازگاریِ عقب‌رو زیرِ metadata هم پذیرفته می‌شوند.

ورودی‌های پلاگین

هر ورودیِ پلاگین در آرایه‌ی plugins یک پلاگین و جای پیداکردنش را توصیف می‌کند. می‌توانی هر فیلدی از اسکیمای مانیفستِ پلاگین (مثلِ description، version، author، commands، hooks و غیره) را به‌علاوه‌ی این فیلدهای مخصوصِ مارکت‌پلیس بگنجانی: source، category، tags و strict.

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

فیلد	نوع	توضیح
`name`	string	شناسه‌ی پلاگین (kebab-case، بدونِ فاصله). این عمومی است: کاربران هنگامِ نصب آن را می‌بینند (برای مثال، `/plugin install my-plugin@marketplace`).
`source`	string\|object	جای fetch کردنِ پلاگین (منابعِ پلاگین را در پایین ببین)

فیلدهای اختیاریِ پلاگین

فیلدهای استانداردِ متادیتا:

فیلد	نوع	توضیح
`displayName`	string	نامِ خواندنی برای انسان که در سطح‌های UI نشان داده می‌شود. وقتی حذف شود به `name` برمی‌گردد. می‌تواند فاصله و هر حروفِ بزرگ/کوچک داشته باشد. برای namespacing یا lookup استفاده نمی‌شود. به Claude Code نسخه‌ی v2.1.143 یا بالاتر نیاز دارد.
`description`	string	توضیحِ کوتاهِ پلاگین
`version`	string	نسخه‌ی پلاگین. اگر تنظیم شود (اینجا یا در `plugin.json`)، پلاگین به این رشته pin می‌شود و کاربران فقط وقتی تغییر کند به‌روزرسانی دریافت می‌کنند. حذفش کن تا به SHAی کامیتِ git برگردد. resolveِ نسخه را ببین.
`author`	object	اطلاعاتِ نویسنده‌ی پلاگین (`name` الزامی، `email` اختیاری)
`homepage`	string	آدرسِ صفحه‌ی اصلی یا مستنداتِ پلاگین
`repository`	string	آدرسِ مخزنِ کدِ منبع
`license`	string	شناسه‌ی لایسنسِ SPDX (برای مثال، MIT، Apache-2.0)
`keywords`	array	تگ‌ها برای کشف و دسته‌بندیِ پلاگین
`category`	string	دسته‌ی پلاگین برای سازماندهی
`tags`	array	تگ‌ها برای جست‌وجوپذیری
`strict`	boolean	کنترل می‌کند که آیا `plugin.json` مرجعِ تعاریفِ کامپوننت است (پیش‌فرض: true). حالتِ strict را در پایین ببین.
`defaultEnabled`	boolean	آیا پلاگین پس از نصب فعال است (پیش‌فرض: true). روی `false` تنظیم کن تا پلاگین غیرفعال نصب شود تا وقتی کاربر آن را انتخاب کند. بر همان فیلد در `plugin.json` پلاگین تقدم دارد. فعال‌بودنِ پیش‌فرض را ببین. به Claude Code نسخه‌ی v2.1.154 یا بالاتر نیاز دارد.

فیلدهای پیکربندیِ کامپوننت:

فیلد	نوع	توضیح
`skills`	string\|array	مسیرهای سفارشی به دایرکتوری‌های skill که شاملِ `<name>/SKILL.md` هستند
`commands`	string\|array	مسیرهای سفارشی به فایل‌های `.md` تختِ skill یا دایرکتوری‌ها
`agents`	string\|array	مسیرهای سفارشی به فایل‌های agent
`hooks`	string\|object	پیکربندیِ سفارشیِ hookها یا مسیر به فایلِ hooks
`mcpServers`	string\|object	پیکربندی‌های سرورِ MCP یا مسیر به پیکربندیِ MCP
`lspServers`	string\|object	پیکربندی‌های سرورِ LSP یا مسیر به پیکربندیِ LSP

منابعِ پلاگین

منابعِ پلاگین به Claude Code می‌گویند هر پلاگینِ جداگانه‌ی فهرست‌شده در مارکت‌پلیست را از کجا fetch کند. این‌ها در فیلدِ source هر ورودیِ پلاگین در marketplace.json تنظیم می‌شوند.

وقتی پلاگینی به دستگاهِ محلی clone یا کپی شد، به cacheِ نسخه‌بندی‌شده‌ی محلیِ پلاگین در ~/.claude/plugins/cache کپی می‌شود.

منبع	نوع	فیلدها	یادداشت‌ها
مسیرِ نسبی	`string` (مثلاً `"./my-plugin"`)	هیچ	دایرکتوریِ محلی درونِ مخزنِ مارکت‌پلیس. باید با `./` شروع شود. نسبت به ریشه‌ی مارکت‌پلیس resolve می‌شود، نه دایرکتوریِ `.claude-plugin/`
`github`	object	`repo`، `ref?`، `sha?`
`url`	object	`url`، `ref?`، `sha?`	منبعِ Git URL
`git-subdir`	object	`url`، `path`، `ref?`، `sha?`	زیردایرکتوری درونِ یک مخزنِ git. برای کم‌کردنِ پهنای باند در monorepoها به‌صورتِ sparse clone می‌شود
`npm`	object	`package`، `version?`، `registry?`	از طریقِ `npm install` نصب می‌شود

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

منبعِ مارکت‌پلیس — جای fetch کردنِ خودِ کاتالوگِ marketplace.json. وقتی کاربران /plugin marketplace add را اجرا می‌کنند یا در تنظیماتِ extraKnownMarketplaces تنظیم می‌شود. از ref (شاخه/تگ) پشتیبانی می‌کند ولی نه sha.
منبعِ پلاگین — جای fetch کردنِ یک پلاگینِ جداگانه‌ی فهرست‌شده در مارکت‌پلیس. در فیلدِ source هر ورودیِ پلاگین درونِ marketplace.json تنظیم می‌شود. هم از ref (شاخه/تگ) و هم sha (کامیتِ دقیق) پشتیبانی می‌کند.

برای مثال، یک مارکت‌پلیسِ میزبانی‌شده در acme-corp/plugin-catalog (منبعِ مارکت‌پلیس) می‌تواند پلاگینی را که از acme-corp/code-formatter (منبعِ پلاگین) fetch می‌شود فهرست کند. منبعِ مارکت‌پلیس و منبعِ پلاگین به مخازنِ متفاوتی اشاره می‌کنند و مستقل pin می‌شوند.

نوع‌های منبعِ git-محورِ زیر github، url و git-subdir هستند. وقتی هر دو ref و sha روی هرکدامشان تنظیم شوند، sha پینِ مؤثر است. Claude Code کامیتِ pin‌شده را مستقیماً fetch و checkout می‌کند، پس نصب موفق می‌شود حتی اگر شاخه یا تگی که ref نام می‌برد از آن زمان upstream حذف شده باشد، تا وقتی کامیت هنوز از مخزن قابلِ دسترس باشد.

مسیرهای نسبی

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

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

مسیرها نسبت به ریشه‌ی مارکت‌پلیس resolve می‌شوند، که دایرکتوریِ دربرگیرنده‌ی .claude-plugin/ است. در مثالِ بالا، ./plugins/my-plugin به <repo>/plugins/my-plugin اشاره می‌کند، حتی اگر marketplace.json در <repo>/.claude-plugin/marketplace.json زندگی کند. از ../ برای ارجاع به مسیرهای بیرونِ ریشه‌ی مارکت‌پلیس استفاده نکن.

مخازنِ GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

می‌توانی به یک شاخه، تگ یا کامیتِ مشخص pin کنی:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

فیلد	نوع	توضیح
`repo`	string	الزامی. مخزنِ GitHub در قالبِ `owner/repo`
`ref`	string	اختیاری. شاخه یا تگِ git (پیش‌فرض: شاخه‌ی پیش‌فرضِ مخزن)
`sha`	string	اختیاری. SHAی کاملِ ۴۰ کاراکتریِ کامیتِ git برای pin کردن به نسخه‌ی دقیق

مخازنِ Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

می‌توانی به یک شاخه، تگ یا کامیتِ مشخص pin کنی:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

فیلد	نوع	توضیح
`url`	string	الزامی. آدرسِ کاملِ مخزنِ git (`https://` یا `git@`). پسوندِ `.git` اختیاری است، پس URLهای Azure DevOps و AWS CodeCommit بدونِ پسوند کار می‌کنند
`ref`	string	اختیاری. شاخه یا تگِ git (پیش‌فرض: شاخه‌ی پیش‌فرضِ مخزن)
`sha`	string	اختیاری. SHAی کاملِ ۴۰ کاراکتریِ کامیتِ git برای pin کردن به نسخه‌ی دقیق

زیردایرکتوری‌های Git

از git-subdir برای اشاره به پلاگینی که درونِ زیردایرکتوریِ یک مخزنِ git زندگی می‌کند استفاده کن. Claude Code از یک cloneِ sparse و partial استفاده می‌کند تا فقط زیردایرکتوری را fetch کند و پهنای باند را برای monorepoهای بزرگ کم کند.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

می‌توانی به یک شاخه، تگ یا کامیتِ مشخص pin کنی:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

فیلدِ url همچنین یک شورتِ‌هندِ GitHub (owner/repo) یا URLهای SSH (git@github.com:owner/repo.git) را می‌پذیرد.

فیلد	نوع	توضیح
`url`	string	الزامی. آدرسِ مخزنِ git، شورتِ‌هندِ `owner/repo` در GitHub، یا URLِ SSH
`path`	string	الزامی. مسیرِ زیردایرکتوری درونِ مخزن که شاملِ پلاگین است (برای مثال، `"tools/claude-plugin"`)
`ref`	string	اختیاری. شاخه یا تگِ git (پیش‌فرض: شاخه‌ی پیش‌فرضِ مخزن)
`sha`	string	اختیاری. SHAی کاملِ ۴۰ کاراکتریِ کامیتِ git برای pin کردن به نسخه‌ی دقیق

پکیج‌های npm

پلاگین‌هایی که به‌صورتِ پکیجِ npm توزیع می‌شوند با npm install نصب می‌شوند. این با هر پکیجی روی registryِ عمومیِ npm یا یک registryِ خصوصی که تیمت میزبانی می‌کند کار می‌کند.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

برای pin کردن به نسخه‌ی مشخص، فیلدِ version را اضافه کن:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

برای نصب از یک registryِ خصوصی یا داخلی، فیلدِ registry را اضافه کن:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

فیلد	نوع	توضیح
`package`	string	الزامی. نامِ پکیج یا پکیجِ scoped (برای مثال، `@org/plugin`)
`version`	string	اختیاری. نسخه یا بازه‌ی نسخه (برای مثال، `2.1.0`، `^2.0.0`، `~1.5.0`)
`registry`	string	اختیاری. آدرسِ registryِ npm سفارشی. پیش‌فرض: registryِ npm سیستم (معمولاً npmjs.org)

ورودی‌های پیشرفته‌ی پلاگین

این مثال یک ورودیِ پلاگین را نشان می‌دهد که از بسیاری از فیلدهای اختیاری استفاده می‌کند، شاملِ مسیرهای سفارشی برای commandها، agentها، hookها و سرورهای MCP:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

نکاتِ مهمی که باید توجه کنی:

commands و agents: می‌توانی چند دایرکتوری یا فایل‌های جداگانه مشخص کنی. مسیرها نسبت به ریشه‌ی پلاگین هستند.
${CLAUDE_PLUGIN_ROOT}: از این متغیر در hookها و پیکربندی‌های سرورِ MCP استفاده کن تا به فایل‌های درونِ دایرکتوریِ نصبِ پلاگین ارجاع دهی. این لازم است چون پلاگین‌ها هنگامِ نصب به یک محلِ cache کپی می‌شوند. برای وابستگی‌ها یا state که باید از به‌روزرسانی‌های پلاگین جان به در ببرند، به‌جایش از ${CLAUDE_PLUGIN_DATA} استفاده کن.
strict: false: چون این روی false تنظیم شده، پلاگین به plugin.json خودش نیاز ندارد. ورودیِ مارکت‌پلیس همه‌چیز را تعریف می‌کند. حالتِ strict را در پایین ببین.

حالتِ strict

فیلدِ strict کنترل می‌کند که آیا plugin.json مرجعِ تعاریفِ کامپوننت است (skillها، agentها، hookها، سرورهای MCP، سبک‌های خروجی).

مقدار	رفتار
`true` (پیش‌فرض)	`plugin.json` مرجع است. ورودیِ مارکت‌پلیس می‌تواند آن را با کامپوننت‌های اضافی تکمیل کند، و هر دو منبع merge می‌شوند.
`false`	ورودیِ مارکت‌پلیس کلِ تعریف است. اگر پلاگین `plugin.json`‌ای هم داشته باشد که کامپوننت اعلام کند، این یک تعارض است و پلاگین بار نمی‌شود.

کِی کدام حالت را استفاده کنیم:

strict: true: پلاگین plugin.json خودش را دارد و کامپوننت‌های خودش را مدیریت می‌کند. ورودیِ مارکت‌پلیس می‌تواند skillها یا hookهای اضافه روی آن بیفزاید. این پیش‌فرض است و برای بیشترِ پلاگین‌ها کار می‌کند.
strict: false: اپراتورِ مارکت‌پلیس کنترلِ کامل می‌خواهد. مخزنِ پلاگین فایل‌های خام را فراهم می‌کند، و ورودیِ مارکت‌پلیس تعریف می‌کند کدام‌یک از آن فایل‌ها به‌عنوانِ skill، agent، hook و غیره نمایان می‌شوند. وقتی مارکت‌پلیس کامپوننت‌های یک پلاگین را متفاوت از آنچه نویسنده‌ی پلاگین می‌خواست بازسازی یا گردآوری می‌کند مفید است.

میزبانی و توزیعِ مارکت‌پلیس‌ها

میزبانی روی GitHub (توصیه‌شده)

GitHub آسان‌ترین روشِ توزیع را فراهم می‌کند:

یک مخزن بساز: مخزنِ جدیدی برای مارکت‌پلیست راه بینداز
فایلِ مارکت‌پلیس را اضافه کن: .claude-plugin/marketplace.json را با تعاریفِ پلاگینت بساز
با تیم‌ها به اشتراک بگذار: کاربران مارکت‌پلیست را با /plugin marketplace add owner/repo اضافه می‌کنند

مزایا: کنترلِ نسخه‌ی داخلی، ردگیریِ ایشو و قابلیت‌های همکاریِ تیمی.

میزبانی روی دیگر سرویس‌های git

هر سرویسِ میزبانیِ git کار می‌کند، مثلِ GitLab، Bitbucket و سرورهای self-hosted. کاربران با آدرسِ کاملِ مخزن اضافه می‌کنند:

/plugin marketplace add https://gitlab.com/company/plugins.git

مخازنِ خصوصی

Claude Code از نصبِ پلاگین از مخازنِ خصوصی پشتیبانی می‌کند. برای نصب و به‌روزرسانیِ دستی، Claude Code از credential helperهای موجودِ git تو استفاده می‌کند، پس دسترسیِ HTTPS از طریقِ gh auth login، macOS Keychain یا git-credential-store همان‌طور که در ترمینالت کار می‌کند کار می‌کند. دسترسیِ SSH کار می‌کند تا وقتی هاست از قبل در فایلِ known_hosts تو باشد و کلید در ssh-agent بارگذاری شده باشد، چون Claude Code پرامپت‌های تعاملیِ SSH برای fingerprintِ هاست و passphraseِ کلید را سرکوب می‌کند.

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

ارائه‌دهنده	متغیرهای محیطی	یادداشت‌ها
GitHub	`GITHUB_TOKEN` یا `GH_TOKEN`	personal access token یا GitHub App token
GitLab	`GITLAB_TOKEN` یا `GL_TOKEN`	personal access token یا project token
Bitbucket	`BITBUCKET_TOKEN`	app password یا repository access token

توکن را در پیکربندیِ shellت تنظیم کن (برای مثال، .bashrc، .zshrc) یا هنگامِ اجرای Claude Code آن را بده:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

پیش از توزیع به‌صورتِ محلی تست کن

پیش از به اشتراک گذاشتن، مارکت‌پلیست را به‌صورتِ محلی تست کن:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

برای دامنه‌ی کاملِ دستورهای add (GitHub، Git URLها، مسیرهای محلی، URLهای ریموت)، افزودنِ مارکت‌پلیس‌ها را ببین.

مارکت‌پلیس‌ها را برای تیمت الزامی کن

می‌توانی مخزنت را طوری پیکربندی کنی که اعضای تیم وقتی پوشه‌ی پروژه را trust می‌کنند خودکار به نصبِ مارکت‌پلیست پرامپت شوند. مارکت‌پلیست را به .claude/settings.json اضافه کن:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

می‌توانی همچنین مشخص کنی کدام پلاگین‌ها باید به‌صورتِ پیش‌فرض فعال باشند:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

برای گزینه‌های کاملِ پیکربندی، تنظیماتِ پلاگین را ببین.

پلاگین‌ها را برای کانتینرها از پیش پر کن

برای imageهای کانتینر و محیط‌های CI، می‌توانی یک دایرکتوریِ پلاگین را در زمانِ build از پیش پر کنی تا Claude Code با مارکت‌پلیس‌ها و پلاگین‌های از پیش موجود شروع کند، بدونِ clone کردنِ چیزی در زمانِ اجرا. متغیرِ محیطیِ CLAUDE_CODE_PLUGIN_SEED_DIR را تنظیم کن تا به این دایرکتوری اشاره کند.

برای لایه‌لایه‌کردنِ چند دایرکتوریِ seed، مسیرها را با : روی Unix یا ; روی Windows جدا کن. Claude Code هر دایرکتوری را به ترتیب جست‌وجو می‌کند، و اولین seed که cacheِ یک مارکت‌پلیس یا پلاگینِ مشخص را داشته باشد برنده می‌شود.

دایرکتوریِ seed ساختارِ ~/.claude/plugins را آینه می‌کند:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

برای ساختِ یک دایرکتوریِ seed، Claude Code را یک‌بار هنگامِ buildِ image اجرا کن، پلاگین‌هایی را که نیاز داری نصب کن، سپس دایرکتوریِ ~/.claude/plugins حاصل را به imageت کپی کن و CLAUDE_CODE_PLUGIN_SEED_DIR را به آن اشاره بده.

برای رد شدن از گامِ کپی، CLAUDE_CODE_PLUGIN_CACHE_DIR را در زمانِ build به مسیرِ seedِ هدفت تنظیم کن تا پلاگین‌ها مستقیماً همان‌جا نصب شوند:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

سپس CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed را در محیطِ اجرای کانتینرت تنظیم کن تا Claude Code هنگامِ راه‌اندازی از seed بخواند.

هنگامِ راه‌اندازی، Claude Code مارکت‌پلیس‌های پیداشده در known_marketplaces.json در seed را در پیکربندیِ اصلی ثبت می‌کند، و cacheهای پلاگینِ پیداشده زیرِ cache/ را بدونِ clone دوباره همان‌جا استفاده می‌کند. این هم در حالتِ تعاملی و هم در حالتِ غیرتعاملی با پرچمِ -p کار می‌کند.

جزئیاتِ رفتار:

فقط-خواندنی: دایرکتوریِ seed هرگز نوشته نمی‌شود. به‌روزرسانیِ خودکار برای مارکت‌پلیس‌های seed غیرفعال است، چون git pull روی یک فایل‌سیستمِ فقط-خواندنی شکست می‌خورد.
ورودی‌های seed تقدم دارند: مارکت‌پلیس‌های اعلام‌شده در seed هر ورودیِ مطابق در پیکربندیِ کاربر را در هر راه‌اندازی بازنویسی می‌کنند. برای انصراف از یک پلاگینِ seed، به‌جای حذفِ مارکت‌پلیس از /plugin disable استفاده کن.
resolveِ مسیر: Claude Code محتوای مارکت‌پلیس را با probe کردنِ $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ در زمانِ اجرا پیدا می‌کند، نه با اعتماد به مسیرهای ذخیره‌شده درونِ JSON در seed. این یعنی seed حتی وقتی در مسیری متفاوت از جای ساختش mount شود درست کار می‌کند.
تغییر مسدود است: اجرای /plugin marketplace remove یا /plugin marketplace update روی یک مارکت‌پلیسِ مدیریت‌شده با seed با راهنمایی به اینکه از مدیرت بخواهی imageِ seed را به‌روز کند شکست می‌خورد.
با تنظیمات ترکیب می‌شود: اگر extraKnownMarketplaces یا enabledPlugins مارکت‌پلیسی را اعلام کنند که از قبل در seed وجود دارد، Claude Code به‌جای clone از کپیِ seed استفاده می‌کند.

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

برای سازمان‌هایی که کنترلِ سخت‌گیرانه روی منابعِ پلاگین می‌خواهند، مدیران می‌توانند با تنظیمِ strictKnownMarketplaces در managed settings محدود کنند که کاربران مجاز به افزودنِ کدام مارکت‌پلیس‌های پلاگین هستند.

وقتی strictKnownMarketplaces در managed settings پیکربندی شود، رفتارِ محدودیت به مقدار بستگی دارد:

مقدار	رفتار
تعریف‌نشده (پیش‌فرض)	بدونِ محدودیت. کاربران می‌توانند هر مارکت‌پلیسی اضافه کنند
آرایه‌ی خالی `[]`	قفلِ کامل. کاربران نمی‌توانند هیچ مارکت‌پلیسِ جدیدی اضافه کنند
فهرستی از منابع	کاربران فقط می‌توانند مارکت‌پلیس‌هایی اضافه کنند که دقیقاً با allowlist مطابقت دارند

پیکربندی‌های رایج

غیرفعال‌کردنِ همه‌ی افزودن‌های مارکت‌پلیس:

{
  "strictKnownMarketplaces": []
}

مجازکردنِ فقط مارکت‌پلیس‌های مشخص:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

مجازکردنِ همه‌ی مارکت‌پلیس‌ها از یک سرورِ git داخلی با تطبیقِ الگوی regex روی هاست. این رویکردِ توصیه‌شده برای GitHub Enterprise Server یا نمونه‌های self-hosted GitLab است:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

مجازکردنِ مارکت‌پلیس‌های فایل‌سیستم‌محور از یک دایرکتوریِ مشخص با تطبیقِ الگوی regex روی مسیر:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

از ".*" به‌عنوانِ pathPattern استفاده کن تا هر مسیرِ فایل‌سیستم مجاز شود در حالی که هنوز منابعِ شبکه را با hostPattern کنترل می‌کنی.

محدودیت‌ها چطور کار می‌کنند

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

allowlist برای بیشترِ نوع‌های منبع از تطبیقِ دقیق استفاده می‌کند. برای اینکه مارکت‌پلیسی مجاز باشد، همه‌ی فیلدهای مشخص‌شده باید دقیقاً مطابقت کنند:

برای منابعِ GitHub: repo الزامی است، و ref یا path هم باید مطابقت کنند اگر در allowlist مشخص شده باشند
برای منابعِ URL: URLِ کامل باید دقیقاً مطابقت کند
برای منابعِ hostPattern: هاستِ مارکت‌پلیس با الگوی regex تطبیق می‌شود
برای منابعِ pathPattern: مسیرِ فایل‌سیستمِ مارکت‌پلیس با الگوی regex تطبیق می‌شود

تطبیقِ دقیق URLها را نرمال نمی‌کند: یک اسلشِ پایانی، پسوندِ .git یا شکلِ ssh:// در برابرِ https:// مقادیرِ متفاوتی تلقی می‌شوند. اگر مارکت‌پلیسِ سازمانت با بیش از یک شکلِ URL قابلِ clone است، به‌جای یک URLِ ادبی یک ورودیِ hostPattern را ترجیح بده تا همه‌ی شکل‌ها مطابقت کنند.

چون strictKnownMarketplaces در managed settings تنظیم می‌شود، کاربرانِ تک و پیکربندی‌های پروژه نمی‌توانند این محدودیت‌ها را override کنند.

برای جزئیاتِ کاملِ پیکربندی شاملِ همه‌ی نوع‌های منبعِ پشتیبانی‌شده و مقایسه با extraKnownMarketplaces، مرجعِ strictKnownMarketplaces را ببین.

resolveِ نسخه و کانال‌های انتشار

نسخه‌های پلاگین مسیرهای cache و تشخیصِ به‌روزرسانی را تعیین می‌کنند: اگر نسخه‌ی resolve‌شده با آنچه کاربر از قبل دارد مطابقت کند، /plugin update و به‌روزرسانیِ خودکار پلاگین را رد می‌کنند.

Claude Code نسخه‌ی یک پلاگین را از اولینِ این‌ها که تنظیم شده باشد resolve می‌کند:

version در plugin.json پلاگین
version در ورودیِ مارکت‌پلیسِ پلاگین
SHAی کامیتِ git منبعِ پلاگین

برای نوع‌های منبعِ git-محورِ github، url، git-subdir و مسیرهای نسبی درونِ یک مارکت‌پلیسِ git-میزبانی‌شده، می‌توانی version را به‌کلی حذف کنی و هر کامیتِ جدید یک نسخه‌ی جدید تلقی می‌شود. این ساده‌ترین راه‌اندازی برای پلاگین‌های داخلی یا در حالِ توسعه‌ی فعال است.

تنظیمِ version پلاگین را pin می‌کند. اگر plugin.json بگوید "version": "1.0.0"، push کردنِ کامیت‌های جدید بدونِ تغییرِ آن رشته برای کاربرانِ موجود هیچ کاری نمی‌کند، چون Claude Code همان نسخه را می‌بیند و کپیِ cache را نگه می‌دارد. این فیلد را در هر انتشار بالا ببر، یا حذفش کن تا از SHAی کامیت استفاده شود.

از تنظیمِ version هم در plugin.json و هم در ورودیِ مارکت‌پلیس بپرهیز. مقدارِ plugin.json همیشه بی‌سروصدا برنده می‌شود، پس یک نسخه‌ی کهنه در مانیفست می‌تواند نسخه‌ای را که در marketplace.json تنظیم کرده‌ای بپوشاند.

کانال‌های انتشار را راه بینداز

برای پشتیبانی از کانال‌های انتشارِ «stable» و «latest» برای پلاگین‌هایت، می‌توانی دو مارکت‌پلیس راه بیندازی که به ref یا SHAهای متفاوتِ همان مخزن اشاره کنند. سپس می‌توانی این دو مارکت‌پلیس را از طریقِ managed settings به گروه‌های کاربریِ متفاوت اختصاص دهی.

مثال

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

کانال‌ها را به گروه‌های کاربری اختصاص بده

هر مارکت‌پلیس را از طریقِ managed settings به گروهِ کاربریِ مناسب اختصاص بده. برای مثال، گروهِ stable این را دریافت می‌کند:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

گروهِ early-access به‌جایش latest-tools را دریافت می‌کند:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

نسخه‌های وابستگی را pin کن

یک پلاگین می‌تواند وابستگی‌هایش را به یک بازه‌ی semver قید بزند تا به‌روزرسانی‌های یک وابستگی پلاگینِ وابسته را نشکنند. برای قراردادِ git-tag به‌صورتِ {plugin-name}--v{version}، نحوِ بازه، و اینکه چند قید روی همان وابستگی چطور ترکیب می‌شوند، قید زدنِ نسخه‌های وابستگیِ پلاگین را ببین.

اعتبارسنجی و تست

پیش از به اشتراک گذاشتن، مارکت‌پلیست را تست کن.

نحوِ JSON مارکت‌پلیست را اعتبارسنجی کن:

claude plugin validate .

یا از درونِ Claude Code:

/plugin validate .

مارکت‌پلیس را برای تست اضافه کن:

/plugin marketplace add ./path/to/marketplace

یک پلاگینِ تست نصب کن تا مطمئن شوی همه‌چیز کار می‌کند:

/plugin install test-plugin@marketplace-name

برای ورک‌فلوهای کاملِ تستِ پلاگین، پلاگین‌هایت را به‌صورتِ محلی تست کن را ببین. برای عیب‌یابیِ فنی، مرجعِ پلاگین‌ها را ببین.

مدیریتِ مارکت‌پلیس‌ها از CLI

Claude Code زیردستورهای غیرتعاملیِ claude plugin marketplace را برای اسکریپت‌نویسی و خودکارسازی فراهم می‌کند. این‌ها معادلِ دستورهای /plugin marketplace در دسترس درونِ یک نشستِ تعاملی هستند.

Plugin marketplace add

یک مارکت‌پلیس را از یک مخزنِ GitHub، git URL، URLِ ریموت یا مسیرِ محلی اضافه کن.

claude plugin marketplace add <source> [options]

آرگومان‌ها:

<source>: شورتِ‌هندِ owner/repo در GitHub، git URL، URLِ ریموت به یک فایلِ marketplace.json، یا مسیرِ دایرکتوریِ محلی. برای pin کردن به یک شاخه یا تگ، @ref را به شورتِ‌هندِ GitHub یا #ref را به یک git URL بچسبان

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`--scope <scope>`	جای اعلامِ مارکت‌پلیس: `user`، `project` یا `local`. scopeهای نصبِ پلاگین را ببین	`user`
`--sparse <paths...>`	checkout را با git sparse-checkout به دایرکتوری‌های مشخص محدود کن. برای monorepoها مفید است

افزودنِ یک مارکت‌پلیس از GitHub با شورتِ‌هندِ owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

pin کردن به یک شاخه یا تگِ مشخص با @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

افزودن از یک git URL روی هاستِ غیر-GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

افزودن از یک URLِ ریموت که فایلِ marketplace.json را مستقیماً سرو می‌کند:

claude plugin marketplace add https://example.com/marketplace.json

افزودن از یک دایرکتوریِ محلی برای تست:

claude plugin marketplace add ./my-marketplace

مارکت‌پلیس را در scopeِ project اعلام کن تا از طریقِ .claude/settings.json با تیمت به اشتراک گذاشته شود:

claude plugin marketplace add acme-corp/claude-plugins --scope project

برای یک monorepo، checkout را به دایرکتوری‌هایی که محتوای پلاگین دارند محدود کن:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

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

claude plugin marketplace list [options]

گزینه‌ها:

گزینه	توضیح
`--json`	خروجی به‌صورتِ JSON

با --json، هر ورودی شاملِ name، source و فیلدهای مخصوصِ منبع است: repo برای منابعِ GitHub، url برای منابعِ git و URL، و path برای منابعِ محلی. منابعِ GitHub و git همچنین یک فیلدِ ref دارند وقتی مارکت‌پلیس با یک شاخه یا تگِ پین‌شده اضافه شده باشد.

Plugin marketplace remove

یک مارکت‌پلیسِ پیکربندی‌شده را حذف کن. اسمِ مستعارِ rm هم پذیرفته می‌شود.

claude plugin marketplace remove <name> [options]

آرگومان‌ها:

<name>: نامِ مارکت‌پلیس برای حذف، همان‌طور که claude plugin marketplace list نشان می‌دهد. این name از marketplace.json است، نه منبعی که به add پاس دادی

گزینه‌ها:

گزینه	توضیح	پیش‌فرض
`--scope <scope>`	حذف را به یک scopeِ تنظیماتِ واحد محدود کن: `user`، `project` یا `local`. scopeهای نصبِ پلاگین را ببین. وقتی حذف شود، اعلام از هر scopeِ قابلِ‌ویرایش حذف می‌شود. وقتی داده شود، فقط اعلامِ آن scope حذف می‌شود؛ stateِ مشترک، cache و داده‌ی پلاگینِ نصب‌شده حفظ می‌شوند اگر مارکت‌پلیس هنوز در scopeِ دیگری اعلام شده باشد	(همه‌ی scopeها)

Plugin marketplace update

مارکت‌پلیس‌ها را از منابعشان refresh کن تا پلاگین‌های جدید و تغییرات نسخه را دریافت کنی.

claude plugin marketplace update [name]

آرگومان‌ها:

[name]: نامِ مارکت‌پلیس برای به‌روزرسانی، همان‌طور که claude plugin marketplace list نشان می‌دهد. اگر حذف شود همه‌ی مارکت‌پلیس‌ها را به‌روز می‌کند

هم remove و هم update وقتی روی یک مارکت‌پلیسِ مدیریت‌شده با seed اجرا شوند شکست می‌خورند، که فقط-خواندنی است. هنگامِ به‌روزرسانیِ همه‌ی مارکت‌پلیس‌ها، ورودی‌های مدیریت‌شده با seed رد می‌شوند و بقیه‌ی مارکت‌پلیس‌ها همچنان به‌روز می‌شوند. برای تغییرِ پلاگین‌های فراهم‌شده با seed، از مدیرت بخواه imageِ seed را به‌روز کند. پلاگین‌ها را برای کانتینرها از پیش پر کن را ببین.

عیب‌یابی

مارکت‌پلیس بار نمی‌شود

نشانه‌ها: نمی‌توانی مارکت‌پلیس را اضافه کنی یا پلاگین‌هایش را ببینی

راه‌حل‌ها:

بررسی کن که URLِ مارکت‌پلیس قابلِ دسترس است
بررسی کن که .claude-plugin/marketplace.json در مسیرِ مشخص‌شده وجود دارد
مطمئن شو که نحوِ JSON معتبر است با claude plugin validate یا /plugin validate. برای بررسیِ frontmatterِ skill، agent و command، دستور را روی هر دایرکتوریِ پلاگین اجرا کن
برای مخازنِ خصوصی، تأیید کن که مجوزهای دسترسی داری

خطاهای اعتبارسنجیِ مارکت‌پلیس

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

برای اعتبارسنجیِ plugin.json یک پلاگینِ جداگانه و فایل‌های skill، agent، command و hook آن، دستور را روی خودِ دایرکتوریِ پلاگین اجرا کن، برای مثال claude plugin validate ./plugins/my-plugin. خطاهای رایج:

خطا	علت	راه‌حل
`File not found: .claude-plugin/marketplace.json`	مانیفستِ گمشده	`.claude-plugin/marketplace.json` را با فیلدهای الزامی بساز
`Invalid JSON syntax: Unexpected token...`	خطای نحوِ JSON در marketplace.json	به دنبالِ کاماهای گمشده، کاماهای اضافی یا رشته‌های بدونِ نقل‌قول بگرد
`Duplicate plugin name "x" found in marketplace`	دو پلاگین همان نام را دارند	به هر پلاگین یک مقدارِ `name` یکتا بده
`plugins[0].source: Path contains ".."`	مسیرِ منبع شاملِ `..` است	از مسیرهای نسبت به ریشه‌ی مارکت‌پلیس بدونِ `..` استفاده کن. مسیرهای نسبی را ببین
`YAML frontmatter failed to parse: ...`	YAMLِ نامعتبر در یک فایلِ skill، agent یا command	نحوِ YAML را در بلاکِ frontmatter اصلاح کن. در زمانِ اجرا این فایل بدونِ متادیتا بار می‌شود. فقط هنگامِ اعتبارسنجیِ یک دایرکتوریِ پلاگین گزارش می‌شود
`Invalid JSON syntax: ...` (hooks.json)	`hooks/hooks.json` بدشکل	نحوِ JSON را اصلاح کن. یک `hooks/hooks.json` بدشکل مانعِ بارگذاریِ کلِ پلاگین می‌شود. فقط هنگامِ اعتبارسنجیِ یک دایرکتوریِ پلاگین گزارش می‌شود

هشدارها (غیرمسدودکننده):

Marketplace has no plugins defined: دستِ‌کم یک پلاگین به آرایه‌ی plugins اضافه کن
No marketplace description provided: یک description در سطحِ بالا اضافه کن تا کاربران مارکت‌پلیست را بفهمند
Plugin name "x" is not kebab-case: نامِ پلاگین حروفِ بزرگ، فاصله یا کاراکترهای خاص دارد. به فقط حروفِ کوچک، ارقام و خط‌فاصله تغییرِ نام بده (برای مثال، my-plugin). Claude Code شکل‌های دیگر را می‌پذیرد، ولی همگام‌سازیِ مارکت‌پلیسِ Claude.ai آن‌ها را رد می‌کند.

شکستِ نصبِ پلاگین

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

راه‌حل‌ها:

بررسی کن که URLهای منبعِ پلاگین قابلِ دسترس‌اند
بررسی کن که دایرکتوری‌های پلاگین فایل‌های لازم را دارند
برای منابعِ GitHub، مطمئن شو مخازن عمومی‌اند یا دسترسی داری
منابعِ پلاگین را به‌صورتِ دستی با clone/download کردن تست کن
اگر منبع هم ref و هم sha را pin کند، یک شاخه یا تگِ حذف‌شده‌ی upstream مانعِ نصب نمی‌شود. اگر نصب همچنان شکست خورد، تأیید کن که کامیتِ pin‌شده هنوز در مخزن وجود دارد

احرازِ هویتِ مخزنِ خصوصی شکست می‌خورد

نشانه‌ها: خطاهای احرازِ هویت هنگامِ نصبِ پلاگین از مخازنِ خصوصی

راه‌حل‌ها:

برای نصب و به‌روزرسانیِ دستی:

تأیید کن که با ارائه‌دهنده‌ی gitت احرازِ هویت شده‌ای (برای مثال، برای GitHub gh auth status را اجرا کن)
بررسی کن که credential helperت درست پیکربندی شده: git config --global credential.helper
سعی کن مخزن را به‌صورتِ دستی clone کنی تا مطمئن شوی اعتبارنامه‌هایت کار می‌کنند

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

توکنِ مناسب را در محیطت تنظیم کن: echo $GITHUB_TOKEN
بررسی کن که توکن مجوزهای لازم را دارد (دسترسیِ خواندن به مخزن)
برای GitHub، مطمئن شو توکن scopeِ repo را برای مخازنِ خصوصی دارد
برای GitLab، مطمئن شو توکن دستِ‌کم scopeِ read_repository را دارد
تأیید کن که توکن منقضی نشده

به‌روزرسانیِ مارکت‌پلیس در محیط‌های آفلاین شکست می‌خورد

نشانه‌ها: git pull مارکت‌پلیس شکست می‌خورد و Claude Code cacheِ موجود را پاک می‌کند، که باعث می‌شود پلاگین‌ها در دسترس نباشند.

علت: به‌صورتِ پیش‌فرض، وقتی یک git pull شکست می‌خورد، Claude Code cloneِ کهنه را حذف و تلاش به clone دوباره می‌کند. در محیط‌های آفلاین یا airgapped، clone دوباره به همان شکل شکست می‌خورد و دایرکتوریِ مارکت‌پلیس را خالی می‌گذارد.

راه‌حل: CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 را تنظیم کن تا وقتی pull شکست خورد cacheِ موجود نگه داشته شود به‌جای پاک‌شدن:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

با این متغیرِ تنظیم‌شده، Claude Code cloneِ کهنه‌ی مارکت‌پلیس را هنگامِ شکستِ git pull نگه می‌دارد و به استفاده از آخرین حالتِ خوبِ شناخته‌شده ادامه می‌دهد. برای استقرارهای کاملاً آفلاین که مخزن هرگز قابلِ دسترس نخواهد بود، به‌جایش از CLAUDE_CODE_PLUGIN_SEED_DIR استفاده کن تا دایرکتوریِ پلاگین را در زمانِ build از پیش پر کنی.

عملیاتِ git تایم‌اوت می‌کند

نشانه‌ها: نصبِ پلاگین یا به‌روزرسانیِ مارکت‌پلیس با خطای تایم‌اوت مثلِ “Git clone timed out after 120s” یا “Git pull timed out after 120s” شکست می‌خورد.

علت: Claude Code از یک تایم‌اوتِ ۱۲۰ ثانیه‌ای برای همه‌ی عملیاتِ git استفاده می‌کند، شاملِ clone کردنِ مخازنِ پلاگین و pull کردنِ به‌روزرسانی‌های مارکت‌پلیس. مخازنِ بزرگ یا اتصال‌های شبکه‌ی کند ممکن است از این حد بگذرند.

راه‌حل: تایم‌اوت را با متغیرِ محیطیِ CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS افزایش بده. مقدار به میلی‌ثانیه است:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

پلاگین‌های دارای مسیرِ نسبی در مارکت‌پلیس‌های URL-محور شکست می‌خورند

نشانه‌ها: یک مارکت‌پلیس را از طریقِ URL اضافه کردی (مثلِ https://example.com/marketplace.json)، ولی پلاگین‌هایی با منبعِ مسیرِ نسبی مثلِ "./plugins/my-plugin" با خطای “path not found” در نصب شکست می‌خورند.

علت: مارکت‌پلیس‌های URL-محور فقط خودِ فایلِ marketplace.json را دانلود می‌کنند. فایل‌های پلاگین را از سرور دانلود نمی‌کنند. مسیرهای نسبی در ورودیِ مارکت‌پلیس به فایل‌هایی روی سرورِ ریموت ارجاع می‌دهند که دانلود نشدند.

راه‌حل‌ها:

از منابعِ خارجی استفاده کن: ورودی‌های پلاگین را به‌جای مسیرهای نسبی به منابعِ GitHub، npm یا git URL تغییر بده:
```
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
```
از یک مارکت‌پلیسِ Git-محور استفاده کن: مارکت‌پلیست را در یک مخزنِ Git میزبانی کن و آن را با git URL اضافه کن. مارکت‌پلیس‌های Git-محور کلِ مخزن را clone می‌کنند و مسیرهای نسبی درست کار می‌کنند.

فایل‌ها بعد از نصب پیدا نمی‌شوند

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

علت: پلاگین‌ها به یک دایرکتوریِ cache کپی می‌شوند به‌جای استفاده در محل. مسیرهایی که به فایل‌های بیرونِ دایرکتوریِ پلاگین ارجاع می‌دهند (مثلِ ../shared-utils) کار نمی‌کنند چون آن فایل‌ها کپی نمی‌شوند.

راه‌حل‌ها: برای راه‌حل‌های دور زدن شاملِ symlinkها و بازساختاردهیِ دایرکتوری، Cacheِ پلاگین و resolveِ فایل را ببین.

برای ابزارهای دیباگِ بیشتر و مشکلاتِ رایج، ابزارهای دیباگ و توسعه را ببین.

همچنین ببین

کشف و نصبِ پلاگین‌های آماده - نصبِ پلاگین‌ها از مارکت‌پلیس‌های موجود
پلاگین‌ها - ساختِ پلاگین‌های خودت
مرجعِ پلاگین‌ها - مشخصاتِ فنیِ کامل و اسکیماها
تنظیماتِ پلاگین - گزینه‌های پیکربندیِ پلاگین
مرجعِ strictKnownMarketplaces - محدودیت‌های مارکت‌پلیسِ مدیریت‌شده