第 4 章 · 04 技能的最佳实践与共享

第 4 章 · 04 技能的最佳实践与共享

本节摘要:技能写好了怎么用对、怎么分享。最佳实践:description 要具体并含触发词(它是自动触发唯一依据)、一个技能解决一个问题、SKILL.md 控制在 500 行内超出拆支持文件、重复内容移到 scripts/references、副作用操作保持用户触发。故障排查:未触发→描述不够具体/目录不可见/被高优先级覆盖;触发太频繁→收紧描述加约束。共享:项目级放仓库共享、个人级放 ~/.claude/skills/(脚本记得 chmod +x)、可打包进插件分发。

学习目标

阅读完本节,你应当能够:

1. 背出技能设计的最佳实践四条。
2. 按清单排查"技能未触发"与"触发太频繁"两类问题。
3. 说出项目级/个人级技能的共享方式与脚本权限注意点。

一、最佳实践(原书整理)

1. description 要具体并含触发词——它决定自动触发率,写"审查代码安全、性能、质量与可维护性问题"就比"代码审查"触发率高得多;
2. 一个技能解决一个问题——多功能拆成多个技能;
3. SKILL.md 控制在 500 行内,超出拆分到支持文件(scripts/references);
4. 重复内容移到 scripts/references,正文只留流程骨架;
5. 安全:不硬编码密钥;副作用操作(部署/发布)保持用户触发(disable-model-invocation);自动触发技能设清晰边界(如 brand-voice 只作用于内容生成场景)。

二、故障排查

未触发:描述不够具体(缺触发词)→ 目录不可见(检查 .claude/skills/ 拼写)→ 被高优先级技能覆盖(同名冲突)。

触发太频繁:收紧 description、加适用约束(如"仅当…时")。

三、共享

• 项目级 .claude/skills/:随仓库版本管理,团队自动共享;
• 个人级 ~/.claude/skills/:全项目生效;复制脚本后记得 chmod +x ~/.claude/skills/*/scripts/*;
• 打包进插件:作为插件组件分发(第 8 章)。

小结

技能的最佳实践浓缩为三句话:描述决定触发、正文保持精简、支持文件承载细节。共享的路径有三条(仓库/用户目录/插件),按受众选择。下一章从"能力包"转向"专门助手":子代理 Subagents。