Chapter 11 · Skills System

Chapter goals: Understand Claude Code's Skills system — SKILL.md structure, discovery mechanism, and progressive disclosure design; learn to写 custom skills and share them within a team.

11.1 What Is a Skill

A Skill is a self-contained capability pack: providing dedicated instructions, scripts, and reference docs for specific tasks. Claude Code implements the open Agent Skills standard (agentskills.io), compatible with Pi and other tools.

The core design is progressive disclosure:

At startup: scan all skills → inject only 「name + description」 into system prompt
At runtime: task matches a skill → agent loads the full SKILL.md via the read tool
At execution: follow SKILL.md instructions;引用 relative paths to scripts/resources

Even with dozens of skills installed, the常驻 context cost is only dozens of lines of description.

11.2 Discovery Locations and Loading Rules

Claude Code loads skills from the following locations:

Global:  ~/.claude/skills/
Project: .claude/skills/  (only for trusted projects)
Plugin:  skills/ installed via plugin
Settings: skills数组 in settings.json explicitly specified
CLI:   --skill <path> (works even with --no-skills)

Discovery rule details:

• Root-level散落 .md files in ~/.claude/skills/ are also识别 as独立 skills;
• Directories containing SKILL.md are recursively scanned at all locations;
• Project .claude/skills/ only loads after the project passes Project Trust.

Review Before Using

Skills can instruct the model to execute任意 operations and may carry executable code the model will call.务必 read the content before installing community skills.

11.3 SKILL.md Structure

A skill is a directory containing SKILL.md:

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # On-demand detailed docs
│   └── api-reference.md
└── assets/
    └── template.json

Frontmatter fields:

Field	Required	Description
name	✅	≤64 chars, lowercase/digits/hyphens
description	✅	≤1024 chars, determines when the agent loads it
license	—	License
compatibility	—	Environment requirements (≤500 chars)
metadata	—	arbitrary key-value pairs
allowed-tools	—	Pre-approved tool list (experimental)
disable-model-invocation	—	Set true tohide from system prompt; only /skill:name manually callable

Validation hard rules: skills missing description are not loaded;其余 violations (name too long, etc.) only warn, not block.

11.4 Walkthrough: Writing a code-review Skill

mkdir -p ~/.claude/skills/code-review/references

Create ~/.claude/skills/code-review/SKILL.md:

---
name: code-review
description: Review recent changes for bugs, security issues, and style violations. Use when the user asks to review code or check a pull request.
---

# Code Review

## Steps

1. Run `git diff HEAD~1` to see recent changes.
2. Read each modified file in full context.
3. Check for:
   - Logic errors and edge cases
   - Security vulnerabilities (injection, XSS, auth bypass)
   - Performance regressions
   - Style guide compliance
4. Report findings by severity: Critical / Warning / Suggestion.

## Rules

- Do not modify any files unless explicitly asked.
- Focus on the diff, not the entire codebase.
- Cite file paths and line numbers for each finding.

Usage:

# Manual trigger
/skill:code-review

# With parameters
/skill:code-review --staged

# Or just say "help me review these changes" — the agent自动 matches the description to load

11.5 Team Sharing and Ecosystem

Three ways to share skills within a team:

1. Project-level directory: place skills in the project's .claude/skills/ and commit to git; team members can use after cloning;
2. Claude Code Plugin: package as a plugin published to the官方 marketplace; auto-updates but read-only;
3. skills.sh: use npx skills add <repo> to复制 an editable copy locally.

Community recommended repos:

• anthropics/skills — docx/pdf/pptx/xlsx document processing, web development;
• mattpocock/skills —精选 engineering skills, small and改-able;
• obra/superpowers — complete methodology, skills auto-trigger.

Chapter Summary

• Skill = a directory containing SKILL.md; progressive disclosure keeps常驻 context to only name+description;
• Discovery locations: ~/.claude/skills/ (global), .claude/skills/ (project, needs trust), plugin, settings;
• Missing description is the only "refuse to load"级 error;其余仅 warning; -正文 references scripts/references/assets via相对 paths; /skill:name manual trigger.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does "progressive disclosure" mean for Claude Code skills?

2. Which skill gets直接拒绝 loaded by Claude Code?

3. To make a skill only manually triggerable and not appear in the system prompt, how should it be configured?

4. In the SKILL.md body, what is the correct way to reference references/api.md under the skill directory?

🛠️ Hands-on Practice

1. Create a commit-helper skill: read git log --oneline -10 and staged changes, generate a Conventional Commits-formatted commit message.
2. Add disable-model-invocation: true to your skill and verify it disappears from the system prompt, only callable via /skill:name.
3. Clone anthropics/skills locally, introduce it via settings, and test one of its document processing skills.

After completing, proceed to Chapter 12: Sub-agents and Parallel Workflows.