09｜Skills：把专业知识封装成按需能力

掌握 SKILL.md、渐进式披露、触发方式与目录结构。

自定义命令像餐厅备菜清单：把每次都相同的步骤固定下来，让注意力留给本次任务的差异。命令需要输入边界、失败提示和验证输出。

本课交付物

创建一个“发布前检查”命令，依次读取状态、运行测试、总结风险，但禁止自动推送。用干净与脏工作区各执行一次，检查提示是否明确。

---

概览

Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 SKILL.md、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。

主要好处

• 可复用
• 可渐进加载
• 可以把脚本、模板、说明放在一起
• 适合标准化流程

Skills 的工作方式：渐进式披露

Skills 不会一次性把所有内容都塞进上下文，而是按需加载。

三层加载

1. 只看描述：先判断这个 skill 是否相关
2. 加载 SKILL.md：读取核心说明
3. 按需加载支持文件：脚本、模板、参考资料

Skill 加载流程

1. Claude 扫描技能目录
2. 根据描述判断是否匹配当前任务
3. 读取 SKILL.md
4. 如有需要，再加载脚本和辅助文件

Skill 类型与位置

Skills 可以放在：

• 项目目录下的 .claude/skills/
• 用户目录下的 ~/.claude/skills/

自动发现

只要目录结构正确，Claude 就会自动发现这些 Skills。

创建自定义 Skills

基本目录结构

my-skill/
└── SKILL.md

SKILL.md 格式

# Your Skill Name

## Instructions

## Examples

必填字段

• name
• description

可选 frontmatter 字段

• argument-hint
• allowed-tools
• model
• disable-model-invocation
• user-invocable
• context
• agent
• hooks

Skill 内容类型

参考内容

适合放规则、标准、文档片段和示例。

任务内容

适合放具体步骤、执行流程和结果格式要求。

控制 Skill 的调用

你可以通过 disable-model-invocation、user-invocable 和工具白名单来控制 Claude 是否能自动调用这个 skill。

字符串替换

Skills 支持 $ARGUMENTS、$0、$1 等参数替换。

动态上下文注入

你可以在 prompt 里插入 shell 命令结果：

- 当前 git 状态：!`git status`
- 当前 diff：!`git diff HEAD`
- 当前分支：!`git branch --show-current`

在 subagent 中运行 Skills

某些 skill 适合在隔离上下文中运行，这样可以降低对主会话的影响。

实战示例

示例 1：代码审查 Skill

一个典型的审查 skill 会包含：

• 审查模板
• 风险等级
• 输出格式
• 需要关注的维度

示例 2：代码库可视化 Skill

可以把代码库结构、依赖关系和模块边界总结给 Claude，便于快速理解。

示例 3：部署 Skill（只允许用户触发）

适合带副作用的操作，比如生产环境部署。通常会配合 disable-model-invocation: true。

示例 4：品牌语气 Skill

用于检查输出是否符合品牌语气、语调和表达风格。

示例 5：CLAUDE.md 生成 Skill

可以从项目文档中生成或补充 CLAUDE.md。

示例 6：带脚本的重构 Skill

常见组合是：

• SKILL.md
• scripts/
• templates/
• references/

管理 Skills

查看可用 Skills

/skills

测试一个 Skill

把它放到测试目录或者临时项目里，然后通过相应命令触发。

更新 Skill

修改 SKILL.md 或支持文件后，重新打开会话或重新加载即可。

限制 Claude 对 Skill 的访问

你可以通过权限配置，只允许 Claude 访问某些 skill。

最佳实践

1. 描述要具体

让 description 明确说明这个 skill 在什么时候触发。

2. 保持聚焦

一个 skill 解决一个问题，不要什么都塞进去。

3. 包含触发词

在描述里加入相关关键词，帮助 Claude 更准确地选择它。

4. SKILL.md 不要太长

尽量控制在 500 行以内，超过就拆分支持文件。

5. 引用支持文件

把重复内容移到脚本或参考文件中，主文件只保留核心说明。

故障排查

快速参考

• 检查目录结构是否正确
• 检查 SKILL.md frontmatter 是否有效
• 检查 skill 名称是否和调用名一致

Skill 没有触发

• 检查描述是否足够具体
• 检查目录是否在 Claude 可见范围内
• 检查是否被更高优先级的 skill 覆盖

Skill 触发太频繁

• 收紧描述
• 增加约束条件
• 用更具体的触发词

Claude 看不到全部 Skills

• 检查路径
• 检查权限
• 重新加载会话

安全注意事项

• 不要在 skill 中硬编码密钥
• 对副作用操作保持用户触发
• 给自动触发的 skill 设置清晰边界

Skills vs 其他功能

功能	触发方式	适合场景
Skills	自动/半自动	复用能力、流程标准化
Slash Commands	手动	快捷命令
Subagents	自动委派	隔离任务
Hooks	事件触发	自动化和验证

内置 Skills

Claude Code 自带一些 Skills，例如批处理、调试、简化和 Claude API 相关内容。

共享 Skills

项目 Skills（团队共享）

把 skill 放在项目目录里，团队成员都能用。

个人 Skills

# 复制到个人目录
mkdir -p ~/.claude/skills

# 让脚本可执行
chmod +x ~/.claude/skills/*/scripts/*

Plugin 分发

你也可以把 Skills 作为插件的一部分发布出去。

继续深入

如果你要管理一整套 Skills，可以再做一个 skill collection 或 skill manager，用来统一发现、更新和分发。

更多资源

• 根目录中文指南
• Slash Commands 中文参考
• Memory 中文指南
• Subagents 中文参考

---

本站实战工作台

自定义命令适合“稳定重复”，不适合“替你思考”

团队每次发布前都会查看状态、跑测试、检查迁移并总结风险，这类顺序稳定的流程适合封装。需求取舍、删除生产数据、是否忽略失败则不该藏进一个按钮。命令降低重复劳动，也可能把坏习惯高速复制。

先写输入与禁止项

设计一个 preflight 命令，输入是可选的目标模块，输出是结构化检查报告。明确禁止自动提交、推送或部署。若工作区不干净，命令应报告而不是偷偷清理。

目标：为当前分支生成发布前检查报告。
步骤：
1. 读取分支与工作区状态；
2. 根据变更文件选择定向测试；
3. 运行项目规定的构建；
4. 检查迁移状态但不应用迁移；
5. 输出通过、失败、未验证和风险。
禁止：修改文件、提交、推送、部署。

让失败成为一等输出

命令不能在测试失败后继续写“可以发布”。每个步骤应保存退出状态，并把“未运行”与“通过”区分开。网络不可用时，报告受阻原因和可重试命令，不要把缓存结果当成新证据。

用两种工作区测试

先在干净分支执行，确认报告列出实际命令和结果。再修改一个未提交文件执行，期望它显著提示脏工作区，但仍可做只读检查。最后制造一个失败测试，确认总状态为阻止发布。

检查命令是否依赖个人绝对路径、特定 shell 或未声明工具。团队命令需要在最小支持环境中运行；环境差异应明确检测并给出安装说明。

防止提示注入和参数失控

如果命令接受文件名或用户文本，不要把它直接拼接进 shell。参数要引用、校验允许值，并限制工作目录。Agent 生成的命令描述也不能凌驾于项目安全规则。

版本化与退出

自定义命令与代码一起审查。命令变化会影响所有使用者，应有变更记录和回退提交。删除命令时说明替代流程，避免团队继续依赖本地旧副本。

本课验收

preflight 在干净、脏、失败三种状态给出不同且准确的结论；没有修改或外部动作；输出能让审查者重跑每项检查。可靠按钮不是把风险藏起来，而是把稳定步骤和失败证据标准化。

最后让一位没有参与编写的同伴只看命令帮助与报告执行一次。如果他必须阅读实现才能知道参数，说明接口仍不够清楚；如果他能解释为何被阻止、怎样重跑和哪些项目尚未验证，命令才真正具备团队复用价值。