第 11 章 · Skills 技能系统
本章目标：理解 Claude Code 的 Skills 技能体系——SKILL.md 结构、发现机制与渐进披露设计，学会编写自定义技能并在团队内共享。
11.1 什么是 Skill
Skill 是一个自包含的能力包：为特定任务提供专用指令、脚本和参考文档。Claude Code 实现了开放的 Agent Skills 标准（agentskills.io），与 Pi 等工具兼容。
核心设计是渐进披露（progressive disclosure）：
text
启动时：扫描所有技能 → 只把「名称+描述」放进 system prompt
运行中：任务匹配某技能 → agent 用 read 工具加载完整 SKILL.md
执行时：按 SKILL.md 指令行事，用相对路径引用脚本/资源这样即使装了几十个技能，常驻上下文成本也只有几十行描述。
11.2 发现位置与加载规则
Claude Code 从以下位置加载技能：
text
全局: ~/.claude/skills/
项目: .claude/skills/ （仅受信任的项目）
插件: 通过 plugin 安装的 skills/
设置: settings.json 中 skills 数组显式指定
CLI: --skill <path>（可重复，即使 --no-skills 也生效）发现规则细节：
~/.claude/skills/中根级散放的.md文件也被识别为独立技能；- 所有位置中含
SKILL.md的目录会被递归扫描； - 项目
.claude/skills/仅在项目通过 Project Trust 信任后加载。
先审查再使用
技能可以指示模型执行任意操作，还可能携带模型会调用的可执行代码。安装社区技能前务必阅读其内容。
11.3 SKILL.md 结构
一个技能就是一个含 SKILL.md 的目录：
text
my-skill/
├── SKILL.md # 必需：frontmatter + 使用说明
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.jsonfrontmatter 字段：
| 字段 | 必需 | 说明 |
|---|---|---|
name | ✅ | ≤64 字符，小写字母/数字/连字符 |
description | ✅ | ≤1024 字符，决定 agent 何时加载 |
license | — | 许可证 |
compatibility | — | 环境要求（≤500 字符） |
metadata | — | 任意键值对 |
allowed-tools | — | 预批准工具列表（实验性） |
disable-model-invocation | — | 设 true 则只能 /skill:name 手动调用 |
校验硬规则：缺 description 的技能不加载；其余违规（名字超长等）只警告不阻断。
11.4 实战：写一个 code-review 技能
bash
mkdir -p ~/.claude/skills/code-review/references创建 ~/.claude/skills/code-review/SKILL.md：
markdown
---
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.使用方式：
bash
# 手动触发
/skill:code-review
# 带参数
/skill:code-review --staged
# 或直接说"帮我 review 这段改动"，agent 自动匹配 description 加载11.5 团队共享与生态
团队共享有三种方式：
- 项目级目录：把技能放在项目的
.claude/skills/中提交到 git，团队成员 clone 即可用； - Claude Code Plugin：打包为插件发布到官方 marketplace，自动更新但只读；
- skills.sh：用
npx skills add <repo>复制可编辑副本到本地。
社区推荐仓库：
- anthropics/skills——docx/pdf/pptx/xlsx 文档处理、Web 开发；
- mattpocock/skills——精选工程技能，小而可改；
- obra/superpowers——完整方法论，技能自动触发。
本章小结
- Skill = 含 SKILL.md 的目录，渐进披露让常驻上下文只有 name+description；
- 发现位置：
~/.claude/skills/（全局）、.claude/skills/（项目，需信任）、plugin、settings； - 缺
description是唯一"拒绝加载"级错误，其余仅警告； - 正文用相对路径引用 scripts/references/assets；
/skill:name手动触发。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. Claude Code 技能的"渐进披露"是指什么？
2. 哪种技能会被 Claude Code 直接拒绝加载？
3. 想让某个技能只能手动触发、不出现在系统提示词中，应该怎么配置？
4. SKILL.md 正文中引用技能目录下的 references/api.md，正确的写法是？
🛠️ 动手实践
- 创建一个
commit-helper技能：读取git log --oneline -10和 staged changes，生成符合 Conventional Commits 格式的 commit message。 - 给你的技能加上
disable-model-invocation: true，验证它从系统提示词消失、只能手动/skill:name调用。 - 把 anthropics/skills 克隆到本地，通过 settings 引入并测试其中一个文档处理技能。
完成后进入下一章：子代理与并行工作流。