>_ Claude Code 手册

Appearance

14 · 自定义 Skill ​

📚 系列导航：上一篇 13 Subagent 教你派分身干脏活。这一篇封装另一项能力——把反复粘贴的步骤打包成 Skill，让 Claude 该用时自动调出来。

01 Skill 是什么 ​

一个 Skill 就是一个叫 SKILL.md 的说明文件，外加可选的配套文件，打包成一身「专项本事」。

text
my-skill/
├── SKILL.md           # 主说明（必需）
├── template.md        # 让 Claude 填的模板
├── examples/
│   └── sample.md      # 示例输出
└── scripts/
    └── validate.sh    # 可执行的脚本

SKILL.md 分两部分——YAML frontmatter 管配置，markdown 正文管说明：

yaml
---
description: 总结未提交的改动并标出风险。当用户问改了啥、想要提交信息时使用。
---
## 当前改动
!`git diff HEAD`
## 说明
把上面的改动用两三个要点概括，再列出你注意到的风险。

TIP

!git diff HEAD`` 是动态上下文注入——Claude Code 先跑这条命令，把输出替换到这一行，Claude 拿到的是已填好的真实 diff，不是空指令。

02 核心命门：渐进式披露 ​

平时： Claude 只看到每个 Skill 的 description（一行菜名）。 相关时： 你的话对上了某个 description，完整正文才被加载（翻出菜谱）。

NOTE

官方规则：在常规会话中，skill 描述被加载到上下文中，以便 Claude 知道什么可用，但完整 skill 内容仅在调用时加载。

所以你可以放心往 Skill 正文里写长篇参考资料——用到之前几乎不花成本。但展开后正文会全程驻留会话，所以 SKILL.md 控制在 500 行以内，长参考拆到 references/ 按需加载。

03 Skill、slash 命令、Subagent 的区别 ​

维度slash 命令SkillSubagent
谁能发起只有你（打 /）你 + Claude 都能主对话委派
跑在哪个上下文当前对话当前对话（默认）独立子上下文
平时占不占上下文—只占一句 description不占
能带配套文件吗不能能看定义

slash 命令本质是 Skill 的手动触发档。 怕 Skill 自动乱动，加 disable-model-invocation: true 锁成纯手动。

04 description：触发命门 ​

好的 description = 干什么 + 什么时候用（含用户会说的原话关键词）。

❌ 废描述✅ 好描述
Commit message helper把暂存改动总结成规范的 commit message。当用户说「帮我提交」「写个 commit」「生成提交信息」时使用
只说了「是什么」既说干什么，又说什么时候用

TIP

description 要写得略微主动——把「即使用户没明说，也该出场」的场景显式写进去。比如「……只要用户提到仪表盘、数据可视化，哪怕没明说要『仪表盘』，都该用这个 skill」。

05 skill-creator：造 Skill 的 Skill ​

skill-creator 引导你走完一整条流水线：

  1. 想清楚要干啥：先跟你聊明白这 skill 做什么
  2. 写初稿：填好 name、description 和正文
  3. 建测试用例：写 2-3 个真实用户会说的话
  4. 跑一遍 + 评估：看输出对不对、触发是否准确
  5. 照反馈改：改完再跑，直到满意
  6. 优化描述：专门优化触发准确率
  7. 打包：可分发

NOTE

手写只做了第 2 步，skill-creator 把后面那几步补全了。最值钱的是「跑测试看触发」和「照反馈改」这个循环。

06 存放与触发 ​

存放位置：

  • ~/.claude/skills/<skill-name>/SKILL.md → 你的所有项目
  • .claude/skills/<skill-name>/SKILL.md → 仅当前项目，进 git 团队共享

触发方式：

  • 自动触发：说人话，Claude 比对 description 自动匹配
  • 直接点名：/skill-name 或 自然语言说 skill 名字

查当前可用：

text
现在有哪些 Skill 可用？

07 动手：用 skill-creator 造一个最小 Skill ​

bash
claude
text
用 skill-creator 帮我做一个 skill。
功能：把当前 git 仓库里未提交的改动总结成 2-3 条要点。
触发场景：当我问「我改了啥」「总结一下我的改动」的时候。
名字就叫 summarize-changes。

确认 description 里有触发词后，让它存到个人目录。造一个改动验证：

bash
echo "// test" >> README.md
text
我改了啥？

预期：Claude 自动调起 summarize-changes，吐出改动要点。

08 小结 ​

知识点一句话
Skill 是什么SKILL.md + 配套文件，一身专项本事
渐进式披露平时只露一句 description，用到才展开全文
description干什么 + 什么时候用（含用户原话），要主动
触发方式自动匹配或 /名字 点名
skill-creator造 skill 的 skill，补全手写跳过的验证环节
存放个人级 ~/.claude/skills/，项目级 .claude/skills/

NOTE

下一篇：15 Memory：跨会话记忆：把 Claude 学到的经验留下来，下次开工自动想起。

Claude Code 实战手册

All rights reserved.