Claude Code Skill 实践
Claude Code 通过 SKILL.md 描述一类任务的触发条件和操作规程。以 VitePress 文档修订为例,Skill 应告诉 Agent 去哪里读导航、何时补图、构建失败怎样追查、怎样确认手机页面可读,而不只是写“提高文档质量”。以下目录与字段按 2026-10-20 的 Claude Code 文档说明,其他宿主需核对各自支持。
最小目录与正文
项目 Skill 放在仓库内的 .claude/skills/<名称>/SKILL.md,个人 Skill 放在 ~/.claude/skills/<名称>/SKILL.md。前者可随仓库版本管理,后者作用于个人项目。不要把具体机器的绝对路径或凭据写进共享 Skill。
text
.claude/skills/docs-review/
SKILL.md
references/
diagram-checks.md下面是需要按实际项目调整的规程示例。文件名和命令对应 VitePress 项目,但参考文件必须真正提供,不能留下一个无法读取的路径。
markdown
---
name: docs-review
description: 新增或实质修改 VitePress 技术文章时使用,检查机制、图示、导航和页面验收;不用于只改错别字。
---
# 文档修订
先读取目标文章、专题入口和 .vitepress/sidebar.ts,明确各页职责。
围绕一个具体场景解释机制、失败路径与验证办法;长背景链接已有详细页。
涉及状态、时序或数据流时,读取 references/diagram-checks.md,核对图与正文一致。
修改后运行 npm run docs:build;构建失败要定位到文件,区分新问题与已有问题。
逐页检查桌面、手机、浅深色和图片放大,不把构建成功当作视觉验收。
工具或环境不可用时记录具体缺口,不宣称该项已验证;保留已完成的文件改动。名称和描述帮助宿主发现 Skill,正文在调用时进入上下文,长资料按引用读取。描述过宽会误触发,描述只列技术关键词又可能漏掉真实任务。既测试“补一篇协议机制文章”,也测试“只修一个错字”,观察触发是否符合范围。
强 Skill 的特征
强 Skill 通常不只写“建议怎么做”,而是写清:
- 什么时候触发。
- 必须先读哪些文件。
- 允许改哪些范围。
- 禁止哪些高风险行为。
- 修改后必须怎样验证。
- 环境不满足时如何说明。
这类规则能直接改变 Agent 的行为。只写“注意代码质量”“保持简洁”这类话,帮助有限。
三类最值得沉淀的规则
任务入口规则
入口规则告诉 Agent 开始前先确认什么。例如修改前端页面时,先找组件和样式来源;修改数据库逻辑时,先看迁移、实体和查询;修改文档时,先看导航和写作约束。
入口规则的目标是防止 Agent 一上来就改文件。
禁止行为规则
禁止行为要具体,并说明原因。例如:
- 不重写无关文件,避免扩大 diff。
- 不绕过失败测试,避免掩盖问题。
- 不把密钥写进示例,避免泄露。
- 不用未经验证的命令作为结论,避免假完成。
“禁止”不是限制能力,而是减少高频事故。
验收规则
验收规则说明任务怎样算完成。它可以是测试命令、构建命令、截图检查、链接检查、接口返回检查,也可以是必须在最终说明中报告哪些风险。
没有验收规则时,Agent 容易把“文件改了”当成“任务完成”。
Skill 与仓库文档的分工
| 内容 | 放哪里更合适 |
|---|---|
| 简短触发条件和流程 | Skill |
| 长背景、架构说明、领域知识 | docs 或 references |
| 常用命令和验证方式 | Skill 或 AGENTS.md |
| 大量示例和反例 | references |
| 安全红线和权限规则 | Skill + 项目规范 |
Skill 不应无限变长。它像索引和操作规程,长材料应按需展开。
编写流程
- 从真实返工中找规则,不要凭空设计。
- 把规则写成动作,不写抽象口号。
- 给每条关键规则配原因。
- 加入验证命令或检查方式。
- 跑一条真实任务,看 Agent 是否按预期执行。
- 把失败点继续写回 Skill。
Skill 的维护方式和回归用例相似:发现稳定缺陷后,把原因转成可执行检查,再用原失败任务验证。规则变多不等于质量提高;若工具路径或构建命令已变,应修正入口,而不是继续叠加“再次检查”。
调用控制与权限
Claude Code 默认允许用户和模型调用 Skill。disable-model-invocation: true 用于仅由用户主动调用的流程,例如按指定时机发布;user-invocable: false 用于不作为用户命令入口的背景知识。这些是 Claude Code 的扩展字段,不能假设其他 Agent 会以相同方式处理。
allowed-tools 会影响 Skill 调用时的工具许可,应逐项审查范围;它不是操作系统沙箱。Skill 中“先确认再发布”也不能替代执行端的环境权限和正式授权。附带脚本、动态上下文命令可能真实读取文件或访问外部服务,导入前需要一并检查。手动调用 Skill 不表示它里面任意新增的外部动作都已被业务授权。
不要用 .claude/skills/ 替代项目的长期事实说明。项目固定目录、构建入口放在仓库规范中,特定任务的多步规程放在 Skill,长示例放在 references;一个规则保留清楚的维护位置,避免三处抄写不同命令。
常见问题
Skill 太长
把背景、示例和长表格移到 references,只在主文件保留触发条件、步骤和验收。
Skill 触发太频繁
说明触发条件过宽。把“所有代码任务”改成更具体的场景,例如“修改 VitePress 文档时”“新增数据库迁移时”。
Agent 仍然不遵守
先检查本次是否实际调用、加载了哪个同名版本,以及正文是否被正确读取,再检查规则是否可执行。工具被禁用、参考文件缺失和上下文容量也会造成遗漏,不能把所有问题归为模型不听话。用当前任务的操作证据判断执行情况,而非只看最终回复是否声称遵守。
总结
一个可维护的 Skill 应能回答:是否触发了正确任务、读取了实际项目入口、执行了约定检查、在失败时停止了不合适的后续动作。保存版本和代表任务结果,宿主升级或规程修改后重新验证,才能判断它是否持续减少返工。
