创建、审查或修复 Claude 技能（SKILL.md）时…

在构建、审查、改进或分发 Claude 技能（SKILL.md），或排查其不触发、过度触发、指令不执行等问题时使用。

适用场景

解决思路

1. 确定技能类型：文档与资产创建（Document & Asset Creation）、工作流自动化（Workflow Automation）或 MCP 增强（MCP Enhancement），并据此选择技术重点。
2. 在写任何内容前定义 2–3 个具体用例，包含 Use Case 名称、Trigger 用户会说的短语、Steps 步骤、Result 预期结果。
3. 创建 kebab-case 的文件夹，例如 my-skill-name。
4. 在文件夹内创建大小写精确的 SKILL.md，不要创建 README.md。
5. 写入 YAML frontmatter，至少包含 name 和 description。
6. name 用 kebab-case，无空格、无大写，并与文件夹名一致。
7. description 同时写清 WHAT（做什么）和 WHEN（何时使用，具体触发短语），可选写 negative triggers（Do NOT use for...）。
8. description 控制在 1024 字符以内，不使用 XML 标签（< 或 >），必要时提及相关文件类型。
9. 可选 frontmatter 字段使用 license、compatibility、metadata.author、metadata.version、metadata.mcp-server。
10. frontmatter 安全限制：禁止 XML 尖括号；name 中禁止包含 “claude” 或 “anthropic”（保留字）。
11. 正文按推荐模板组织：## Instructions → 编号步骤 → ## Examples → ## Troubleshooting。
12. 把正文写得具体、可执行；例如给出要运行的命令和失败时的常见原因与修复。
13. 把详细文档移到 references/ 并用链接引用；保持 SKILL.md 在 5000 词以内。
14. 对关键校验优先提供 bundled script，而不是仅用自然语言说明，因为代码结果确定。
15. 在技能仓库中创建或修改技能后，更新 CLAUDE.md 的 Included Skills 表格，Trigger 列写一行触发说明。
16. 同时更新 README.md 的 Enthaltene Skills 表格，Beschreibung 列写德语一句话说明。
17. 保持 CLAUDE.md 和 README.md 的技能表同步，此步骤为强制步骤。
18. 处理本仓库技能时，加载 cc-best-practices 技能，确保上下文和会话管理符合项目标准。
19. 从仓库根目录运行 bash .claude/skills/skill-best-practices/scripts/validate-skills.sh 校验 YAML 和 skills CLI 兼容性。
20. 修复校验输出中的所有 FAIL 行后再继续测试或提交。
21. 如果 description 使用块标量（> 或 |），改成带引号的单行字符串。
22. 如果父级 mapping key 下的子键没有缩进，添加两个空格缩进。
23. 推送后运行 bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote，确认 npx skills add --list 能找到所有技能。
24. 运行 10–20 个测试查询，目标：相关查询约 90% 触发技能，不相关主题绝不触发。
25. 根据触发测试结果迭代 description 直到可靠触发。
26. 若 undertriggering（触发不足），往 description 增加更多触发短语。
27. 若 overtriggering（过度触发），增加负面触发条件并缩小范围。
28. 若指令被忽略，把关键步骤移到顶部并使用明确语言。
29. 构建新技能示例做法：先识别类别、定义用例、创建 linear-sprint-planner/SKILL.md、写含触发短语的 description、写含 Linear MCP 工具调用的分步说明、用 10 个触发短语测试并在不自动加载时调整 description。
30. 审查现有技能示例做法：读取 frontmatter 检查 name 是否 kebab-case、description 是否 WHAT+WHEN 且少于 1024 字符并含触发短语。
31. 审查正文：检查是否少于 5000 词、指令是否具体可执行、是否有 Troubleshooting、是否有 Examples。
32. 模拟触发：判断 description 是否会让 Claude 在正确查询下加载该技能。
33. 按 PASS / WARN / FAIL 逐项报告审查发现。
34. 排查不自动触发示例做法：读取 description 判断是否过于泛泛。
35. 检查是否缺少用户真实会说的触发短语。
36. 问 Claude：“When would you use the [skill name] skill?”，根据它复述的 description 找出缺口。
37. 重写 description 加入具体触发短语并重新测试。
38. 技能文件夹可包含：必需 SKILL.md；可选 scripts/ 可执行代码；可选 references/ 按需加载文档；可选 assets/ 输出模板、字体、图标。
39. 遵循 Progressive Disclosure 三层：YAML frontmatter 始终在系统提示中，说明何时加载；SKILL.md 正文在相关时加载完整指令；references/ 链接文件按需加载。
40. 遵循 Composability：技能要能与其他技能协同工作，不要假设排他性。
41. 遵循 Portability：让技能在 Claude.ai、Claude Code 和 API 中表现一致。
42. 规划时问自己：用户想完成什么？需要什么多步骤工作流？需要哪些内置或 MCP 工具？应嵌入哪些领域知识？
43. 文档与资产创建（Document & Asset Creation）类技能使用风格指南、模板、质量检查清单等技术。
44. 工作流自动化（Workflow Automation）类技能使用带验证关卡、迭代循环的分步流程。
45. MCP 增强（MCP Enhancement）类技能使用顺序 MCP 调用并嵌入领域专业知识。
46. 文件夹命名只用 kebab-case，不用空格、下划线或大写。
47. 技能文件名必须精确为 SKILL.md，区分大小写，不要使用变体。
48. 技能文件夹内不要放 README.md，把文档放在 SKILL.md 或 references/。
49. description 结构写成：[What it does] + [When to use it] + [Key capabilities]。
50. 写 description 时避免只有 “Helps with projects” 这类模糊表述。
51. 写 description 时避免只描述能力而缺失触发条件。
52. 写 description 时避免过于技术化、没有用户会说的触发词。
53. 正文说明尽量采用“运行 python scripts/validate.py --input {filename} 检查数据格式；若校验失败，常见问题包括缺少必填字段、日期格式无效等”的具体形式。
54. 在正文中记录常见错误的 Cause 和 Solution。
55. 引用捆绑资源时明确说明用途，例如在写查询前查阅 references/api-patterns.md 获取限流和分页模式。
56. 触发测试中应触发的示例包括：“Help me set up a new ProjectHub workspace”、“I need to create a project in ProjectHub”。
57. 触发测试中不应触发的示例包括：“What's the weather?”、“Help me write Python code”。
58. 功能测试检查：输出有效、API 调用成功、错误处理可用、边界情况覆盖。
59. 性能对比时比较启用技能与不启用技能时的 token 数、工具调用次数、来回消息数。
60. 对单个有挑战的任务反复迭代直到 Claude 成功，再把获胜方法抽取成技能。
61. 处理 “Could not find SKILL.md” 错误：把文件名精确改为 SKILL.md。
62. 处理 “Invalid frontmatter” 错误：添加 --- 分隔符并闭合引号。
63. 处理 “Invalid skill name” 错误：改用 kebab-case，去掉空格和大写。
64. 处理触发不足：在 description 中添加更具体的关键词和用户会说的短语。
65. 处理过度触发：加入负面触发条件并收窄范围，例如 “Advanced data analysis for CSV files... Do NOT use for simple data exploration.”
66. 处理指令太冗长：保持简洁、用项目符号、把细节移到 references/。
67. 处理关键指令被淹没：把关键指令放在顶部，使用 ## Critical 标题。
68. 处理语言含糊：明确写出 “CRITICAL: Before calling X, verify: ...”。
69. 处理模型偷懒：在用户提示词中加入 “Take your time, quality over speed, do not skip validation steps”，这比写在 SKILL.md 更有效。
70. 处理上下文过大或响应慢：把详细文档移到 references/。
71. 处理上下文过大或响应慢：保持 SKILL.md 少于 5000 词。
72. 处理上下文过大或响应慢：减少同时启用的技能数量，评估是否超过 20–50 个。
73. 需要工作流模式时，从五种模式中选择：Sequential orchestration、Multi-MCP coordination、Iterative refinement、Context-aware tool selection、Domain-specific intelligence。
74. 需要各工作流模式的详细示例和实现模板时，查阅 references/patterns.md。
75. 开始前检查：已识别 2–3 个具体用例。
76. 开始前检查：已确定使用内置工具还是 MCP 工具。
77. 开始前检查：已规划文件夹结构。
78. 开发中检查：文件夹为 kebab-case。
79. 开发中检查：SKILL.md 存在且拼写、大小写精确。
80. 开发中检查：YAML frontmatter 有 --- 分隔符。
81. 开发中检查：name 为 kebab-case，无空格、无大写。
82. 开发中检查：description 包含 WHAT 和 WHEN。
83. 开发中检查：任何位置都没有 XML 标签（< >）。
84. 开发中检查：指令清晰可执行。
85. 开发中检查：包含错误处理。
86. 开发中检查：提供 Examples。
87. 开发中检查：references 被清晰链接。
88. 仓库同步检查：已更新 CLAUDE.md 技能表。
89. 仓库同步检查：已更新 README.md 技能表。
90. 仓库同步检查：本次会话已加载 cc-best-practices 技能。
91. 仓库同步检查：已运行 validate-skills.sh，且没有 FAIL 行。
92. 推送后检查：已运行 validate-skills.sh --remote，且 npx skills 能找到所有技能。
93. 上传前检查：能在明显任务上触发。
94. 上传前检查：能在改写过的请求上触发。
95. 上传前检查：不会在不相关主题上触发。
96. 上传前检查：功能测试通过。
97. 上传后检查：在真实对话中测试。
98. 上传后检查：监控触发不足或过度触发。
99. 上传后检查：迭代 description 和 instructions。

适用边界 · 注意事项

• 不适用于通用 Claude Code 配置或 hook 设置。
• 当任务与创建、审查、改进 Claude 技能（SKILL.md）或排查其触发/分发问题无关时，不要使用。