Skills 系统:把再次输入的指令变成可加载的能力
原文:https://code.claude.com/docs/en/skills 官方定位:Extend Claude with skills — Create a
SKILL.mdfile with instructions, and Claude adds it to its toolkit. 遵循的标准:agentskills.io(开放标准,跨 AI 工具)— Claude Code 在标准之外做了三项扩展:disable-model-invocation、context: fork、动态 context 注入
🔥 影响力卡片
| 维度 | 数据 |
|---|---|
| 跨 AI 工具兼容 | 走 agentskills.io 开放标准 — 同一个 SKILL.md 理论上能在 Cursor / Gemini CLI / Copilot CLI / Claude Code 通用 |
| 本机你已经在用的 skills | ~30 个(superpowers 套件 14 个:brainstorming, writing-skills, executing-plans, subagent-driven-development, dispatching-parallel-agents, test-driven-development, systematic-debugging, verification-before-completion, using-git-worktrees, using-superpowers, requesting-code-review, receiving-code-review, finishing-a-development-branch, writing-plans · understand-anything 套件 8 个 · ~/.claude/skills/ 个人 3 个(content-curation / content-curation-auto / gstack-game)· 系统 bundled / 其他 plugin ~10 个:loop / schedule / claude-api / init / review / security-review / simplify / fewer-permission-prompts / update-config / keybindings-help) |
| 内置 bundled skills(每个 session 自动有) | /simplify, /batch, /debug, /loop, /claude-api, /init, /review, /security-review |
| Custom commands 现状 | 已合并到 skills(.claude/commands/*.md 还能用,但 skills 是新路径) |
| 你已经写过 skill 的痕迹 | ~/.claude/skills/content-curation/SKILL.md + ~/.claude/skills/content-curation-auto/SKILL.md — 由我们自己沉淀出来 |
🎯 为什么必读
1. Skill 是 Claude Code 里”边际成本最低”的扩展。
不像 plugin / MCP / Hook 那么重 — 一个 skill = 一个 SKILL.md 文件 + 几行 YAML frontmatter,5 分钟就能造一个,本机即时生效(live change detection 直接监听目录)。
2. 它解决的痛点是真痛点
“Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.”
回想你 CLAUDE.md 里有多少行是”流程类”:
- 启动检查 (
grep context/) - 隐私红线
- 自治档位判断
- 想法 → 拓展 → 竞品 → 定位 → 技术选型 → 0-1 上线
后面那个执行链 应该是个 skill,不是 CLAUDE.md 里的静态文字 — 因为它是个流程,该按需加载。
3. 它跟 CLAUDE.md 的根本区别:加载时机不同
- CLAUDE.md:每次 session 启动都加载,全程占 context
- Skill body:只有被调用时才加载,但调用后会一直留在 context 直到 session 结束(关键!)
所以:短小高频的事实 → CLAUDE.md;长冗低频的流程 → skill。
一句话总结
Skill = 一个文件夹 +
SKILL.md(YAML frontmatter 描述何时触发 + 正文写指令)。Claude 看 description 决定要不要自动加载;你也可以/skill-name主动调用。一旦加载就常驻 context,所以正文要短而精**。**
💎 金句墙
★ “Keep
SKILL.mdunder 500 lines. Move detailed reference material to separate files.” “SKILL.md 保持 500 行以下。详细参考资料放到独立文件,按需加载。” —— 🟢 这是 progressive disclosure 的核心 — SKILL.md 是入口,supporting files 是延伸
★ “Once a skill loads, its content stays in context across turns, so every line is a recurring token cost.” “一旦 skill 被加载,内容会跨 turn 留在 context 里 — 每一行都是循环 token 成本。” —— 🟢 决定了你不能把 skill 写得像 README — 每行都要”必要而充分”
★ “State what to do rather than narrating how or why.” “写’做什么’,不要写’怎么做’和’为什么这样做’。” —— 🟢 LLM 不需要 onboarding 解释,需要清晰指令 — 写 skill 时跟写给新员工的 SOP 完全不同
★ “After compaction, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each.” “压缩后,Claude Code 会把每个最近调用过的 skill 重新挂回(只保第 5000 tokens),最近用的优先。” —— 🟢 25k 总预算限制 — 调用太多 skill 会让早的 skill 在压缩时被丢
📋 核心精读
1. Skill 的最小例子
~/.claude/skills/hello/
└── SKILL.md---
description: Greet the user named "$ARGUMENTS" warmly
---
# Hello Skill
Greet "$ARGUMENTS" by name and ask how you can help today.测试:claude → /hello Alex → Claude 用名字打招呼。
完事。5 行 YAML + 几行 markdown = 一个 skill。
2. 4 个存放位置 — 决定 skill 的可见范围
| 位置 | 路径 | 适用范围 |
|---|---|---|
| 企业 | managed settings | 整个组织 |
| 个人 | ~/.claude/skills/<name>/SKILL.md | 所有你的项目 |
| 项目 | .claude/skills/<name>/SKILL.md | 单个项目 |
| Plugin | <plugin>/skills/<name>/SKILL.md | plugin 装在哪就在哪 |
优先级:enterprise > personal > project。Plugin 用 plugin-name:skill-name 命名空间,不冲突。
.claude/commands/<name>.md 也算 skill(平等对待),但 skill 比 command 优先级高。
3. 14 个 frontmatter 字段(精选最常用的 6 个)
| 字段 | 用途 | 实例 |
|---|---|---|
description ⭐ | 必写 — Claude 看这个决定何时自动调用 | description: Reviews code for security issues. Use when reviewing PRs or analyzing auth flows. |
disable-model-invocation | true = Claude 不会自动调,只能你 /name 触发 | 适用于 /deploy、/commit 这种有副作用的 |
user-invocable | false = Claude 能自动调,你的 / 菜单看不见 | 适用于”背景知识”型 skill,如 legacy-system-context |
allowed-tools | 这个 skill active 时 Claude 不需要每次问允许的工具 | allowed-tools: Bash(git add *) Bash(git commit *) |
context: fork + agent: <type> | 在隔离 subagent 里跑这个 skill,不污染主 session | 适合”深度调研类” |
paths | glob 匹配 — Claude 只在改这些文件时自动加载这个 skill | paths: ["src/api/**/*.ts"] |
其他次要字段:name、when_to_use、argument-hint、arguments、model、effort、hooks、shell。
4. 动态 context 注入 — 真正强的功能
skill 内容里可以用 !`<shell-command>` 在加载时执行 shell,输出会替换占位符:
---
description: Summarizes uncommitted changes. Use when user asks what changed.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two-three bullet points. Flag risks like
missing error handling or hardcoded values.加载时 git diff HEAD 先跑,输出直接插进 skill 正文,然后整体作为一条 message 进 Claude。这意味着:
- skill 不再需要”教 Claude 怎么取数据” — 你直接预处理好喂进去
- 比”让 Claude 调用 Bash tool 取数据”省 1-2 个 turn
- 拼接的指令永远基于当前真实状态,不是过期记忆
多行版本:
## Environment
```!
node --version
npm --version
git status --short
```可用变量:
| 变量 | 含义 |
|---|---|
$ARGUMENTS | 所有传入参数 |
$ARGUMENTS[N] 或 $N | 第 N 个参数(0-indexed) |
$name(配合 arguments: [...]) | 命名参数 |
${CLAUDE_SESSION_ID} | 当前 session ID |
${CLAUDE_EFFORT} | 当前 effort 级别 |
${CLAUDE_SKILL_DIR} | skill 目录的绝对路径 — 必背,用来引用 supporting files |
5. Progressive disclosure — 大 skill 的正确做法
my-big-skill/
├── SKILL.md # 入口 ~200 行 — 必读
├── reference.md # API 详细参数 — 按需 Read
├── examples.md # 示例 — 按需 Read
└── scripts/
└── helper.py # 实际执行的脚本在 SKILL.md 里显式提示 Claude 这些文件存在:
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)这样:
- 主流程 token 成本低(SKILL.md 才 200 行)
- Claude 需要细节时自己 Read 加载
- supporting files 不占 context 直到真要看
6. context: fork — 隔离执行(高级用法)
---
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/research authentication-flow会:
- 开一个新的 subagent context(基于
Exploreagent 类型 — read-only,优化于代码探索) - SKILL.md 内容作为 subagent 的 prompt
- 干完后 Claude 把结果回总结到主 session
- 主 session 的 context 完全不被污染
适合场景:深度调研、扫描整个 codebase、做单一的封闭任务。不适合:那种纯”知识/约定”型 skill(没具体 task,fork 出去无意义)。
7. Skill 的生命周期 — 一旦加载就常驻
[turn 1] 调用 /my-skill → SKILL.md 被注入 context
[turn 2-N] 内容一直在 context 里
[compaction] 保第 5000 tokens(总预算 25k,从最近的开始挤老的)
[新 session] 重置这意味着:
- 不能为了”安全”在 skill 里写一堆 caveat — 每次都会重读 → 浪费 token
- 可以写 skill 来”改变 Claude 整个对话风格”(因为留着) — 比如
learning-output-style那种 - 不要在一个 session 里调 20 个 skill — 老的会在 compaction 后被挤掉
8. /skills 菜单 + skillOverrides — 临时关掉某 skill
> /skills
# 高亮 skill,按 Space 循环 4 个状态,Enter 保存到 .claude/settings.local.json四种状态:
| 状态 | Claude 能看到 | / 菜单显示 |
|---|---|---|
on(默认) | 名 + 描述 | 是 |
name-only | 只名 | 是 |
user-invocable-only | 不列 | 是(只你能调) |
off | 不列 | 否 |
实际用例:你装了 22 个 skill,某段时间只在做前端 → 把 understand-anything、security-review 临时设 name-only,腾 context 给 frontend-design。
9. 8 个 bundled skill 你应该知道
Claude Code 内置的 prompt-based 命令(每个 session 自动可用):
| 命令 | 干啥 |
|---|---|
/simplify | 找当前 diff 的可简化代码 |
/batch | 把多个相关任务批量给 Claude 处理 |
/debug | 启动结构化 debug 流程 |
/loop | 你正在用的!循环跑 prompt |
/claude-api | 涉及 Anthropic API 代码时的开发指引 |
/init | 给新 codebase 生成 CLAUDE.md |
/review | review 一个 PR |
/security-review | 安全审查当前分支改动 |
它们就是 skill — 不是硬编码命令。这意味着你可以覆盖它们(同名 skill,personal scope 优先级更高)。
10. 跟 plugin / subagent 的关系图
┌─────────────────┐
│ plugin (容器) │
│ skills/ │
│ agents/ │
│ hooks/ │
│ .mcp.json │
└────────┬────────┘
│
含 0-N 个 skill
│
┌────────────────┼────────────────┐
│ │ │
独立 skill skill + 隔离 skill 引用 subagent
(主 session 跑) (context: fork) (用 Read 加载 agent.md)
│ │ │
▼ ▼ ▼
最常见用法 深度调研 跟 Claude 协作复杂任务🟢 译者总评 — 给独立开发者的实战建议
1. 你已经在用很多 skills,但可能没意识到。
打开 /help 或在输入框输 /,你能看到几十个 skill 列表(superpowers / understand-anything 这类常用 plugin 一装就十几个,加上 bundled 和个人 skill)。它们决定了 Claude 给你的每一个回答的质量 —— 比如这次调研用 content-curation-auto 控节奏,前几篇文章受 writing-skills 的写作纪律影响。
2. 立即可以给自己写的两个 skill:
a. 新项目脚手架 skill(new-project)
---
description: Scaffold a new project under ~/code/ with my standard layout (README, docs/, src/, .gitignore, package.json)
disable-model-invocation: true
arguments: [project-name, project-type]
---
Create a new project at ~/code/$0:
1. mkdir + git init
2. Write README.md with sections: Problem, Tech, Run, Status
3. If $1 is "frontend": Vite + React + TS + Tailwind
If $1 is "node": Bun + TS strict mode
...
!`ls ~/code/`b. Deployment 检查 skill(deploy-check)
---
description: Pre-deployment checklist for my projects.
disable-model-invocation: true
allowed-tools: Bash(git *)
---
## Current state
- Branch: !`git branch --show-current`
- Uncommitted: !`git status --short`
- Last commit: !`git log -1 --pretty=oneline`
## Checklist
1. CI passing?
2. README up to date?
3. Env vars documented?
4. License set?
5. ...3. 警惕的反模式:
- ❌ skill 写得跟 README 一样长 — 每行都进 context,500 行已经太多
- ❌ skill 重复 CLAUDE.md 的内容 — CLAUDE.md 已经在 context 里了
- ❌ skill 当文档用 — 那是 supporting files 的事
- ❌ 20+ skill 同时活跃 — 占满 context budget,压缩时丢
- ❌
allowed-tools给太多 — skill 一加载就放权;在恶意 skill 里这是后门
4. Skill 系统是 Anthropic 在押注”AI 工作流的 npm”
agentskills.io 是个开放标准。Anthropic 在试图让 skill 成为跨 AI 工具的能力分发单位 — 你写一个 skill,理论上 Cursor / Gemini CLI / Copilot CLI 都能用。这个野心很大,而且如果成,Claude Code 就是事实上的”包管理”参考实现。
值得关注的下一波动作:
- skill 加 version 字段(目前是 plugin 携带版本,skill 单独还没)
- 公开的 skill registry(目前要走 plugin marketplace)
- 跨工具兼容性认证
🔗 延伸阅读
- 同系列:
04-plugins-marketplace.md(skill 的分发容器)、06-hooks.md(skill 配合 hook 做强制约束) - 官方:
/en/sub-agents—context: fork的另一边 - 官方:
/en/commands— 内置命令一览,bundled skill 用 Skill 标记 - 标准:agentskills.io — 开放标准本体
🔗 调研来源(可校验)
- 主原文:
https://code.claude.com/docs/en/skills - 本地自己写的 skill 通常放
~/.claude/skills/<skill-name>/SKILL.md - bundled skill 验证:在 Claude Code 输入框输入
/应能看到/simplify、/batch、/debug、/loop等 - 开放标准:agentskills.io(撰文时已注册,内容可能仍在迭代)