skill-development

技能开发

使用此技能在当前本地环境中创建或修复 Claude 技能，而不是针对抽象的插件模板。

目标

打造的技能应：

• 易于触发；
• SKILL.md 层精简；
• 提及的 references/、examples/ 和 scripts/ 文件确实存在并提供支持；
• 不包含失效的本地引用。

核心规则

• 坚持一个技能 = 一项持久任务。
• 将 frontmatter 描述视为主要触发入口。
• 让 SKILL.md 聚焦于工作流和边界。
• 不要提及不存在的文件。
• 未经验证，不要沿用过时的名称、Agent 或对同级技能的引用。

默认工作流

1. 先检查当前环境

开始编写之前：

• 检查目标技能目录；
• 检查已经解决类似问题的相邻技能；
• 确认哪些 Agent、命令和同级技能实际存在；
• 添加新引用之前，先找出过时引用。

以本地清单为准。不要基于想象中的插件布局编写指导。

2. 明确技能契约

编辑前定义以下四项：

1. 技能的用途；
2. 触发条件；
3. 明确不处理的事项；
4. 实际需要哪些捆绑资源。

如果技能只需要简短的工作流，就保持简短。不要仅仅因为目录约定俗成，就创建 references/、examples/ 或 scripts/。

3. 编写或修复 frontmatter

frontmatter 应：

• 在 name 中使用实际的技能标识符；
• 使用第三人称的触发描述；
• 包含用户自然会说的具体短语；
• 简洁易读。

优先采用以下形式的描述：

---
name: skill-name
description: This skill should be used when the user asks to "...", "...", or needs help with ....
---

4. 保持主文件精简

优秀的 SKILL.md 通常应包含：

• 简短的目标部分；
• 角色边界；
• 默认工作流；
• 安全或质量规则；
• 简短的附加资源列表。

以下内容变长时，应移出主文件：

• 模板；
• 完整详尽的检查清单；
• 边缘情况目录；
• 示例输出；
• 长篇示例。

5. 只添加真实存在的捆绑资源

有目的地使用捆绑资源：

• references/ 用于可按需加载的详细指导；
• examples/ 用于真实示例输出或脚手架；
• scripts/ 用于确定性的辅助逻辑。

如果 SKILL.md 提及某项资源，该资源必须存在。 如果某项资源存在，但从未被引用或使用，就将其删除。

6. 完成前运行完整性检查

至少确认：

• frontmatter 可解析；
• 引用的本地文件均存在；
• 同级技能或 Agent 的引用真实有效；
• SKILL.md 没有塞入本应放在 references 中的过多内容；
• 技能目录中没有遗留临时日志、缓存或编辑器文件。

常见修复模式

技能过长时

• 在 SKILL.md 中保留触发条件和工作流；
• 将目录和深入细节移至 references/；
• 保留简短的阅读顺序，方便其他模型了解应先加载哪些内容。

技能过于单薄时

• 添加默认工作流；
• 至少添加一个具体示例或检查清单；
• 明确说明边界，避免技能沦为一句口号。

技能包含过时引用时

• 立即移除失效路径；
• 用当前本地名称替换历史名称；
• 根据实际目录重新检查相邻的 Agent、命令和技能。

推荐的输出形式

创建或修复技能时，建议最后说明：

• 更改了什么；
• 创建或更新了哪些文件；
• 运行了哪些完整性检查；
• 还有哪些事项需要人工跟进（如有）。

参考资料

仅加载所需内容：

• references/checklist.md - 完成技能编辑前使用的精简质量检查清单
• references/integrity-checks.md - 用于检查文件缺失、引用失效和内容偏移的具体本地检查
• references/skill-creator-original.md - 旧版背景参考资料；用于了解背景，而非作为当前权威来源