Appearance
Claude Code Skill 实践
Claude Code 这类编程 Agent 的价值不只在模型能力，也在仓库里是否有清晰的规则、工具和验证闭环。Skill 的作用是把这些规则写成可复用流程，让 Agent 在执行任务时更接近团队的工作方式。
强 Skill 的特征
强 Skill 通常不只写“建议怎么做”，而是写清：
- 什么时候触发。
- 必须先读哪些文件。
- 允许改哪些范围。
- 禁止哪些高风险行为。
- 修改后必须怎样验证。
- 环境不满足时如何说明。
这类规则能直接改变 Agent 的行为。只写“注意代码质量”“保持简洁”这类话，帮助有限。
三类最值得沉淀的规则
任务入口规则
入口规则告诉 Agent 开始前先确认什么。例如修改前端页面时，先找组件和样式来源；修改数据库逻辑时，先看迁移、实体和查询；修改文档时，先看导航和写作约束。
入口规则的目标是防止 Agent 一上来就改文件。
禁止行为规则
禁止行为要具体，并说明原因。例如：
- 不重写无关文件，避免扩大 diff。
- 不绕过失败测试，避免掩盖问题。
- 不把密钥写进示例，避免泄露。
- 不用未经验证的命令作为结论，避免假完成。
“禁止”不是限制能力，而是减少高频事故。
验收规则
验收规则说明任务怎样算完成。它可以是测试命令、构建命令、截图检查、链接检查、接口返回检查，也可以是必须在最终说明中报告哪些风险。
没有验收规则时，Agent 容易把“文件改了”当成“任务完成”。
Skill 与仓库文档的分工
| 内容 | 放哪里更合适 |
|---|---|
| 简短触发条件和流程 | Skill |
| 长背景、架构说明、领域知识 | docs 或 references |
| 常用命令和验证方式 | Skill 或 AGENTS.md |
| 大量示例和反例 | references |
| 安全红线和权限规则 | Skill + 项目规范 |
Skill 不应无限变长。它像索引和操作规程，长材料应按需展开。
编写流程
- 从真实返工中找规则，不要凭空设计。
- 把规则写成动作，不写抽象口号。
- 给每条关键规则配原因。
- 加入验证命令或检查方式。
- 跑一条真实任务，看 Agent 是否按预期执行。
- 把失败点继续写回 Skill。
Skill 的维护方式和测试用例很像：发现一次稳定缺陷，就补一条能防止复发的规则。
常见问题
Skill 太长
把背景、示例和长表格移到 references，只在主文件保留触发条件、步骤和验收。
Skill 触发太频繁
说明触发条件过宽。把“所有代码任务”改成更具体的场景，例如“修改 VitePress 文档时”“新增数据库迁移时”。
Agent 仍然不遵守
检查规则是否可执行。抽象建议通常遵守率低；明确动作、路径、命令和禁区更容易生效。
总结
Claude Code Skill 的实践重点是把团队经验变成可执行规程。好的 Skill 不追求长，而追求边界清楚、动作明确、验证可查。它让 Agent 从“随机发挥”变成“按项目流程协作”。