پلاگین Claude Code چیست و چه هزینهای دارد؟
با ساختار پلاگینهای 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، بافتار (context) پروژه است که در ابتدای نشست خوانده شده و بر همه چیز اعمال میشود. - پلاگین (Plugin) یک کانتینر است که میتواند مهارتها، عاملها، هوکها و تعاریف سرور MCP را بههمراه شماره نسخه و کانال توزیع در خود جای دهد.
بنابراین، پرسشی که یک پلاگین به آن پاسخ میدهد این نیست که «عامل چه کاری میتواند انجام دهد»، بلکه این است که «چگونه این ابزار را به تیم خود ارائه دهم و ماه آینده آن را بهروزرسانی کنم». اگر در حال انتخاب بین سه مورد اول هستید، مقایسه مهارتها، سرورهای MCP و فایلهای قوانین این تصمیم را بهطور مفصل بررسی میکند. اگر بخش MCP برای شما اهمیت دارد، اجرای سرورهای MCP شخصی روی VPS جنبههای میزبانی آن را پوشش میدهد.
محل قرارگیری افزونهها و محتویات آنها
افزونهای که از یک بازارچه (marketplace) نصب میشود، بهجای اجرا از محلی که کلون شده است، در یک کش محلی در ~/.claude/plugins/cache کپی میشود. هر نسخهٔ نصبشده، دایرکتوری اختصاصی خود را دارد. هنگامی که افزونهای را بهروزرسانی یا حذف میکنید، دایرکتوری نسخهٔ قدیمی بهعنوان یتیم (orphaned) علامتگذاری شده و حدود دو هفته بعد حذف میشود؛ بنابراین، نشست (session) کاری که قبلاً نسخهٔ قدیمی را بارگذاری کرده است، بهجای مواجهه با خطا در حین انجام کار، به فعالیت خود ادامه میدهد.
از آنجا که مسیر (path) در هر بهروزرسانی تغییر میکند، یک افزونه هرگز نباید موقعیت خود را بهصورت 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توجه داشته باشید که مخزن anthropics/claude-code نام دارد در حالی که marketplace با نام claude-code-plugins شناخته میشود. این نام از فایل کاتالوگ داخل مخزن گرفته شده است، نه از مسیر مخزن؛ بنابراین پیش از تایپ دستور نصب، نام marketplace را از تب Marketplaces در /plugin بخوانید.
پس از نصب، خط خلاصه را بخوانید. Plugin is now active. به این معنی است که مؤلفهها در این نشست بارگذاری شدهاند. 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 listclaude 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 ویرایشهای شما را بدون نیاز به restart اعمال میکند و claude plugin validate ./my-plugin پیش از آنکه دیگران آن را ببینند، manifest، مهارت، frontmatter عامل و hooks/hooks.json را بررسی میکند.
هزینه پلاگین Claude Code چقدر است؟
مکانیسم استفاده از آن رایگان است. تا اوت 2026، هیچ هزینهای برای افزودن مارکتپلیس، نصب پلاگین یا فعال نگهداشتن آن دریافت نمیشود. مارکتپلیسهای رسمی و اجتماعی، مخازن عمومی git هستند و هر پلاگین، پوشهای از فایلهای متنی است.
هزینه واقعی یک پلاگین، توکن (token) است و توکنها همان چیزی هستند که میزان مصرف اشتراک یا صورتحساب API شما را تعیین میکنند. اینکه یک پلاگین از کدامیک از این دو کسر میکند، به نحوه پرداخت شما برای ابزار بستگی دارد و هزینه Claude Code در هر طرح، سطوح اشتراک را در کنار قیمتگذاری API بر اساس هر توکن مشخص میکند. این هزینه به سه روش مختلف اعمال میشود که رفتار متفاوتی دارند.
هزینه زمینه ثابت (Standing context cost). آنچه یک پلاگین به زمینه (context) اضافه میکند، در حافظه باقی میماند و در هر نوبت از نشست (session) دوباره خوانده میشود. پیش از نصب، نمای جزئیات /plugin یک تخمین Context cost بر اساس توکن به همراه بخش Will install نمایش میدهد که شامل دستورات، مهارتها، عاملها (agents)، هوکها و سرورهای MCP و LSP است که قصد افزودن آنها را دارید. هر دو را مطالعه کنید. پلاگینهای مارکتپلیسهای محلی یا سفارشی ممکن است این دادهها را ارائه ندهند که در این صورت باید خودتان تخمین بزنید. پلاگینی که یک سرور MCP را بستهبندی میکند معمولاً سنگینترین است، زیرا تعاریف ابزارها حجیم هستند؛ هرچند در مدلهایی که از جستجوی ابزار MCP پشتیبانی میکنند، این تعاریف تا زمانی که به ابزار نیاز نباشد، بارگذاری نمیشوند.
هزینه فراخوانی (Invocation cost). اجرای مهارت (skill) یک پلاگین، دستورالعملهای آن را به گفتگو اضافه میکند، بنابراین شما فقط زمانی هزینه بدنه مهارت را میپردازید که از آن استفاده شود. بدنه مهارت بخش ارزان ماجراست، اما آنچه مهارت به عامل دیکته میکند لزوماً ارزان نیست: روش Depth Tree در مهارت unlazy تقریباً تمام توکنهای خود را صرف پردازشهای اضافی میکند که پیش از اجازه دادن به عامل برای اعلام پایان وظیفه انجام میدهد، نه صرف فایلی که نصب کردهاید. یک عامل (agent) متفاوت است. یک زیر-عامل (subagent) گفتگوی خاص خود را با پرامپت سیستمی و کش (cache) اختصاصیاش اجرا میکند و بدون هیچ cache hit شروع میشود؛ بنابراین پلاگینی که گردشکار آن باعث ایجاد عاملها میشود، هزینه بسیار بیشتری نسبت به تخمین زمینه آن دارد.
هزینه کش (Cache cost). فعال یا غیرفعال کردن یک پلاگین در میان یک نشست میتواند باعث شود درخواست بعدی، کل گفتگوی شما را دوباره پردازش کند. مهارتها، دستورات، عاملها، هوکها، سرورهای LSP، مانیتورها و تمها هرگز چنین کاری نمیکنند: آنچه آنها اضافه میکنند به انتهای تاریخچه موجود پیوست میشود، بنابراین درخواست بعدی هزینه محتوای جدید را میپردازد و همچنان همه چیز پیش از آن را از کش میخواند. استثنا، پلاگینی است که یک سرور MCP ارائه میدهد. اگر ابزارهای آن توسط جستجوی ابزار به تعویق بیفتند، کش حفظ میشود. اگر آنها در پیشوند پرامپت بارگذاری شوند، درخواست بعدی کل گفتگو را به عنوان ورودی غیرکششده (uncached) دوباره میخواند. دقیقاً به همین دلیل است که /reload-plugins در این مورد هشدار میدهد و تا زمانی که --force را وارد نکنید، از انجام آن خودداری میکند.
شما میتوانید به جای حدس زدن، این موضوع را مشاهده کنید. هر پاسخ API، مقادیر cache_read_input_tokens و cache_creation_input_tokens را گزارش میدهد و یک خط وضعیت سفارشی که مصرف زنده توکن را نشان میدهد، هر دو را پیش روی شما میگذارد. یک نشست سالم، بسیار بیشتر از آنچه ایجاد میکند، میخواند. اگر میزان ایجاد محتوا نوبت به نوبت بالا بماند، چیزی در پیشوند شما در هر نوبت در حال تغییر است. برای درک وسیعتر از آنچه پنجره را پر میکند، به نحوه مدیریت پنجره زمینه 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 را مطالعه کنید و پیش از نصب افزونهای که با سرویسهای خارجی در ارتباط است، نحوه دور نگه داشتن اعتبارنامهها از دسترس عامل را بخوانید. سایر ابزارهای مشابه نیز در همان سرورهای اجارهای با همین محدودیتها مواجه هستند؛ به همین دلیل است که افزونههای DeepSeek Harness که ارزش نصب دارند عمدتاً شامل محدودیتهای هزینه، قوانین دسترسی ابزارها و اسکن تزریق کد هستند، نه قابلیتهای جدید.
برخی محافظها (guardrails) وجود دارند و شناخت آنها مفید است. یک افزونه در سطح پروژه (project-scope) از مخزن (repository) بارگذاری میشود، نه از سمت شما؛ بنابراین تنها پس از آنکه به فضای کاری اعتماد کردید بارگذاری میشود، سرورهای 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 که عامل را به سمت کوچکترین تغییرِ کارآمد سوق میدهد، واضحترین نمونه برای این کار است: یک فایل با یک قانون واحد، تا روزی که تیم شما نیز به آن نیاز پیدا کند. زمانی که دیگران به آن نیاز دارند و لازم است در طول زمان بهروزرسانی شود، آن را به یک پلاگین تبدیل کنید. مهارتهای پلاگین دارای فضای نام (namespace) هستند، بنابراین یک مهارت درون پلاگین به جای /skill-name، به صورت /plugin-name:skill-name فراخوانی میشود.
پلاگین من نصب شد اما مهارتهایش ظاهر نمیشوند. مشکل چیست؟
ابتدا خلاصه نصب را بررسی کنید. اگر پیام Run /reload-plugins to activate. نمایش داده شده، یعنی اجزا هنوز بارگذاری نشدهاند؛ اگر در هنگام بارگذاری مجدد هشداری مبنی بر خواندن دوباره گفتگو دریافت کردید، آن را با /reload-plugins --force دوباره اجرا کنید. اگر بارگذاری انجام شد اما چیزی نمایش داده نمیشود، /plugin را باز کرده و تب Errors را بخوانید. رایجترین خطای ساختاری، قرار دادن skills/، agents/ یا hooks/ در داخل .claude-plugin/ است، جایی که Claude Code آنها را جستجو نمیکند. به یاد داشته باشید که مهارتهای پلاگین دارای فضای نام هستند، بنابراین باید در تب Custom commands از /help به دنبال /plugin-name:skill-name باشید. به عنوان آخرین راهکار، 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 را بررسی کنید و در سرور سختگیرانهتر از لپتاپ عمل کنید، زیرا حساب کاربری در سرور معمولاً حاوی کلیدها و توکنهایی است که ارزش سرقت دارند.