چطور هزینه‌ی کانتکست اسکیل‌ها را کم و اثرشان را بسنجیم

هر اسکیلی که در کلاد کد بارگذاری می‌شود، حتی اگر هیچ‌وقت اجرا نشود، توکن مصرف می‌کند. سه ابزار این هزینه را قابل اندازه‌گیری کرده‌اند: /skill-doctor اسکیل‌های بی‌استفاده را نشان می‌دهد، claude plugin details سهم هر جزء را جدا می‌کند، و claude plugin eval از نسخه‌ی 2.1.269 به بعد ثابت می‌کند که اسکیل شما واقعاً کاری را که ادعا می‌کند انجام می‌دهد یا نه. در این نوشته هر سه را با عدد و دستور واقعی باز می‌کنیم.

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

مستندات رسمی کلاد کد یک جمله‌ی صریح دارد: در هر نشستی که یک پلاگین فعال است، نام و توضیح اسکیل‌ها، ایجنت‌ها و دستورهای آن پلاگین وارد کانتکست کلود می‌شود و این توکن‌ها حتی اگر هیچ‌چیز اجرا نشود از سهمیه‌ی شما کم می‌شود [4]. یعنی هزینه‌ی یک اسکیل به تعداد اسکیل‌های بارگذاری‌شده ربط دارد، نه به تعداد دفعات اجرای آن.

یک عدد واقعی از همین بحث: در نسخه‌ی 2.1.234 تیم کلاد کد هزینه‌ی کانتکستی اسکیل درون‌ساخت claude-api را از بیش از ۲۰۰ هزار توکن به حدود ۲۵ هزار توکن رساند، با این روش که مستندات مرجع را به‌صورت lazy بارگذاری کند [2]. یعنی یک اسکیل با متن خام بسیار بلند، اگر بد نوشته شده باشد، می‌تواند بخش بزرگی از پنجره‌ی کانتکست را در هر نشست ببلعد.

نکته‌ی دوم این است که بدنه و فهرست اسکیل دو هزینه‌ی جدا هستند. برخلاف محتوای CLAUDE.md، بدنه‌ی یک اسکیل فقط وقتی بارگذاری می‌شود که آن اسکیل استفاده شود، اما توضیحش از ابتدا در فهرست اسکیل‌ها حاضر است [5]. پس کار مؤثر روی هزینه‌ی دائمی، کوتاه‌کردن description است، نه متن SKILL.md.

برای دیدن اینکه پول کجا می‌رود، اولین قدم /context است. برای سرورهای MCP، مستندات همین کار را پیشنهاد می‌کنند: سهم MCPهای یک پلاگین را از ستون MCP tools بخوانید، چون plugin details برای آن‌ها برآورد هزینه نمی‌دهد [4].

سه دستور که باید بشناسید

کلاد کد چهار جای مختلف به شما می‌گوید کدام پلاگین‌ها دیگر استفاده نمی‌شوند: پنل /plugin، خود /skill-doctor، بخش /doctor و صفحه‌ی /usage [4]. برای یک توسعه‌دهنده‌ی منفرد، دو دستور کار را کامل می‌کنند.

دستور /skill-doctor در ۴ سپتامبر ۲۰۲۶ به چرخه‌ی تغییرات اضافه شد [1]. توضیح رسمی آن دو چیز را با هم نشان می‌دهد: کدام اسکیل‌های بارگذاری‌شده هیچ‌وقت استفاده نشده‌اند و هرکدام چقدر کانتکست هزینه داشته‌اند [2]. این همان سه نقطه‌ای است که در پست بودجه‌ی کانتکست ایجنت توضیح دادم؛ جایی هست که پول هدر می‌رود بی‌آنکه چیزی بخرد. /skill-doctor آن سه نقطه را نام می‌برد.

دستور دوم بیرون از نشست اجرا می‌شود، نه در پرامپت. فهرست کامل پرچم‌های آن در مرجع دستورهای پلاگین آمده است [7].

claude plugin details formatter

formatter 1.0.0
  Description: Formats and lints code on save
  Source: formatter@my-marketplace

Component inventory
  Skills (3)  format-all, format-code, lint-fix
  Agents (1)  style-reviewer
  Hooks (1)  PostToolUse  (harness-only - no model context cost)
  MCP servers (1)  formatter-tools  (tool schemas resolved at runtime; not counted)
  LSP servers (0)

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

Per-component (rounded)
  component       always-on  on-invoke
  format-code           ~40        ~30
  lint-fix              ~50        ~30
  style-reviewer        ~40        ~40
  format-all           < 20        ~30

این نمونه از مستندات رسمی است [4]. دو نکته از همین خروجی خوانده می‌شود. اول اینکه هر پلاگین دو نوع هزینه دارد: Always-on که در هر نشست پرداخت می‌شود و on-invoke که هر بار جزء اجرا می‌شود. دوم اینکه هوک‌ها و سرورهای MCP در این جدول سطری نمی‌گیرند، چون هارنس آن‌ها را بدون هزینه‌ی کانتکست مدل اجرا می‌کند [4].

جمع سطرهای always-on در همین نمونه می‌شود ۴۰ به‌علاوه‌ی ۵۰ به‌علاوه‌ی ۴۰ به‌علاوه‌ی کمتر از ۲۰، یعنی بین ۱۳۰ تا ۱۵۰ توکن. عدد Always-on: ~146 tok دقیقاً در همین بازه قرار می‌گیرد و اختلاف از گردکردن اعداد می‌آید.

چطور هزینه‌ی دائمی را کم کنیم

اگر پلاگین را نگه می‌دارید، چهار راه دارید. اول کوتاه‌کردن توضیح اسکیل‌ها. دوم حذف اسکیل‌هایی که هرگز صدا زده نمی‌شوند. سوم خاموش‌کردن اسکیل‌های درون‌ساخت با disableBundledSkills [5][6]. چهارم جابه‌جایی یک اسکیل از حالت همیشه‌حاضر به حالت فقط‌با‌فرمان. ترتیب فایل‌های تنظیمات و اینکه کدام فایل بر کدام حرفه دارد در راهنمای تنظیمات آمده است [10].

برای مورد چهارم، دو راه جدا دارید که فرقشان در ویرایش فایل است. اگر مالک SKILL.md هستید، در frontmatter بنویسید:

---
name: deploy
description: Build and run the deploy checklist for the release branch
disable-model-invocation: true
---

مقدار disable-model-invocation: true جلوی بارگذاری خودکار این اسکیل توسط کلود را می‌گیرد و شما آن را با /deploy صدا می‌زنید [5]. اما اگر فایل در یک ریپازیتوری مشترک کامیت شده و نمی‌خواهید دست بزنید، مقدار "user-invocable-only" در skillOverrides همان اثر را بدون ویرایش فایل می‌گذارد [5].

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

منوی /skills این فایل را برایتان می‌نویسد: یک اسکیل را هایلایت کنید و کلید Space را بزنید تا بین حالت‌ها بچرخد، بعد با Esc در .claude/settings.local.json ذخیره کنید [5]. اگر توضیح اسکیل‌های شما در فهرست بریده می‌شود، مشکل بودجه است نه نگارش. تنظیم skillListingBudgetFraction سهم بیشتری از کانتکست را به فهرست اسکیل‌ها اختصاص می‌دهد و برای مثال 0.02 یعنی ۲ درصد [5][6]. کلید skillListingMaxDescChars هم سقف طول توضیح هر اسکیل را جدا تعیین می‌کند [6].

سنجش اثر واقعی اسکیل با plugin eval

ساختار کار ساده است. مجموعه‌ی کیس‌ها در پوشه‌ی evals/ داخل پلاگین زندگی می‌کند و هر کیس یک prompt.md دارد به‌علاوه‌ی یک یا چند grader [3].

my-plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── evals/
    ├── first-case/
    │   ├── prompt.md          # frontmatter: case fields; body: the prompt
    │   ├── graders/
    │   │   ├── criteria.md    # frontmatter: type + options; body: rubric
    │   │   └── skill-fired.md
    │   └── case.yaml          # optional: only for context.* fields
    └── results/               # add to .gitignore

هر کیس به‌طور پیش‌فرض سه بار اجرا می‌شود، پس یک کیس شش اجراست. نمره‌ی هر اجرا نسبتی از graderهایی است که قبول شده‌اند و نمره‌ی کیس میانگین آن سه اجراست. یک کیس وقتی قبول می‌شود که نمره‌اش به آستانه‌ی --threshold برسد که پیش‌فرض 1.0 است، و پایین آمدن از آن خروج با کد ۱ می‌دهد [3].

خروجی یک اجرا چنین شکلی است:

CASE        WITH  W/OUT  DELTA      RUNS COST    NOTES
first-case  1.00  0.33  +0.67  6    $0.41

1 case(s) - mean delta +0.67 - 74s - $0.41
Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html

عدد Δ برابر ۰٫۶۷ از تفریق ۱٫۰۰ منهای ۰٫۳۳ به دست می‌آید و شش اجر هم حاصل سه بار با پلاگین و سه بار بدون آن است. یک کیس که هم با پلاگین و هم بدون آن ۱٫۰۰ بگیرد، یعنی پلاگین هیچ چیزی به آن اضافه نکرده است [3].

انتخاب grader

از شش نوع grader موجود، چهار نوع از روی transcript و فایل‌ها حساب می‌شوند و هزینه‌ای ندارند: regex، tool_used، tool_order و file_exists. دو نوع دیگر یعنی llm و baseline یک مدل داور را صدا می‌زنند و به هزینه اضافه می‌شوند. مدل داور به‌طور پیش‌فرض یک مدل کوچک و سریع است [3].

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:"(?:[\w-]+:)?your-skill-name"'
---

این grader وقتی قبول می‌شود که کلود دست‌کم یک بار آن اسکیل را صدا زده باشد، و شکل namespaced یعنی plugin-name:skill-name را هم می‌پذیرد [3]. یک هشدار مهم هم اینجاست: هر grader از نوع tool_used که ابزارش Skill باشد از امتیازدهی کنار گذاشته می‌شود، چون بدون پلاگین هرگز نمی‌تواند قبول شود و در غیر این صورت بازوی بدون پلاگین را به سمت صفر می‌کشت و Δ را باد می‌داد [3]. در گزارش این graderها با نشان scored: false ظاهر می‌شوند و نقش نشانگر دارند نه امتیاز.

کنترل هزینه و اجرا در CI

سه اهرم برای هزینه دارید. --ablation none فقط بازوی با پلاگین را اجرا می‌کند و هزینه را نصف می‌کند. --concurrency عددی از ۱ تا ۸ می‌پذیرد و چند اجرا را هم‌زمان راه می‌اندازد؛ مستندات تصریح می‌کنند که این کار زمان دیواری را کوتاه می‌کند و توان عبوری را از سهمیه‌ی نرخ حساب بالاتر نمی‌برد [3]. --max-cost-usd هم سقف هزینه است که پیش از هر اجرا بررسی می‌شود، و اگر مصرف از آن بگذرد اجراهای شروع‌نشده رها می‌شوند و خروج با کد ۲ است [3].

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5 \
  --judge-model claude-haiku-4-5 \
  --no-publish \
  --max-cost-usd 20

پیش‌نیازها را هم جدی بگیرید. این دستور به کلاد کد 2.1.269 یا بالاتر و در صورت نصب بودن git به نسخه‌ی 2.31 به بالا نیاز دارد، و هر اجرا و هر داور یک فراخوانی واقعی مدل است که از سهمیه یا صورتحساب شما کم می‌شود [3]. هر grant که به Bash بدهید اجرا را زیر sandbox در سطح سیستم‌عامل می‌برد؛ روی ویندوز بومی هیچ backend ای وجود ندارد، پس این مجموعه‌ها باید زیر WSL2 اجرا شوند [8].

اول چه چیزی را بسنجیم

ترتیب درست کار از پرسمان هم شروع نمی‌شود. با /skill-doctor ببینید کدام اسکیل‌ها هرگز اجرا نشده‌اند و چه هزینه‌ای دارند، بعد با claude plugin details سهم هر جزء را جدا ببینید و هرکدام را که بی‌استفاده است یا پنهان کنید یا حذف. تازه بعد از آن سراغ claude plugin eval بروید، آن هم نه برای هر اسکیل.

مستندات خود کلاد کد یک هشدار روشن دارند: مجموعه‌ای که قبول می‌شود چیزی درباره‌ی امن بودن پلاگین نمی‌گوید، چون آن جداسازی فقط دسترسی ایجنت تحت آزمون را محدود می‌کند و مرزی در برابر کد خود پلاگین نیست [3]. اگر پلاگین شما هوک یا سرور MCP دارد که خودتان ننوشته‌اید، نمره‌ها را مشورتی حساب کنید و در یک کانتینر اجرا کنید.

برای تیم‌ها، همان صفحه‌ی سنجش دو رویداد OpenTelemetry را نام می‌برد: claude_code.plugin_loaded برای اینکه کدام پلاگین در چند نشست فعال است، و claude_code.skill_activated برای اینکه کدام اسکیل‌ها واقعاً فعال می‌شوند [9].

لحظه‌ی خواندن داده: ۲۶ سپتامبر ۲۰۲۶. همه‌ی نسخه‌ها و اعداد بالا از مستندات و چانج‌لگ رسمی خوانده شده‌اند.

منابع

1. Claude Code changelog
2. CHANGELOG.md در ریپازیتوری anthropics/claude-code
3. Test plugins with evals - Claude Code Docs
4. Measure plugin cost and usage
5. Extend Claude with skills
6. All settings
7. Plugin commands reference
8. Sandboxing
9. Monitoring usage
10. Settings files and precedence