پلاگین Claude Code چیست و چه هزینه‌ای دارد؟

پلاگین Claude Code چیست

یک پلاگین Claude Code شامل یک دایرکتوری از مؤلفه‌ها است که Claude Code آن‌ها را به عنوان یک واحد یکپارچه بارگذاری و مدیریت می‌کند. این مؤلفه‌ها شامل مهارت‌ها (skills)، عامل‌ها (agents)، هوک‌ها (hooks)، سرورهای MCP، سرورهای LSP و مانیتورهای پس‌زمینه هستند. نصب یک پلاگین، تمامی بخش‌های آن را به‌طور هم‌زمان و تحت یک نام واحد اضافه می‌کند و غیرفعال‌کردن آن نیز باعث حذف یکجای آن‌ها می‌شود.

یک پلاگین هیچ قابلیتی که عامل (agent) از قبل نداشته باشد به آن اضافه نمی‌کند. هر بخشی که درون یک پلاگین قرار دارد، چیزی است که می‌توانید به‌صورت دستی در دایرکتوری .claude/ بنویسید. پلاگین در واقع لایه بسته‌بندی است: روشی برای نسخه‌گذاری این بخش‌ها، تحویل آن‌ها به 15 نفر و به‌روزرسانی بعدی آن‌ها بدون نیاز به اینکه از همه بخواهید فایل‌ها را کپی کنند. کل ایده همین است و بیشتر سردرگمی‌ها درباره پلاگین‌ها ناشی از این تصور است که آن‌ها نوع جدیدی از قابلیت‌ها هستند.

فایل manifest اختیاری در مسیر .claude-plugin/plugin.json، نام پلاگین را تعیین می‌کند و آن نام به یک فضای نام (namespace) تبدیل می‌شود. یک مهارت در پلاگینی به نام commit-commands با دستور /commit-commands:commit فراخوانی می‌شود، بنابراین دو پلاگین می‌توانند هر کدام مهارتی به نام commit داشته باشند بدون اینکه یکی دیگری را بپوشاند. عامل‌های پلاگین نیز به همین ترتیب در لیست @-mention با نام plugin-name:agent-name محدود و شناسایی می‌شوند.

پلاگین، مهارت، سرور MCP یا فایل قوانین

این چهار واژه گاهی به‌گونه‌ای استفاده می‌شوند که گویی با یکدیگر در رقابت هستند. اما این‌طور نیست و ارزش دارد که مرز میان آن‌ها را یک‌بار مشخص کنیم.

• مهارت (Skill) یک واحد دستورالعمل است که Claude هنگام نیاز به انجام وظیفه، آن را بارگذاری می‌کند. به اینکه مهارت عامل (Agent Skill) واقعاً چیست مراجعه کنید.
• سرور MCP یک پردازش مجزا است که ابزارها را از طریق یک پروتکل در اختیار عامل قرار می‌دهد؛ این معمولاً یک سرویس شبکه است که خودتان آن را اجرا می‌کنید.
• فایل قوانین (Rules file) مانند CLAUDE.md، محتوای متنی پروژه است که در شروع نشست (session) خوانده می‌شود و بر همه چیز اعمال می‌گردد.
• پلاگین (Plugin) یک کانتینر است که می‌تواند مهارت‌ها، عامل‌ها، هوک‌ها و تعاریف سرور MCP را به‌همراه شماره نسخه و کانال توزیع در خود جای دهد.

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

محل قرارگیری افزونه‌ها و محتویات آن‌ها

افزونه‌ای که از یک بازارچه (marketplace) نصب می‌شود، به‌جای اجرا از محلی که کلون شده است، در یک کش محلی در مسیر ~/.claude/plugins/cache کپی می‌شود. هر نسخهٔ نصب‌شده، دایرکتوری اختصاصی خود را دارد. هنگامی که افزونه‌ای را به‌روزرسانی یا حذف می‌کنید، دایرکتوری نسخهٔ قدیمی به‌عنوان یتیم (orphaned) علامت‌گذاری شده و حدود دو هفته بعد حذف می‌شود؛ بنابراین، نشست (session) کاری که قبلاً نسخهٔ قدیمی را بارگذاری کرده است، به‌جای شکست در حین انجام وظیفه، به کار خود ادامه می‌دهد.

از آنجا که مسیر فایل‌ها با هر به‌روزرسانی تغییر می‌کند، یک افزونه هرگز نباید مکان خود را به‌صورت hardcode در کد قرار دهد. هوک‌ها و پیکربندی‌های MCP در داخل یک افزونه از ${CLAUDE_PLUGIN_ROOT} استفاده می‌کنند که به دایرکتوری نصب فعلی اشاره دارد. داده‌های حالتی (state) که باید پس از به‌روزرسانی باقی بمانند، باید در ${CLAUDE_PLUGIN_DATA} قرار گیرند که به یک دایرکتوری پایدار در زیرشاخه ~/.claude/plugins/data/ اشاره می‌کند.

تنها دایرکتوری خودِ افزونه در کش کپی می‌شود که این موضوع پیامدی دارد که کاربران اغلب دیر متوجه آن می‌شوند. مسیری که به خارج از ریشهٔ افزونه اشاره دارد، مانند ../shared-utils، در زمان توسعه با مسیر محلی به‌درستی کار می‌کند اما پس از نصب از کار می‌افتد، زیرا آن فایل‌ها هرگز کپی نشده‌اند.

ساختار فایل‌ها به این صورت است.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

فقط plugin.json در داخل .claude-plugin/ قرار می‌گیرد. سایر موارد در ریشهٔ افزونه جای دارند. قرار دادن skills/ یا hooks/ در داخل .claude-plugin/ رایج‌ترین دلیل برای این است که یک افزونه به‌درستی نصب می‌شود اما هیچ کاری انجام نمی‌دهد: Claude Code این دایرکتوری‌ها را در ریشه جستجو می‌کند، چیزی نمی‌یابد و افزونه را بدون هیچ مؤلفه‌ای بارگذاری می‌کند.

فایل مانیفست به‌خودی‌خود کوچک است.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

نحوه نصب افزونه Claude Code

فرایند نصب شامل دو مرحله است که مرحله اول چیزی را نصب نمی‌کند. شما ابتدا یک marketplace (فهرستی از افزونه‌ها) را اضافه می‌کنید و سپس افزونه‌های مورد نظر خود را از آن نصب می‌کنید. marketplace رسمی Anthropic با نام claude-plugins-official، اولین باری که Claude Code را به‌صورت تعاملی اجرا می‌کنید، برای شما ثبت می‌شود. سایر موارد را باید خودتان اضافه کنید.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

توجه داشته باشید که مخزن (repository) با نام anthropics/claude-code شناخته می‌شود، در حالی که نام marketplace برابر با claude-code-plugins است. این نام از فایل کاتالوگ موجود در مخزن گرفته می‌شود، نه از مسیر مخزن؛ بنابراین پیش از تایپ دستور نصب، نام marketplace را از تب Marketplaces در /plugin بخوانید.

پس از نصب، خط خلاصه را مطالعه کنید. عبارت Plugin is now active. به این معناست که مؤلفه‌ها در این نشست (session) بارگذاری شده‌اند. عبارت Run /reload-plugins to activate. یعنی مؤلفه‌ها بارگذاری نشده‌اند و باید آن دستور را اجرا کنید. اگر /reload-plugins هشدار داد که این کار باعث بازخوانی گفتگو می‌شود، آن را با دستور /reload-plugins --force مجدداً اجرا کنید. سپس تأیید کنید که افزونه واقعاً اضافه شده است: /plugin آن را در تب Installed نمایش می‌دهد، /help مهارت‌های آن را در تب Custom commands فهرست می‌کند و هر موردی که در بارگذاری شکست خورده باشد، در تب Errors به همراه دلیل آن ظاهر می‌شود.

هنگام نصب، از شما یک scope (محدوده) پرسیده می‌شود که تعیین می‌کند چه کسی به افزونه دسترسی داشته باشد. محدوده User برای شما و در تمام پروژه‌هاست. محدوده Project افزونه را در فایل .claude/settings.json مخزن و در بخش enabledPlugins می‌نویسد، بنابراین به هر کسی که مخزن را clone کند، پیشنهاد می‌شود. محدوده Local فقط برای شما و صرفاً در همین مخزن است.

برای اسکریپت‌ها، Dockerfile یا هر نشستی که پنل تعاملی در دسترس نیست، از فرم shell استفاده کنید. این دستور به‌صورت پیش‌فرض در محدوده User نصب می‌شود، مگر اینکه پرچم --scope را ارسال کنید.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

دستور claude plugin install خارج از یک نشست اجرا می‌شود، بنابراین نشستی که از قبل باز است، افزونه جدید را نمی‌بیند مگر اینکه /reload-plugins را اجرا کنید یا یک نشست جدید شروع کنید.

مدیریت افزونه‌های موجود در هر دو حالت از یک الگو پیروی می‌کند. دستور /plugin list موارد نصب‌شده را چاپ می‌کند و ورودی‌های --enabled یا --disabled را می‌پذیرد. دستور /plugin disable name@marketplace افزونه را بدون حذف کردن غیرفعال می‌کند، /plugin enable آن را دوباره فعال می‌کند و /plugin uninstall آن را حذف می‌نماید. فرم‌های slash-command پنل افزونه را برای اعمال تغییرات باز می‌کنند، به همین دلیل است که برای استفاده در اسکریپت‌ها باید از معادل‌های shell یعنی claude plugin ... استفاده کنید.

برای ارائه یک marketplace به کل تیم، آن را در فایل .claude/settings.json پروژه قرار دهید. اعضای تیم پس از اعتماد به پوشه مخزن، برای نصب آن ترغیب می‌شوند.

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

هنگامی که در حال ساخت افزونه اختصاصی خود هستید، marketplace را کاملاً نادیده بگیرید. دستور claude --plugin-dir ./my-plugin یک دایرکتوری را برای همان نشست بارگذاری می‌کند، /reload-plugins ویرایش‌های شما را بدون نیاز به راه‌اندازی مجدد اعمال می‌کند و claude plugin validate ./my-plugin پیش از آنکه دیگران آن را ببینند، manifest، مهارت‌ها، frontmatter عامل و hooks/hooks.json را بررسی می‌کند.

هزینه افزونه‌های Claude Code چقدر است؟

مکانیسم استفاده از آن‌ها رایگان است. تا اوت 2026، هیچ هزینه‌ای برای افزودن یک marketplace، نصب افزونه یا فعال نگه‌داشتن آن دریافت نمی‌شود. marketplaceهای رسمی و اجتماعی، مخازن عمومی git هستند و هر افزونه صرفاً مجموعه‌ای از فایل‌های متنی است.

هزینه واقعی یک افزونه بر اساس توکن محاسبه می‌شود؛ همان معیاری که در اشتراک یا صورت‌حساب API شما لحاظ می‌گردد. این هزینه از سه طریق متفاوت اعمال می‌شود که رفتار هرکدام با دیگری فرق دارد:

هزینه کانتکست ثابت (Standing context cost). آنچه یک افزونه به کانتکست شما اضافه می‌کند، در هر مرحله از نشست (session) مجدداً خوانده می‌شود. پیش از نصب، نمای جزئیات /plugin یک تخمین Context cost بر اساس تعداد توکن‌ها به همراه بخش Will install که شامل دستورات، مهارت‌ها، عامل‌ها (agents)، هوک‌ها و سرورهای MCP و LSP است را نمایش می‌دهد. هر دو را مطالعه کنید. افزونه‌هایی که از marketplaceهای محلی یا سفارشی می‌آیند ممکن است این داده‌ها را ارائه ندهند که در این صورت باید خودتان تخمین بزنید. افزونه‌ای که یک سرور MCP را بسته‌بندی می‌کند معمولاً سنگین‌ترین نوع است، زیرا تعاریف ابزارها حجم زیادی دارند؛ هرچند در مدل‌هایی که از جستجوی ابزار MCP پشتیبانی می‌کنند، این تعاریف تا زمانی که به ابزار نیاز نباشد، بارگذاری نمی‌شوند.

هزینه فراخوانی (Invocation cost). اجرای مهارت یک افزونه، دستورالعمل‌های آن را به گفتگو اضافه می‌کند، بنابراین شما فقط در زمان استفاده، هزینه بدنه آن مهارت را می‌پردازید. عامل‌ها (agents) متفاوت هستند. یک زیر-عامل (subagent) گفتگوی مستقل خود را با پرامپت سیستمی و کش اختصاصی‌اش اجرا می‌کند و کار را بدون هیچ cache hit آغاز می‌کند؛ بنابراین افزونه‌ای که گردش‌کار آن باعث ایجاد عامل‌های جدید می‌شود، هزینه بسیار بیشتری نسبت به تخمین کانتکست اولیه دارد.

هزینه کش (Cache cost). فعال یا غیرفعال کردن یک افزونه در میانه نشست می‌تواند باعث شود درخواست بعدی، کل گفتگوی شما را دوباره پردازش کند. مهارت‌ها، دستورات، عامل‌ها، هوک‌ها، سرورهای LSP، مانیتورها و تم‌ها هرگز چنین کاری نمی‌کنند؛ آنچه آن‌ها اضافه می‌کنند به انتهای تاریخچه موجود ضمیمه می‌شود، بنابراین درخواست بعدی هزینه محتوای جدید را می‌پردازد و همچنان همه موارد قبلی را از کش می‌خواند. استثنا، افزونه‌ای است که یک سرور MCP ارائه می‌دهد. اگر ابزارهای آن توسط جستجوی ابزار به تعویق بیفتند، کش حفظ می‌شود. اگر آن‌ها در پیش‌وند پرامپت (prompt prefix) بارگذاری شوند، درخواست بعدی کل گفتگو را به عنوان ورودی غیرکش‌شده (uncached) می‌خواند. دقیقاً به همین دلیل است که /reload-plugins در این موارد هشدار می‌دهد و تا زمانی که --force را تأیید نکنید، از انجام آن خودداری می‌کند.

شما می‌توانید به جای حدس زدن، این موارد را مانیتور کنید. هر پاسخ API، مقادیر cache_read_input_tokens و cache_creation_input_tokens را گزارش می‌دهد و یک خط وضعیت سفارشی که استفاده لحظه‌ای از توکن را نشان می‌دهد، هر دو مقدار را پیش روی شما قرار می‌دهد. در یک نشست بهینه، میزان خواندن بسیار بیشتر از میزان ایجاد (creation) است. اگر میزان ایجاد در هر مرحله بالا باقی بماند، یعنی چیزی در پیش‌وند شما در هر مرحله در حال تغییر است. برای درک بهتر از آنچه پنجره کانتکست را پر می‌کند، به نحوه مدیریت پنجره کانتکست Claude Code و معنای واقعی آن تعداد توکن‌ها مراجعه کنید.

یک اقدام نظافتی ساده، هزینه خود را جبران می‌کند. زبانه Installed افزونه‌هایی را که حداقل دو هفته از آن‌ها استفاده نکرده‌اید، زیر سرتیتر Not used recently گروه‌بندی می‌کند و در نمای جزئیات، خط Last used را نمایش می‌دهد. این افزونه‌ها همچنان در هر نشست، زمان راه‌اندازی و فضای کانتکست شما را اشغال می‌کنند. آن‌ها را غیرفعال یا حذف کنید.

یک افزونه با دسترسی‌های کاربری شما اجرا می‌شود

مستندات خود Anthropic در این باره صریح است: افزونه‌ها و مارکت‌پلیس‌ها مؤلفه‌هایی با سطح اعتماد بالا هستند که می‌توانند کدهای دلخواه را با امتیازات کاربری شما روی دستگاهتان اجرا کنند. این یک فرضیه نیست. هوک‌های یک افزونه، دستورات shell را در رویدادهای نشست (session)، از جمله قبل و بعد از فراخوانی ابزارها، اجرا می‌کنند. دایرکتوری bin/ آن در زمان فعال بودن افزونه به PATH ابزار Bash اضافه می‌شود. سرورهای MCP آن نیز فرآیندهایی هستند که توسط خود افزونه شروع می‌شوند. در اینجا هیچ‌چیز از حساب کاربری شما ایزوله (sandbox) نشده است.

روی یک لپ‌تاپ، این ریسک محدود به دسترسی‌های کاربر دسکتاپ شماست. اما روی یک سرور، معمولاً این‌طور نیست. حسابی که عامل (agent) را اجرا می‌کند، اغلب دارای کلیدهای SSH، توکن‌های استقرار (deploy tokens)، نشست‌های cloud CLI و دسترسی به Docker socket است؛ بنابراین «اجرای کد دلخواه با کاربر شما» به معنای در اختیار گرفتن کل ماشین است. اگر Claude Code را روی یک VPS اجرا می‌کنید، پیش از نصب هر چیزی نحوه اجرای امن Claude Code روی VPS را بخوانید و پیش از نصب افزونه‌ای که با یک سرویس خارجی در ارتباط است، نحوه دور نگه داشتن اعتبارنامه‌ها از دسترس یک عامل را مطالعه کنید.

برخی محافظ‌ها (guardrails) وجود دارند و دانستن آن‌ها مفید است. یک افزونه با محدوده پروژه (project-scope) از مخزن (repository) می‌آید، نه از سمت شما؛ بنابراین تنها پس از آنکه به فضای کاری (workspace) اعتماد کردید بارگذاری می‌شود، سرورهای MCP آن همچنان نیاز به تأییدیه برای هر سرور دارند، سرورهای LSP آن منتظر آن اعتماد می‌مانند و مانیتورهای پس‌زمینه آن اصلاً بارگذاری نمی‌شوند. عامل‌هایی که همراه افزونه‌ها ارائه می‌شوند، اجازه ندارند هوک، سرور MCP یا حالت دسترسی (permission mode) تعریف کنند. افزونه‌های مارکت‌پلیس در کش کپی می‌شوند و symlinkهایی که به خارج از مارکت‌پلیس اشاره دارند نادیده گرفته می‌شوند، بنابراین یک افزونه نمی‌تواند فایل‌های دلخواه میزبان را فراخوانی کند.

هیچ‌کدام از این‌ها جایگزین بررسی آنچه نصب می‌کنید نمی‌شود. لیست Will install را چک کنید، افزونه‌هایی را ترجیح دهید که سورس‌کد آن‌ها قابل مشاهده و خواندن باشد، افزونه‌های تیم خود را در یک مخزن مارکت‌پلیس که تحت کنترل شماست نگه دارید و روی هر چیزی که خودتان می‌نویسید claude plugin validate را اجرا کنید.

FAQ

آیا پلاگین‌های Claude Code هزینه اضافی دارند؟

خیر. سیستم پلاگین، افزودن مارکت‌پلیس یا نصب پلاگین هیچ هزینه‌ای ندارد. هزینه مربوط به مصرف توکن است که مانند هر محتوای دیگری، از طرح اشتراک یا اعتبار API شما کسر می‌شود. یک پلاگین در هر مرحله، محتوای ثابتی به زمینه (context) اضافه می‌کند، هنگام فراخوانی مهارت‌ها یا عامل‌هایش محتوای بیشتری می‌افزاید و اگر یک سرور MCP ارائه دهد که ابزارهایش در پیشوند پرامپت بارگذاری می‌شوند، می‌تواند باعث یک مرحله پرهزینه و بدون کش (uncached) شود. نمای جزئیات /plugin، پیش از نصب، یک برآورد Context cost به شما نشان می‌دهد.

تفاوت بین پلاگین و مهارت (skill) چیست؟

مهارت یک واحد دستوری واحد است. پلاگین بسته‌ای است که می‌تواند شامل مهارت‌ها، عامل‌ها (agents)، هوک‌ها، سرورهای MCP، سرورهای LSP و مانیتورها باشد و دارای نام، نسخه و مارکت‌پلیسی برای نصب است. زمانی که یک مهارت برای استفاده شخصی و این پروژه است، آن را در .claude/ به صورت مستقل بنویسید. یک مهارت تک‌منظوره مانند Ponytail که عامل را به سمت کوچک‌ترین تغییرِ کارآمد سوق می‌دهد، واضح‌ترین نمونه برای این مورد است: یک فایل با یک قانون واحد، تا روزی که تیم شما نیز به آن نیاز پیدا کند. زمانی که دیگران به آن نیاز دارند و لازم است در طول زمان به‌روزرسانی شود، آن را به یک پلاگین تبدیل کنید. مهارت‌های پلاگین دارای فضای نام (namespaced) هستند، بنابراین یک مهارت درون پلاگین به جای /skill-name، با نام /plugin-name:skill-name فراخوانی می‌شود.

پلاگین من نصب شد اما مهارت‌هایش ظاهر نمی‌شوند. مشکل چیست؟

ابتدا خلاصه نصب را بررسی کنید. اگر پیام Run /reload-plugins to activate. نمایش داده شد، یعنی اجزا هنوز بارگذاری نشده‌اند؛ اگر در هنگام بارگذاری مجدد هشدار داد که مکالمه دوباره خوانده می‌شود، آن را با دستور /reload-plugins --force دوباره اجرا کنید. اگر بارگذاری شد اما چیزی نشان نمی‌دهد، /plugin را باز کرده و زبانه Errors را بخوانید. رایج‌ترین اشتباه ساختاری، قرار دادن skills/، agents/ یا hooks/ در داخل .claude-plugin/ است، جایی که Claude Code آن‌ها را جستجو نمی‌کند. به یاد داشته باشید که مهارت‌های پلاگین دارای فضای نام هستند، بنابراین شما باید به دنبال /plugin-name:skill-name در زبانه Custom commands از /help باشید. به عنوان آخرین راهکار، rm -rf ~/.claude/plugins/cache را انجام دهید، ری‌استارت کنید و دوباره نصب نمایید.

آیا می‌توانم بدون پنل تعاملی، پلاگین نصب کنم؟

بله. از دستور شل claude plugin install name@marketplace استفاده کنید که پلاگین را در محدوده کاربر (user scope) نصب می‌کند، مگر اینکه از فلگ --scope project یا --scope local استفاده کنید. این دستور در اسکریپت‌ها، ایمیج‌ها و محیط‌های غیرتعاملی که پنل /plugin در دسترس نیست، کار می‌کند. از آنجایی که این دستور خارج از یک نشست (session) اجرا می‌شود، نشستی که از قبل باز است برای اعمال تغییرات پلاگین نیاز به /reload-plugins دارد.

آیا نصب پلاگین از مارکت‌پلیسی که در GitHub پیدا کرده‌ام امن است؟

با آن همان‌طور رفتار کنید که با اجرای اسکریپت نصب آن مخزن با دسترسی خودتان رفتار می‌کنید، زیرا ماهیت آن تقریباً همین است. یک پلاگین می‌تواند از طریق هوک‌ها دستورات شل اجرا کند، فایل‌های اجرایی را به PATH ابزار Bash اضافه کند و سرورهای MCP را با دسترسی‌های کاربری شما راه‌اندازی نماید. شرکت Anthropic محتوای پلاگین‌های شخص ثالث را کنترل یا تأیید نمی‌کند. از منابعی نصب کنید که می‌توانید آن‌ها را بخوانید، پیش از تأیید لیست Will install را بررسی کنید و در سرور سخت‌گیرتر از لپ‌تاپ باشید، زیرا حساب کاربری در سرور معمولاً حاوی کلیدها و توکن‌هایی است که ارزش سرقت دارند.