د — Course 4: Introduction to agent skills (شش lecture)

این course در ۳۰ دقیقه روی skill متمرکز می‌شود؛ از تعریف و ساخت تا config پیشرفته و troubleshooting.

Lecture 4.1 — skill ها چه هستند؟

عنوان اصلی: What are skills?

هدف یادگیری: تعریف skill به‌عنوان یک extension مبتنی بر SKILL.md که on-demand load می‌شود و از استاندارد باز Agent Skills پیروی می‌کند.

مفاهیم کلیدی: Agent Skills standard (agentskills.io), SKILL.md, on-demand loading, model-invoked or user-invoked, bundled skills (/simplify, /batch, /debug, /loop, /claude-api).

نقل قول رسمی: «Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit.»

دو تفاوت کلیدی با CLAUDE.md: 1. بدنه فقط در زمان استفاده load می‌شود — playbook طولانی تا قبل از invoke هزینه‌ی صفر دارد. 2. Claude خودش می‌تواند تصمیم به invoke بگیرد بر اساس فیلد description.

custom commands با skill ادغام شده‌اند. skill های bundled مثل /debug و /simplify با هر نصب می‌آیند.

اشتباهات رایج

• نگهداشتن یک playbook را در chat به‌صورت paste-and-repeat. اگر می‌بینید همان checklist چندباری paste می‌شود، آن را به skill تبدیل کنید.
• نگه‌داشتن procedure در CLAUDE.md. اگر بخشی از CLAUDE.md شما تبدیل به procedure شده، آن را به skill ببرید — CLAUDE.md برای fact است نه procedure.

Lecture 4.2 — ساخت اولین skill

عنوان اصلی: Creating your first skill

هدف یادگیری: نوشتن یک SKILL.md مینیمال، قرار دادن در محل صحیح و invoke.

مفاهیم کلیدی: mkdir ~/.claude/skills/<name>, frontmatter (name, description), markdown body, automatic delegation vs /skill-name, live change detection.

سه گام: 1. mkdir -p ~/.claude/skills/explain-code 2. نوشتن SKILL.md با frontmatter + body. 3. test یا با پرسش «How does this code work?» (auto) یا با /explain-code src/foo.ts (صریح).

مثال عملی

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. Start with an analogy
2. Draw an ASCII diagram
3. Walk through the code step-by-step
4. Highlight a gotcha

اشتباهات رایج

• live change detection روی edit داخل ~/.claude/skills/ کار می‌کند، اما ساختن یک پوشه‌ی top-level skills کاملاً جدید نیاز به restart دارد.

Lecture 4.3 — config و skill چندفایلی

عنوان اصلی: Configuration and multi-file skills

هدف یادگیری: استفاده از frontmatter کامل و فایل‌های جانبی برای skill در سطح production.

مفاهیم کلیدی: full frontmatter (name, description, when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, model, effort, context: fork, agent, hooks, paths, shell), $ARGUMENTS / $N / $name substitution, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}, !`shell` dynamic context, supporting files (reference.md, examples/, scripts/).

skill می‌تواند هر تعداد فایل داشته باشد. SKILL.md نقطه‌ی ورود است؛ از داخل آن به فایل‌های جانبی ارجاع دهید تا Claude بداند چه زمانی هر کدام را load کند. با context: fork + agent: Explore می‌توانید skill را در یک subagent مجزا اجرا کنید (بدنه‌ی skill prompt آن می‌شود). با !`gh pr diff` خروجی shell را به‌صورت زنده در prompt تزریق کنید. با paths: ["src/api/**/*.ts"] skill را فقط هنگام کار با فایل‌های تطابق‌یافته auto-load کنید.

Layout چندفایلی

my-skill/
├── SKILL.md           # required entrypoint
├── reference.md       # detailed API docs (loaded on demand)
├── examples/
│   └── sample.md
└── scripts/
    └── helper.py

مثال عملی — PR-summary skill

---
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.md بیش از ۵۰۰ خط. توصیه‌ی رسمی: «Keep SKILL.md under 500 lines» — مرجع تفصیلی را به فایل جانبی ببرید.

Lecture 4.4 — skill در برابر سایر feature های Claude Code (decision matrix)

عنوان اصلی: Skills vs other Claude Code features (the decision matrix)

هدف یادگیری: انتخاب primitive درست از میان skill، subagent، hook، MCP، CLAUDE.md و path-scoped rule.

مفاهیم کلیدی: advisory vs deterministic, in-context vs separate-context, on-demand vs always-loaded, internal vs external.

این جدول، decision matrix کانونیک است:

قاعده‌ی سرانگشتی (verbatim): «CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead. Use hooks for actions that must happen every time with zero exceptions.»

اشتباهات رایج

• استفاده از CLAUDE.md برای procedure ای که فقط برای ۱۰٪ task ها مرتبط است → context bloat.
• استفاده از skill برای چیزی که correctness به آن وابسته است (مثل block کردن rm -rf) → باید hook باشد.

Lecture 4.5 — اشتراک skill ها

عنوان اصلی: Sharing skills

هدف یادگیری: توزیع skill به همتیمی‌ها، org یا public.

مفاهیم کلیدی: project-level (.claude/skills/ در git)، user-level (~/.claude/skills/), plugin-bundled (<plugin>/skills/), managed (org-wide via managed settings), --add-dir discovery exception, plugin marketplace (/plugin).

چهار مسیر توزیع:

1. commit در .claude/skills/ تا همتیمی‌ها از طریق git pull کنند.
2. شخصی در ~/.claude/skills/ نگه دارید.
3. bundle در plugin و publish در plugin marketplace.
4. deploy از طریق managed settings برای org.

نکته‌ی ظریف: --add-dir معمولاً یک flag دسترسی به فایل است، اما .claude/skills/ از پوشه‌های اضافه‌شده هم load می‌شود — یک exception عمدی برای ممکن کردن اشتراک skill بین پروژه‌ها.

اشتباهات رایج

• skill های plugin از namespace plugin-name:skill-name استفاده می‌کنند و با skill های local تداخل ندارند. اگر هم .claude/skills/deploy/SKILL.md دارید و هم .claude/commands/deploy.md، skill اولویت دارد.

Lecture 4.6 — troubleshooting skill ها

عنوان اصلی: Troubleshooting skills

هدف یادگیری: تشخیص اینکه چرا یک skill trigger نمی‌شود، بیش‌از حد trigger می‌شود، یا description اش بریده می‌شود.

مفاهیم کلیدی: «What skills are available?»، description keyword tuning، disable-model-invocation، SLASH_COMMAND_TOOL_CHAR_BUDGET، per-entry cap ۱٬۵۳۶ کاراکتر، /permissions Skill(name) rules.

سه حالت شکست:

1. trigger نمی‌شود — keyword های description با عبارت طبیعی کاربر مطابقت ندارند. با پرسش «What skills are available?» بررسی کنید؛ description را تغییر دهید یا با /skill-name صریح invoke کنید.
2. بیش‌از حد trigger می‌شود — description را specific تر کنید، یا disable-model-invocation: true بگذارید برای حالت manual.
3. description بریده می‌شود — توضیحات skill ها budget مشترک دارند (۱٪ از context window، پیش‌فرض ~۸۰۰۰ کاراکتر). هر entry به‌علاوه سقف ۱٬۵۳۶ کاراکتر برای combined description + when_to_use دارد. use case کلیدی را اول بگذارید؛ در صورت نیاز با env var SLASH_COMMAND_TOOL_CHAR_BUDGET افزایش دهید.

block کردن همه‌ی skill ها با /permissions deny rule: Skill. بلاک یک: Skill(deploy *). مجاز کردن خاص: Skill(commit), Skill(review-pr *).

اشتباهات رایج

نقل قول مستقیم: «If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches.» اگر این رفتار را دیدید، یا description را قوی‌تر کنید یا برای enforcement deterministic از hook استفاده کنید.