گسترش Claude با skillها

Skillها قابلیت‌های Claude را گسترش می‌دهند. یک فایل SKILL.md با دستورالعمل‌ها بساز، و Claude آن را به جعبه‌ابزارش اضافه می‌کند. Claude هر وقت مرتبط باشد از skillها استفاده می‌کند، یا می‌توانی یکی را مستقیماً با /skill-name فراخوانی کنی.

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

برای دستورهای داخلی مثل /help و /compact، و skillهای همراهِ پیش‌فرض مثل /debug و /code-review، به مرجع دستورها مراجعه کن.

دستورهای سفارشی در skillها ادغام شده‌اند. فایلی در .claude/commands/deploy.md و یک skill در .claude/skills/deploy/SKILL.md هر دو /deploy را می‌سازند و یکسان کار می‌کنند. فایل‌های موجودِ .claude/commands/ تو همچنان کار می‌کنند. skillها قابلیت‌های اختیاری اضافه می‌کنند: یک پوشه برای فایل‌های پشتیبان، frontmatter برای کنترلِ اینکه تو یا Claude آن‌ها را فراخوانی می‌کنید، و امکانِ بارگذاریِ خودکارِ آن‌ها توسط Claude هنگامِ مرتبط‌بودن.

skillهای Claude Code از استانداردِ بازِ Agent Skills پیروی می‌کنند که روی ابزارهای متعددِ AI کار می‌کند. Claude Code این استاندارد را با قابلیت‌های بیشتری گسترش می‌دهد، مثل کنترلِ فراخوانی، اجرا در ساب‌ایجنت، و تزریقِ کانتکستِ پویا.

skillهای همراهِ پیش‌فرض

Claude Code مجموعه‌ای از skillهای همراهِ پیش‌فرض دارد که در هر نشست در دسترس‌اند مگر اینکه با تنظیمِ disableBundledSkills غیرفعال شوند، از جمله /code-review، /batch، /debug، /loop و /claude-api. برخلافِ بیشترِ دستورهای داخلی که منطقِ ثابتی را مستقیماً اجرا می‌کنند، skillهای همراه مبتنی بر پرامپت‌اند: به Claude دستورالعملِ دقیق می‌دهند و می‌گذارند کار را با ابزارهایش هماهنگ کند. آن‌ها را مثل هر skill دیگری فراخوانی می‌کنی، با تایپِ / و سپس نامِ skill.

skillهای همراه در کنارِ دستورهای داخلی در مرجع دستورها فهرست شده‌اند و در ستونِ Purpose با Skill مشخص شده‌اند.

اجرا و تأییدِ اپلیکیشنت

سه skillِ همراه با هم کار می‌کنند تا اپت را اجرا کنند و تغییرات را در برابرِ اپِ در حالِ اجرا تأیید کنند، نه فقط با تست‌ها:

Skill	Purpose
`/run`	اجرا و راهبریِ اپت برای دیدنِ کارکردِ یک تغییر
`/verify`	ساخت و اجرای اپت برای تأییدِ اینکه یک تغییرِ کد کارِ موردِنظر را انجام می‌دهد، بدون پناه‌بردن به تست‌ها یا بررسیِ تایپ
`/run-skill-generator`	به `/run` و `/verify` یاد می‌دهد چطور پروژه‌ات را بسازند و اجرا کنند

{/* min-version: 2.1.145 */}هر سه skill به Claude Code نسخه‌ی v2.1.145 یا بالاتر نیاز دارند.

/run و /verify بدون راه‌اندازی کار می‌کنند. آن‌ها نحوه‌ی اجرا را از نوعِ پروژه‌ات (CLI، server، TUI، browser-driven) و از محتوای README، package.json یا Makefile استنتاج می‌کنند. این استنتاج برای پروژه‌هایی که به چیزی فراتر از یک اجرای استاندارد نیاز دارند غیرقابل‌اعتماد می‌شود: یک پایگاه‌داده، یک فایلِ env، یک نشستِ گرافیکی، یک ساختِ چندمرحله‌ای.

/run-skill-generator به‌جای آن دستورِالعمل را ثبت می‌کند. اپت را از یک محیطِ تمیز به اجرا درمی‌آورد، آنچه را که کار کرد ثبت می‌کند (دستورهای نصب، متغیرهای env، اسکریپتِ اجرا) و آن را به‌صورت یک skillِ مخصوصِ پروژه در .claude/skills/run-<name>/ کامیت می‌کند. پس از آن، /run، /verify و هر ایجنت دیگری در مخزن به‌جای کشفِ دوباره، از دستورالعملِ ثبت‌شده پیروی می‌کنند. /run-skill-generator را یک‌بار برای هر پروژه اجرا کن، و دوباره اگر فرایندِ ساخت یا اجرا تغییر کرد.

شروعِ کار

اولین skill خود را بساز

این مثال یک skill می‌سازد که تغییراتِ کامیت‌نشده‌ی مخزنِ git تو را خلاصه می‌کند و هر چیزِ پرریسک را علامت می‌زند. diffِ زنده را قبل از اینکه Claude بخوانَدش به پرامپت می‌کشد، پس پاسخ بر اساسِ درختِ کاریِ واقعیِ تو ساخته می‌شود، نه آنچه Claude از فایل‌های باز حدس می‌زند. Claude این skill را وقتی درباره‌ی تغییراتت می‌پرسی به‌صورت خودکار بارگذاری می‌کند، یا می‌توانی مستقیماً با /summarize-changes فراخوانی‌اش کنی.

ساختِ پوشه‌ی skill

یک پوشه برای skill در پوشه‌ی skillهای شخصی‌ات بساز. skillهای شخصی در همه‌ی پروژه‌هایت در دسترس‌اند.

mkdir -p ~/.claude/skills/summarize-changes

نوشتنِ SKILL.md

هر skill به یک فایلِ SKILL.md با دو بخش نیاز دارد: frontmatterِ YAML میانِ نشانگرهای --- که به Claude می‌گوید چه زمانی از skill استفاده کند، و محتوای markdown با دستورالعمل‌هایی که Claude هنگامِ اجرای skill دنبال می‌کند. نامِ پوشه به دستوری تبدیل می‌شود که تایپ می‌کنی، و description به Claude کمک می‌کند تصمیم بگیرد چه زمانی skill را به‌صورت خودکار بارگذاری کند.

این را در ~/.claude/skills/summarize-changes/SKILL.md ذخیره کن:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

خطِ !`git diff HEAD` از تزریقِ کانتکستِ پویا استفاده می‌کند: Claude Code دستور را اجرا می‌کند و خط را با خروجی‌اش جایگزین می‌کند پیش از آنکه Claude محتوای skill را ببیند، پس دستورالعمل‌ها همراه با diffِ فعلیِ از پیش‌درج‌شده می‌رسند.

تستِ skill

یک پروژه‌ی git باز کن، یک ویرایشِ کوچک روی هر فایلی انجام بده، و با اجرای claude کلودکد را راه بینداز. می‌توانی skill را به دو روش تست کنی.

بگذار Claude به‌صورت خودکار فراخوانی‌اش کند با پرسیدنِ چیزی که با description مطابقت دارد:

What did I change?

یا مستقیماً فراخوانی‌اش کن با نامِ skill:

/summarize-changes

در هر دو حالت، Claude باید با خلاصه‌ای کوتاه از ویرایشت و فهرستی از ریسک‌ها پاسخ دهد.

skillها کجا زندگی می‌کنند

جایی که یک skill را ذخیره می‌کنی تعیین می‌کند چه کسی می‌تواند از آن استفاده کند:

محل	مسیر	اِعمال بر
Enterprise	به تنظیماتِ مدیریت‌شده مراجعه کن	همه‌ی کاربرانِ سازمانت
شخصی	`~/.claude/skills/<skill-name>/SKILL.md`	همه‌ی پروژه‌هایت
پروژه	`.claude/skills/<skill-name>/SKILL.md`	فقط این پروژه
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	هرجا plugin فعال باشد

وقتی skillها در سطوحِ مختلف نامِ یکسانی دارند، enterprise بر شخصی اولویت دارد، و شخصی بر پروژه. skillهای plugin از فضای‌نامِ plugin-name:skill-name استفاده می‌کنند، پس نمی‌توانند با سطوحِ دیگر تداخل کنند. اگر فایل‌هایی در .claude/commands/ داری، آن‌ها هم به همین شکل کار می‌کنند، اما اگر یک skill و یک command نامِ یکسانی داشته باشند، skill اولویت دارد.

تشخیصِ تغییرِ زنده

Claude Code پوشه‌های skill را برای تغییرِ فایل‌ها زیرِ نظر دارد. افزودن، ویرایش یا حذفِ یک skill زیرِ ~/.claude/skills/، پوشه‌ی پروژه‌ی .claude/skills/، یا یک .claude/skills/ِ داخلِ یک پوشه‌ی --add-dir در همان نشستِ جاری و بدونِ راه‌اندازیِ مجدد اثر می‌گذارد. ساختنِ یک پوشه‌ی skillِ سطح‌بالا که هنگامِ شروعِ نشست وجود نداشت به راه‌اندازیِ مجددِ Claude Code نیاز دارد تا پوشه‌ی جدید بتواند زیرِ نظر گرفته شود.

کشفِ خودکار از پوشه‌های والد و تودرتو

skillهای پروژه از .claude/skills/ در پوشه‌ی شروعت و در هر پوشه‌ی والد تا ریشه‌ی مخزن بارگذاری می‌شوند، پس شروعِ Claude در یک زیرپوشه باز هم skillهای تعریف‌شده در ریشه را برمی‌دارد. وقتی با فایل‌هایی در زیرپوشه‌های پایین‌ترِ پوشه‌ی شروعت کار می‌کنی، Claude Code همچنین skillها را از پوشه‌های .claude/skills/ِ تودرتو به‌صورت درخواستی کشف می‌کند. برای مثال، اگر داری فایلی را در packages/frontend/ ویرایش می‌کنی، Claude Code همچنین در packages/frontend/.claude/skills/ دنبالِ skill می‌گردد. این از ساختارهای monorepo که در آن‌ها بسته‌ها skillهای خودشان را دارند پشتیبانی می‌کند.

هر skill یک پوشه است با SKILL.md به‌عنوان نقطه‌ی ورود:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

SKILL.md دستورالعمل‌های اصلی را دربردارد و الزامی است. سایر فایل‌ها اختیاری‌اند و به تو امکان می‌دهند skillهای قدرتمندتری بسازی: قالب‌هایی برای پُرکردنِ Claude، خروجی‌های نمونه که قالبِ موردِانتظار را نشان می‌دهند، اسکریپت‌هایی که Claude می‌تواند اجرا کند، یا مستنداتِ مرجعِ مفصل. این فایل‌ها را از SKILL.md خود ارجاع بده تا Claude بداند چه محتوایی دارند و چه زمانی باید بارگذاری‌شان کند. برای جزئیاتِ بیشتر به افزودنِ فایل‌های پشتیبان مراجعه کن.

skillها از پوشه‌های اضافی

پرچمِ --add-dir و دستورِ /add-dir به‌جای کشفِ پیکربندی، دسترسیِ فایل اعطا می‌کنند، اما skillها یک استثنا هستند: .claude/skills/ِ داخلِ یک پوشه‌ی اضافه‌شده به‌صورت خودکار بارگذاری می‌شود. این استثنا فقط بر --add-dir و /add-dir اِعمال می‌شود. تنظیمِ permissions.additionalDirectories در settings.json فقط دسترسیِ فایل اعطا می‌کند و skillها را بارگذاری نمی‌کند. برای اینکه ببینی ویرایش‌ها در طولِ یک نشست چطور برداشته می‌شوند، به تشخیصِ تغییرِ زنده مراجعه کن.

سایر پیکربندی‌های .claude/ مثل ساب‌ایجنت‌ها، command‌ها و output styleها از پوشه‌های اضافی بارگذاری نمی‌شوند. برای فهرستِ کاملِ آنچه بارگذاری می‌شود و نمی‌شود، و روش‌های توصیه‌شده برای اشتراکِ پیکربندی میانِ پروژه‌ها، به جدولِ استثناها مراجعه کن.

پیکربندیِ skillها

skillها از طریقِ frontmatterِ YAML در بالای SKILL.md و محتوای markdownی که در پی می‌آید پیکربندی می‌شوند.

انواعِ محتوای skill

فایل‌های skill می‌توانند هر دستورالعملی را دربربگیرند، اما فکرکردن به اینکه می‌خواهی چطور فراخوانی‌شان کنی به هدایتِ آنچه باید بگنجانی کمک می‌کند:

محتوای مرجع دانشی اضافه می‌کند که Claude بر کارِ فعلیِ تو اِعمال می‌کند. قراردادها، الگوها، راهنماهای سبک، دانشِ دامنه. این محتوا به‌صورت inline اجرا می‌شود تا Claude بتواند آن را در کنارِ کانتکستِ گفت‌وگوی تو به کار ببرد.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

محتوای وظیفه به Claude دستورالعمل‌های گام‌به‌گام برای یک اقدامِ خاص می‌دهد، مثلِ استقرار، کامیت یا تولیدِ کد. این‌ها اغلب اقداماتی‌اند که می‌خواهی مستقیماً با /skill-name فراخوانی‌شان کنی، نه اینکه بگذاری Claude تصمیم بگیرد چه زمانی اجرایشان کند. disable-model-invocation: true را اضافه کن تا از فراخوانیِ خودکارِ آن توسط Claude جلوگیری کنی.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

SKILL.md تو می‌تواند هر چیزی را دربربگیرد، اما اندیشیدن به اینکه می‌خواهی skill چطور فراخوانی شود (توسطِ تو، توسطِ Claude، یا هر دو) و کجا اجرا شود (inline یا در یک ساب‌ایجنت) به هدایتِ آنچه باید بگنجانی کمک می‌کند. برای skillهای پیچیده، می‌توانی فایل‌های پشتیبان اضافه کنی تا skillِ اصلی متمرکز بماند.

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

مرجعِ frontmatter

فراتر از محتوای markdown، می‌توانی رفتارِ skill را با فیلدهای frontmatterِ YAML میانِ نشانگرهای --- در بالای فایلِ SKILL.md پیکربندی کنی:

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

همه‌ی فیلدها اختیاری‌اند. فقط description توصیه می‌شود تا Claude بداند چه زمانی از skill استفاده کند.

فیلد	الزامی	توضیح
`name`	خیر	نامِ نمایشی که در فهرستِ skillها نشان داده می‌شود. به‌صورت پیش‌فرض نامِ پوشه. برای اینکه ببینی این چطور با نامی که برای فراخوانیِ skill تایپ می‌کنی فرق دارد، به چطور یک skill نامِ دستورش را می‌گیرد مراجعه کن.
`description`	توصیه‌شده	چه کاری می‌کند و چه زمانی استفاده شود. Claude از این برای تصمیم درباره‌ی زمانِ اِعمالِ skill استفاده می‌کند. اگر حذف شود، از اولین پاراگرافِ محتوای markdown استفاده می‌شود. کاربردِ کلیدی را اول بگذار: متنِ ترکیب‌شده‌ی `description` و `when_to_use` در فهرستِ skillها در ۱٬۵۳۶ کاراکتر بریده می‌شود تا مصرفِ کانتکست کاهش یابد.
`when_to_use`	خیر	کانتکستِ اضافی برای زمانی که Claude باید skill را فراخوانی کند، مثلِ عبارت‌های ماشه‌ای یا درخواست‌های نمونه. به `description` در فهرستِ skillها افزوده می‌شود و در سقفِ ۱٬۵۳۶ کاراکتری حساب می‌شود.
`argument-hint`	خیر	راهنمایی که هنگامِ تکمیلِ خودکار نشان داده می‌شود تا آرگومان‌های موردِانتظار را مشخص کند. مثال: `[issue-number]` یا `[filename] [format]`.
`arguments`	خیر	آرگومان‌های موقعیتیِ نام‌دار برای جایگزینیِ `$name` در محتوای skill. یک رشته‌ی فاصله‌جدا یا یک فهرستِ YAML می‌پذیرد. نام‌ها به‌ترتیب به موقعیتِ آرگومان‌ها نگاشت می‌شوند.
`disable-model-invocation`	خیر	روی `true` بگذار تا از بارگذاریِ خودکارِ این skill توسطِ Claude جلوگیری شود. برای ورک‌فلوهایی که می‌خواهی دستی با `/name` راه‌اندازی‌شان کنی استفاده کن. همچنین از پیش‌بارگذاریِ skill در ساب‌ایجنت‌ها جلوگیری می‌کند. پیش‌فرض: `false`.
`user-invocable`	خیر	روی `false` بگذار تا از منوی `/` پنهان شود. برای دانشِ پس‌زمینه‌ای که کاربران نباید مستقیماً فراخوانی‌اش کنند استفاده کن. پیش‌فرض: `true`.
`allowed-tools`	خیر	ابزارهایی که Claude می‌تواند بدونِ پرسیدنِ مجوز هنگامِ فعال‌بودنِ این skill استفاده کند. یک رشته‌ی فاصله‌جدا یا کاما‌جدا، یا یک فهرستِ YAML می‌پذیرد.
`disallowed-tools`	خیر	ابزارهایی که هنگامِ فعال‌بودنِ این skill از مجموعه‌ی دردسترسِ Claude حذف می‌شوند. برای skillهای خودگردان که هرگز نباید ابزارهای خاصی را فراخوانی کنند استفاده کن، مثلِ `AskUserQuestion` برای یک حلقه‌ی پس‌زمینه. یک رشته‌ی فاصله‌جدا یا کاما‌جدا، یا یک فهرستِ YAML می‌پذیرد. محدودیت با ارسالِ پیامِ بعدی‌ات پاک می‌شود.
`model`	خیر	مدلی که هنگامِ فعال‌بودنِ این skill استفاده شود. این بازنویسی برای بقیه‌ی نوبتِ جاری اِعمال می‌شود و در تنظیمات ذخیره نمی‌شود؛ مدلِ نشست در پرامپتِ بعدی‌ات از سر گرفته می‌شود. همان مقادیرِ `/model` را می‌پذیرد، یا `inherit` برای حفظِ مدلِ فعال.
`effort`	خیر	سطحِ effort هنگامِ فعال‌بودنِ این skill. سطحِ effortِ نشست را بازنویسی می‌کند. پیش‌فرض: از نشست به ارث می‌رسد. گزینه‌ها: `low`، `medium`، `high`، `xhigh`، `max`؛ سطوحِ دردسترس به مدل بستگی دارد.
`context`	خیر	روی `fork` بگذار تا در یک کانتکستِ ساب‌ایجنتِ فورک‌شده اجرا شود.
`agent`	خیر	اینکه هنگامِ تنظیمِ `context: fork` از چه نوع ساب‌ایجنتی استفاده شود.
`hooks`	خیر	hookهایی که به چرخه‌ی حیاتِ این skill محدود شده‌اند. برای قالبِ پیکربندی به Hooks در skillها و agentها مراجعه کن.
`paths`	خیر	الگوهای glob که زمانِ فعال‌شدنِ این skill را محدود می‌کنند. یک رشته‌ی کاما‌جدا یا یک فهرستِ YAML می‌پذیرد. وقتی تنظیم شود، Claude skill را فقط هنگامِ کار با فایل‌های منطبق بر الگوها به‌صورت خودکار بارگذاری می‌کند. از همان قالبِ قواعدِ مخصوصِ مسیر استفاده می‌کند.
`shell`	خیر	shellی که برای !`command` و بلاک‌های ```! در این skill استفاده شود. `bash` (پیش‌فرض) یا `powershell` می‌پذیرد. تنظیمِ `powershell` دستورهای shellِ inline را روی Windows از طریقِ PowerShell اجرا می‌کند. به `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` نیاز دارد.

چطور یک skill نامِ دستورش را می‌گیرد

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

جدولِ زیر نشان می‌دهد نامِ دستور برای هر چیدمان از کجا می‌آید:

محلِ skill	منبعِ نامِ دستور	مثال
پوشه‌ی skill زیرِ `~/.claude/skills/` یا `.claude/skills/`	نامِ پوشه	`.claude/skills/deploy-staging/SKILL.md` ← `/deploy-staging`
فایل زیرِ `.claude/commands/`	نامِ فایل بدونِ پسوند	`.claude/commands/deploy.md` ← `/deploy`
زیرپوشه‌ی `skills/`ِ یک plugin	نامِ پوشه، با فضای‌نامِ plugin	`my-plugin/skills/review/SKILL.md` ← `/my-plugin:review`
`SKILL.md`ِ ریشه‌ی plugin	`name`ِ frontmatter، با نامِ پوشه‌ی plugin به‌عنوانِ پشتیبان	`my-plugin/SKILL.md` با `name: review` ← `/my-plugin:review`. به قواعدِ رفتارِ مسیر مراجعه کن

موردِ ریشه‌ی plugin تنها جایی است که name نامِ دستور را تعیین می‌کند، چون پوشه‌ی skillی نیست که نام از آن گرفته شود. اگر name در frontmatter تنظیم نشده باشد، به‌جایش نامِ پوشه‌ی plugin استفاده می‌شود.

جایگزینی‌های رشته‌ایِ دردسترس

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

متغیر	توضیح
`$ARGUMENTS`	همه‌ی آرگومان‌های پاس‌شده هنگامِ فراخوانیِ skill. اگر `$ARGUMENTS` در محتوا حاضر نباشد، آرگومان‌ها به‌صورتِ `ARGUMENTS: <value>` افزوده می‌شوند.
`$ARGUMENTS[N]`	دسترسی به یک آرگومانِ خاص با اندیسِ صفرپایه، مثلِ `$ARGUMENTS[0]` برای اولین آرگومان.
`$N`	شکلِ کوتاهِ `$ARGUMENTS[N]`، مثلِ `$0` برای اولین آرگومان یا `$1` برای دومی.
`$name`	آرگومانِ نام‌دارِ اعلام‌شده در فهرستِ frontmatterِ `arguments`. نام‌ها به‌ترتیب به موقعیت‌ها نگاشت می‌شوند، پس با `arguments: [issue, branch]` جانگهدارِ `$issue` به اولین آرگومان و `$branch` به دومی بسط می‌یابد.
`$\{CLAUDE_SESSION_ID\}`	شناسه‌ی نشستِ جاری. برای لاگ‌گیری، ساختنِ فایل‌های مخصوصِ نشست، یا همبسته‌کردنِ خروجیِ skill با نشست‌ها مفید است.
`$\{CLAUDE_EFFORT\}`	سطحِ effortِ جاری: `low`، `medium`، `high`، `xhigh` یا `max`. Ultracode یک سطحِ مجزا نیست و به‌عنوانِ `xhigh` گزارش می‌شود. از این برای تطبیقِ دستورالعمل‌های skill با تنظیمِ effortِ فعال استفاده کن.
`$\{CLAUDE_SKILL_DIR\}`	پوشه‌ای که فایلِ `SKILL.md`ِ skill را دربردارد. برای skillهای plugin، این زیرپوشه‌ی skill در درونِ plugin است، نه ریشه‌ی plugin. از این در دستورهای تزریقِ bash برای ارجاع به اسکریپت‌ها یا فایل‌های بسته‌بندی‌شده با skill استفاده کن، صرفِ‌نظر از پوشه‌ی کاریِ فعلی.

آرگومان‌های اندیس‌دار از نقل‌قول‌گذاریِ سبکِ shell استفاده می‌کنند، پس مقادیرِ چندکلمه‌ای را در نقل‌قول بپیچ تا به‌عنوانِ یک آرگومانِ واحد پاس شوند. برای مثال، /my-skill "hello world" second باعث می‌شود $0 به hello world و $1 به second بسط یابد. جانگهدارِ $ARGUMENTS همیشه به رشته‌ی کاملِ آرگومان‌ها همان‌طور که تایپ شده بسط می‌یابد.

برای گنجاندنِ یک $ِ تحت‌اللفظی پیش از یک رقم، ARGUMENTS، یا یک نامِ آرگومانِ اعلام‌شده، مثلِ $1.00 در نثر، آن را با یک بک‌اسلش escape کن: \$1.00. یک بک‌اسلش پیش از هر $ِ دیگری بدونِ تغییر باقی می‌ماند. فقط یک بک‌اسلشِ منفرد که مستقیماً پیش از توکن بیاید آن را escape می‌کند. یک بک‌اسلشِ دوگانه مثلِ \\$1 هر دو بک‌اسلش را سرِ جایش می‌گذارد، و $1 همچنان به مقدارِ آرگومان بسط می‌یابد.

مثالِ استفاده از جایگزینی‌ها:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/$\{CLAUDE_SESSION_ID\}.log:

$ARGUMENTS

افزودنِ فایل‌های پشتیبان

skillها می‌توانند چند فایل را در پوشه‌شان بگنجانند. این کار SKILL.md را متمرکز بر ضروریات نگه می‌دارد و در عینِ حال به Claude اجازه می‌دهد فقط هنگامِ نیاز به مراجعِ مفصل دسترسی پیدا کند. مستنداتِ مرجعِ بزرگ، مشخصاتِ API یا مجموعه‌های نمونه لازم نیست هر بار که skill اجرا می‌شود در کانتکست بارگذاری شوند.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

فایل‌های پشتیبان را از SKILL.md ارجاع بده تا Claude بداند هر فایل چه محتوایی دارد و چه زمانی باید بارگذاری‌اش کند:

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

کنترلِ اینکه چه کسی یک skill را فراخوانی می‌کند

به‌صورت پیش‌فرض، هم تو و هم Claude می‌توانید هر skillی را فراخوانی کنید. می‌توانی /skill-name را تایپ کنی تا مستقیماً فراخوانی‌اش کنی، و Claude می‌تواند هنگامِ مرتبط‌بودن با گفت‌وگویت به‌صورت خودکار بارگذاری‌اش کند. دو فیلدِ frontmatter اجازه می‌دهند این را محدود کنی:

disable-model-invocation: true: فقط تو می‌توانی skill را فراخوانی کنی. این را برای ورک‌فلوهایی با عوارضِ جانبی یا آن‌هایی که می‌خواهی زمان‌بندی‌شان را کنترل کنی استفاده کن، مثلِ /commit، /deploy یا /send-slack-message. نمی‌خواهی Claude تصمیم بگیرد استقرار کند چون کدت آماده به نظر می‌رسد.
user-invocable: false: فقط Claude می‌تواند skill را فراخوانی کند. این را برای دانشِ پس‌زمینه‌ای که به‌عنوانِ دستور قابلِ‌اقدام نیست استفاده کن. یک skillِ legacy-system-context توضیح می‌دهد یک سیستمِ قدیمی چطور کار می‌کند. Claude باید این را هنگامِ مرتبط‌بودن بداند، اما /legacy-system-context اقدامِ معناداری برای کاربران نیست.

این مثال یک skillِ deploy می‌سازد که فقط تو می‌توانی راه‌اندازی‌اش کنی. فیلدِ disable-model-invocation: true از اجرای خودکارِ آن توسطِ Claude جلوگیری می‌کند:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

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

Frontmatter	تو می‌توانی فراخوانی کنی	Claude می‌تواند فراخوانی کند	چه زمانی در کانتکست بارگذاری می‌شود
(پیش‌فرض)	بله	بله	description همیشه در کانتکست، skillِ کامل هنگامِ فراخوانی بارگذاری می‌شود
`disable-model-invocation: true`	بله	خیر	description در کانتکست نیست، skillِ کامل وقتی تو فراخوانی کنی بارگذاری می‌شود
`user-invocable: false`	خیر	بله	description همیشه در کانتکست، skillِ کامل هنگامِ فراخوانی بارگذاری می‌شود

چرخه‌ی حیاتِ محتوای skill

وقتی تو یا Claude یک skill را فراخوانی می‌کنید، محتوای رندرشده‌ی SKILL.md به‌عنوانِ یک پیامِ واحد واردِ گفت‌وگو می‌شود و برای بقیه‌ی نشست همان‌جا می‌مانَد. Claude Code فایلِ skill را در نوبت‌های بعدی دوباره نمی‌خوانَد، پس راهنمایی‌ای که باید در سراسرِ یک وظیفه اِعمال شود را به‌صورتِ دستورالعمل‌های پابرجا بنویس، نه گام‌های یک‌باره.

فشرده‌سازیِ خودکار skillهای فراخوانده‌شده را در چارچوبِ یک بودجه‌ی توکن به جلو می‌برد. وقتی گفت‌وگو برای آزادسازیِ کانتکست خلاصه می‌شود، Claude Code تازه‌ترین فراخوانیِ هر skill را پس از خلاصه دوباره می‌چسباند و ۵٬۰۰۰ توکنِ نخستِ هر کدام را نگه می‌دارد. skillهای دوباره‌چسبیده‌شده یک بودجه‌ی مشترکِ ۲۵٬۰۰۰ توکنی دارند. Claude Code این بودجه را از تازه‌ترین skillِ فراخوانده‌شده پُر می‌کند، پس اگر در یک نشست skillهای زیادی فراخوانده باشی، skillهای قدیمی‌تر می‌توانند پس از فشرده‌سازی کاملاً حذف شوند.

اگر به نظر می‌رسد یک skill پس از اولین پاسخ دیگر بر رفتار اثر نمی‌گذارد، محتوا معمولاً هنوز حاضر است و مدل دارد ابزارها یا رویکردهای دیگری را انتخاب می‌کند. description و دستورالعمل‌های skill را تقویت کن تا مدل همچنان آن را ترجیح دهد، یا از hookها برای اِعمالِ قطعیِ رفتار استفاده کن. اگر skill بزرگ است یا چندتای دیگر را پس از آن فراخوانده‌ای، پس از فشرده‌سازی دوباره فراخوانی‌اش کن تا محتوای کامل بازگردد.

پیش‌تأییدِ ابزارها برای یک skill

فیلدِ allowed-tools هنگامِ فعال‌بودنِ skill برای ابزارهای فهرست‌شده مجوز اعطا می‌کند، پس Claude می‌تواند بدونِ درخواستِ تأیید از تو از آن‌ها استفاده کند. این کار محدود نمی‌کند چه ابزارهایی در دسترس‌اند: هر ابزاری همچنان قابلِ‌فراخوانی می‌ماند، و تنظیماتِ دسترسیِ تو همچنان بر ابزارهای فهرست‌نشده حکومت می‌کنند.

برای skillهای کامیت‌شده در پوشه‌ی .claude/skills/ِ یک پروژه، allowed-tools پس از پذیرشِ دیالوگِ اعتمادِ workspace برای آن پوشه اثر می‌گذارد، درست مثلِ قواعدِ دسترسی در .claude/settings.json. پیش از اعتماد به یک مخزن، skillهای پروژه را مرور کن، چون یک skill می‌تواند به خودش دسترسیِ گسترده‌ی ابزار اعطا کند.

این skill اجازه می‌دهد Claude هر وقت فراخوانی‌اش کنی دستورهای git را بدونِ تأییدِ هر-بار اجرا کند:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

برای حذفِ ابزارها از مجموعه‌ی دردسترسِ Claude هنگامِ فعال‌بودنِ یک skill، آن‌ها را در disallowed-tools در frontmatterِ skill فهرست کن. محدودیت با ارسالِ پیامِ بعدی‌ات پاک می‌شود. برای مسدودکردنِ ابزارها در همه‌ی skillها و پرامپت‌ها، قواعدِ deny را در تنظیماتِ دسترسیِ خود اضافه کن.

پاس‌دادنِ آرگومان به skillها

هم تو و هم Claude می‌توانید هنگامِ فراخوانیِ یک skill آرگومان پاس بدهید. آرگومان‌ها از طریقِ جانگهدارِ $ARGUMENTS در دسترس‌اند.

این skill یک issueِ GitHub را با شماره‌اش رفع می‌کند. جانگهدارِ $ARGUMENTS با هر چیزی که پس از نامِ skill بیاید جایگزین می‌شود:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

وقتی /fix-issue 123 را اجرا کنی، Claude دریافت می‌کند: «Fix GitHub issue 123 following our coding standards…»

اگر یک skill را با آرگومان فراخوانی کنی اما skill شاملِ $ARGUMENTS نباشد، Claude Code عبارتِ ARGUMENTS: <your input> را به انتهای محتوای skill می‌افزاید تا Claude باز هم آنچه را که تایپ کرده‌ای ببیند.

برای دسترسی به آرگومان‌های منفرد بر اساسِ موقعیت، از $ARGUMENTS[N] یا شکلِ کوتاه‌ترِ $N استفاده کن:

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

اجرای /migrate-component SearchBar React Vue جایگزین می‌کند $ARGUMENTS[0] را با SearchBar، $ARGUMENTS[1] را با React، و $ARGUMENTS[2] را با Vue. همان skill با استفاده از شکلِ کوتاهِ $N:

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

الگوهای پیشرفته

تزریقِ کانتکستِ پویا

نحوِ !`<command>` دستورهای shell را پیش از ارسالِ محتوای skill به Claude اجرا می‌کند. خروجیِ دستور جای جانگهدار را می‌گیرد، پس Claude داده‌ی واقعی دریافت می‌کند، نه خودِ دستور را.

این skill یک pull request را با واکشیِ داده‌ی زنده‌ی PR از طریقِ GitHub CLI خلاصه می‌کند. دستورهای !`gh pr diff` و سایرین اول اجرا می‌شوند، و خروجی‌شان در پرامپت درج می‌شود:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

وقتی این skill اجرا می‌شود:

هر !`<command>` بی‌درنگ اجرا می‌شود (پیش از آنکه Claude چیزی ببیند)
خروجی جای جانگهدار را در محتوای skill می‌گیرد
Claude پرامپتِ کاملاً رندرشده را با داده‌ی واقعیِ PR دریافت می‌کند

این پیش‌پردازش است، نه چیزی که Claude اجرایش کند. Claude فقط نتیجه‌ی نهایی را می‌بیند.

جایگزینی یک‌بار روی فایلِ اصلی اجرا می‌شود. خروجیِ دستور به‌صورتِ متنِ ساده درج می‌شود و برای جانگهدارهای بیشترِ !`<command>` دوباره پویش نمی‌شود، پس یک دستور نمی‌تواند جانگهداری منتشر کند که در پویشِ بعدی بسط یابد.

شکلِ inline فقط زمانی شناسایی می‌شود که ! در ابتدای یک خط یا بلافاصله پس از فاصله‌ی خالی بیاید. اگر ! پس از کاراکترِ دیگری بیاید، مثلِ KEY=!`cmd`، جانگهدار به‌صورتِ متنِ تحت‌اللفظی باقی می‌ماند و دستور اجرا نمی‌شود.

برای دستورهای چندخطی، به‌جای شکلِ inline از یک بلاکِ کدِ محصور که با ```! باز می‌شود استفاده کن:

## Environment
```!
node --version
npm --version
git status --short
```

برای غیرفعال‌کردنِ این رفتار برای skillها و دستورهای سفارشیِ منابعِ user، project، plugin یا پوشه‌ی اضافی، در تنظیمات مقدارِ "disableSkillShellExecution": true را بگذار. هر دستور به‌جای اجرا با [shell command execution disabled by policy] جایگزین می‌شود. skillهای همراه و مدیریت‌شده تحتِ تأثیر قرار نمی‌گیرند. این تنظیم بیشتر در تنظیماتِ مدیریت‌شده مفید است، جایی که کاربران نمی‌توانند بازنویسی‌اش کنند.

اجرای skillها در یک ساب‌ایجنت

وقتی می‌خواهی یک skill در انزوا اجرا شود، context: fork را به frontmatterِ خود اضافه کن. محتوای skill به پرامپتی تبدیل می‌شود که ساب‌ایجنت را پیش می‌بَرد. به تاریخچه‌ی گفت‌وگوی تو دسترسی نخواهد داشت.

skillها و ساب‌ایجنت‌ها در دو جهت با هم کار می‌کنند:

رویکرد	پرامپتِ سیستمی	وظیفه	همچنین بارگذاری می‌کند
skill با `context: fork`	از نوعِ agent	محتوای SKILL.md	CLAUDE.md، مگر وقتی agent از نوعِ Explore یا Plan باشد
ساب‌ایجنت با فیلدِ `skills`	بدنه‌ی markdownِ ساب‌ایجنت	پیامِ واگذاریِ Claude	skillهای پیش‌بارگذاری‌شده + CLAUDE.md

با context: fork، وظیفه را در skillِ خود می‌نویسی و یک نوعِ agent برای اجرایش انتخاب می‌کنی. agentهای داخلیِ Explore و Plan برای کوچک‌نگه‌داشتنِ کانتکستشان از CLAUDE.md و وضعیتِ git صرف‌نظر می‌کنند، پس یک skillِ فورک‌شده که از agent: Explore استفاده می‌کند فقط محتوای SKILL.md و پرامپتِ سیستمیِ خودِ agent را می‌بیند. برای حالتِ معکوس، که در آن یک ساب‌ایجنتِ سفارشی تعریف می‌کنی که از skillها به‌عنوانِ مرجع استفاده می‌کند، به ساب‌ایجنت‌ها مراجعه کن.

مثال: skillِ پژوهش با استفاده از agentِ Explore

این skill پژوهش را در یک agentِ Exploreِ فورک‌شده اجرا می‌کند. محتوای skill به وظیفه تبدیل می‌شود، و agent ابزارهای فقط‌خواندنیِ بهینه‌شده برای کاوشِ کدبیس فراهم می‌کند:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

وقتی این skill اجرا می‌شود:

یک کانتکستِ منزویِ جدید ساخته می‌شود
ساب‌ایجنت محتوای skill را به‌عنوانِ پرامپتش دریافت می‌کند (“Research $ARGUMENTS thoroughly…”)
فیلدِ agent محیطِ اجرا (مدل، ابزارها و دسترسی‌ها) را تعیین می‌کند
نتایج خلاصه و به گفت‌وگوی اصلیِ تو بازگردانده می‌شوند

فیلدِ agent مشخص می‌کند از کدام پیکربندیِ ساب‌ایجنت استفاده شود. گزینه‌ها شاملِ agentهای داخلی (Explore، Plan، general-purpose) یا هر ساب‌ایجنتِ سفارشی از .claude/agents/ هستند. اگر حذف شود، از general-purpose استفاده می‌شود.

محدودکردنِ دسترسیِ Claude به skill

به‌صورت پیش‌فرض، Claude می‌تواند هر skillی را که disable-model-invocation: true تنظیم نشده فراخوانی کند. skillهایی که allowed-tools تعریف می‌کنند هنگامِ فعال‌بودنِ skill به Claude دسترسی به آن ابزارها را بدونِ تأییدِ هر-بار اعطا می‌کنند. تنظیماتِ دسترسیِ تو همچنان بر رفتارِ تأییدِ پایه برای همه‌ی ابزارهای دیگر حکومت می‌کنند. چند دستورِ داخلی هم از طریقِ ابزارِ Skill در دسترس‌اند، از جمله /init، /review و /security-review. سایر دستورهای داخلی مثلِ /compact در دسترس نیستند.

سه راه برای کنترلِ اینکه Claude کدام skillها را می‌تواند فراخوانی کند:

غیرفعال‌کردنِ همه‌ی skillها با deny‌کردنِ ابزارِ Skill در /permissions:

# Add to deny rules:
Skill

مجاز یا ممنوع‌کردنِ skillهای خاص با استفاده از قواعدِ دسترسی:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

نحوِ دسترسی: Skill(name) برای تطابقِ دقیق، Skill(name *) برای تطابقِ پیشوندی با هر آرگومانی.

پنهان‌کردنِ skillهای منفرد با افزودنِ disable-model-invocation: true به frontmatterشان. این کار skill را به‌کلی از کانتکستِ Claude حذف می‌کند.

بازنویسیِ مرئی‌بودنِ skill از تنظیمات

تنظیمِ skillOverrides مرئی‌بودنِ skill را به‌جای frontmatterِ خودِ skill از تنظیماتِ تو کنترل می‌کند. از آن برای skillهایی استفاده کن که نمی‌خواهی SKILL.mdشان را ویرایش کنی، مثلِ آن‌هایی که در یک مخزنِ پروژه‌ی مشترک کامیت شده‌اند یا توسطِ یک سرورِ MCP فراهم شده‌اند. منوی /skills آن را برایت می‌نویسد: یک skill را برجسته کن و Space را فشار بده تا میانِ حالت‌ها بچرخی، سپس Enter تا در .claude/settings.local.json ذخیره شود.

هر کلید یک نامِ skill است و هر مقدار یکی از چهار حالت:

مقدار	فهرست‌شده برای Claude	در منوی `/`
`"on"`	نام و توضیح	بله
`"name-only"`	فقط نام	بله
`"user-invocable-only"`	پنهان	بله
`"off"`	پنهان	پنهان

skillی که در skillOverrides غایب باشد به‌عنوانِ "on" رفتار می‌شود. مثالِ زیر یک skill را به نامش جمع می‌کند و دیگری را به‌کلی خاموش می‌کند:

\{
  "skillOverrides": \{
    "legacy-context": "name-only",
    "deploy": "off"
  \}
\}

skillهای plugin تحتِ تأثیرِ skillOverrides قرار نمی‌گیرند. آن‌ها را به‌جایش از طریقِ /plugin مدیریت کن.

اشتراکِ skillها

skillها بسته به مخاطبت می‌توانند در دامنه‌های مختلفی توزیع شوند:

skillهای پروژه: .claude/skills/ را به کنترلِ نسخه کامیت کن
Pluginها: یک پوشه‌ی skills/ در plugin خود بساز
مدیریت‌شده: در سطحِ کلِ سازمان از طریقِ تنظیماتِ مدیریت‌شده استقرار بده

تولیدِ خروجیِ بصری

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

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

پوشه‌ی Skill را بساز:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

این را در ~/.claude/skills/codebase-visualizer/SKILL.md ذخیره کن. description به Claude می‌گوید چه زمانی این Skill را فعال کند، و دستورالعمل‌ها به Claude می‌گویند اسکریپتِ بسته‌بندی‌شده را اجرا کند. مسیرِ اسکریپت از ${CLAUDE_SKILL_DIR} استفاده می‌کند تا فارغ از اینکه skill در سطحِ شخصی، پروژه یا plugin نصب شده باشد، درست resolve شود:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 $\{CLAUDE_SKILL_DIR\}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

این را در ~/.claude/skills/codebase-visualizer/scripts/visualize.py ذخیره کن. این اسکریپت یک درختِ پوشه را پویش می‌کند و یک فایلِ HTMLِ خوداتکا تولید می‌کند با:

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

اسکریپت به Python 3 نیاز دارد اما فقط از کتابخانه‌های داخلی استفاده می‌کند، پس بسته‌ای برای نصب وجود ندارد:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = \{'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'\}

def scan(path: Path, stats: dict) -> dict:
    result = \{"name": path.name, "children": [], "size": 0\}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append(\{"name": item.name, "size": size, "ext": ext\})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = \{
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    \}
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">\{ext\}</span>'
        f'<div class="bar" style="width:\{(size/total_size)*100\}%;background:\{colors.get(ext,"#6b7280")\}"></div>'
        f'<span class="bar-pct">\{(size/total_size)*100:.1f\}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"\{b\} B"
        if b < 1048576: return f"\{b/1024:.1f\} KB"
        return f"\{b/1048576:.1f\} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body \{\{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; \}\}
    .container \{\{ display: flex; height: 100vh; \}\}
    .sidebar \{\{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; \}\}
    .main \{\{ flex: 1; padding: 20px; overflow-y: auto; \}\}
    h1 \{\{ margin: 0 0 10px 0; font-size: 18px; \}\}
    h2 \{\{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; \}\}
    .stat \{\{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; \}\}
    .stat-value \{\{ font-weight: bold; \}\}
    .bar-row \{\{ display: flex; align-items: center; margin: 6px 0; \}\}
    .bar-label \{\{ width: 55px; font-size: 12px; color: #aaa; \}\}
    .bar \{\{ height: 18px; border-radius: 3px; \}\}
    .bar-pct \{\{ margin-left: 8px; font-size: 12px; color: #666; \}\}
    .tree \{\{ list-style: none; padding-left: 20px; \}\}
    details \{\{ cursor: pointer; \}\}
    summary \{\{ padding: 4px 8px; border-radius: 4px; \}\}
    summary:hover \{\{ background: #2d2d44; \}\}
    .folder \{\{ color: #ffd700; \}\}
    .file \{\{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; \}\}
    .file:hover \{\{ background: #2d2d44; \}\}
    .size \{\{ color: #888; margin-left: auto; font-size: 12px; \}\}
    .dot \{\{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; \}\}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">\{stats["files"]:,\}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">\{stats["dirs"]:,\}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">\{fmt(data["size"])\}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">\{len(stats["extensions"])\}</span></div>
      <h2>By file type</h2>
      \{lang_bars\}
    </div>
    <div class="main">
      <h1>📁 \{escape(data["name"])\}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
  <script>
    const data = \{json.dumps(data)\};
    const colors = \{json.dumps(colors)\};
    function fmt(b) \{\{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; \}\}
    function esc(s) \{\{ return s.replace(/[&<>"']/g, c => (\{\{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"\}\}[c])); \}\}
    function render(node, parent) \{\{
      if (node.children) \{\{
        const det = document.createElement('details');
        det.open = parent === document.getElementById('root');
        det.innerHTML = `<summary><span class="folder">📁 ${{esc(node.name)}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;
        const ul = document.createElement('ul'); ul.className = 'tree';
        node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
        node.children.forEach(c => render(c, ul));
        det.appendChild(ul);
        const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
      \}\} else \{\{
        const li = document.createElement('li'); li.className = 'file';
        li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{esc(node.name)}}<span class="size">${{fmt(node.size)}}</span>`;
        parent.appendChild(li);
      \}\}
    \}\}
    data.children.forEach(c => render(c, document.getElementById('root')));
  </script>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = \{"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()\}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated \{out.absolute()\}')
    webbrowser.open(f'file://\{out.absolute()\}')

برای تست، Claude Code را در هر پروژه‌ای باز کن و بپرس «Visualize this codebase.» Claude اسکریپت را اجرا می‌کند، codebase-map.html را تولید می‌کند و آن را در مرورگرت باز می‌کند.

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

عیب‌یابی

skill راه نمی‌افتد

اگر Claude آن‌طور که انتظار داری از skillت استفاده نمی‌کند:

بررسی کن که description کلیدواژه‌هایی را که کاربران طبیعتاً می‌گویند دربردارد
تأیید کن که skill در What skills are available? ظاهر می‌شود
درخواستت را طوری بازنویسی کن که بیشتر با description مطابقت کند
اگر skill قابلِ‌فراخوانی توسطِ کاربر است، مستقیماً با /skill-name فراخوانی‌اش کن

skill بیش از حد راه می‌افتد

اگر Claude وقتی نمی‌خواهی از skillت استفاده می‌کند:

description را خاص‌تر کن
اگر فقط فراخوانیِ دستی می‌خواهی، disable-model-invocation: true اضافه کن

توضیحاتِ skill کوتاه می‌شوند

descriptionهای skill در کانتکست بارگذاری می‌شوند تا Claude بداند چه چیزی در دسترس است. همه‌ی نام‌های skill همیشه گنجانده می‌شوند، اما اگر skillهای زیادی داری، توضیحات برای جا‌شدن در بودجه‌ی کاراکتری کوتاه می‌شوند، که می‌تواند کلیدواژه‌هایی را که Claude برای تطابق با درخواستت نیاز دارد حذف کند. بودجه با نرخِ ۱٪ از پنجره‌ی کانتکستِ مدل مقیاس می‌گیرد. وقتی سرریز شود، توضیحاتِ skillهایی که کمترین فراخوانی را داری اول حذف می‌شوند، پس skillهایی که واقعاً استفاده می‌کنی متنِ کاملشان را نگه می‌دارند. /doctor را اجرا کن تا ببینی آیا بودجه سرریز می‌کند و کدام skillها متأثرند.

برای بالابردنِ بودجه، تنظیمِ skillListingBudgetFraction را تنظیم کن (مثلاً 0.02 = ۲٪) یا متغیرِ محیطیِ SLASH_COMMAND_TOOL_CHAR_BUDGET را روی یک شمارِ کاراکترِ ثابت بگذار. برای آزادکردنِ بودجه برای skillهای دیگر، ورودی‌های کم‌اولویت را در skillOverrides روی "name-only" بگذار تا بدونِ توضیح فهرست شوند. همچنین می‌توانی متنِ description و when_to_use را در منبع کوتاه کنی: کاربردِ کلیدی را اول بگذار، چون متنِ ترکیب‌شده‌ی هر ورودی صرفِ‌نظر از بودجه در ۱٬۵۳۶ کاراکتر سقف می‌خورد. این سقف با maxSkillDescriptionChars قابلِ‌پیکربندی است.

منابعِ مرتبط

عیب‌یابیِ پیکربندی‌ات: تشخیصِ اینکه چرا یک skill ظاهر یا راه نمی‌افتد
ساب‌ایجنت‌ها: واگذاریِ وظایف به agentهای تخصصی
Pluginها: بسته‌بندی و توزیعِ skillها همراه با سایرِ افزونه‌ها
Hooks: خودکارسازیِ ورک‌فلوها پیرامونِ رویدادهای ابزار
حافظه: مدیریتِ فایل‌های CLAUDE.md برای کانتکستِ پایدار
دستورها: مرجع برای دستورهای داخلی و skillهای همراه
دسترسی‌ها: کنترلِ دسترسی به ابزار و skill