SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场writing-skills

writing-skills

写作与研究

查看项目

更新于 10-16 02:12

技能介绍

用途

Writing Skills 是一套用于编写和验证 AI 智能体技能（skill）的方法论。它的核心主张是：编写技能就是测试驱动开发（TDD）应用于流程文档。技能是经过验证的技术、模式或工具的参考指南，帮助未来的智能体实例找到并应用有效方法。技能不是关于某次如何解决问题的叙述。

主要能力

  • 将 TDD 的 RED-GREEN-REFACTOR 循环适配到技能文档编写：先写测试用例（带子智能体的压力场景），观察失败（基线行为），编写技能，观察测试通过（智能体遵守），再重构（关闭漏洞）。
  • 技能类型分类：参考（API、语法、命令选项、兼容性说明）、工作流（带门禁/清单的分步流程）、风格指南（命名、格式、语气、结构）、人格（交互风格、优先级、边界）、技术/模式（解决重复问题的方法或心智模型）。多类型技能可通过决策流程询问意图，选择合并或拆分。
  • 目录结构规范：技能目录只包含 SKILL.md，其余内容放入同级分类文件夹 references/、scripts/、assets/。
  • SKILL.md 结构规范：YAML frontmatter 仅支持 name 和 description 两个字段，总计不超过 1024 字符；name 只用字母、数字和连字符，且必须与文件夹名一致；description 用第三人称，格式为“做什么、何时使用、结果是什么”，尽量控制在 500 字符以内。正文包含 Overview、When to Use、Core Pattern、Quick Reference、Implementation、Common Mistakes、Real-World Impact 等章节。
  • Claude 搜索优化（CSO）：description 采用“做什么、何时使用、结果是什么”格式，用第三人称编写以便注入系统提示，使用具体触发条件、症状和结果，包含可搜索关键词（错误信息、症状、工具）。
  • 流程图使用规范：仅用于非显而易见的决策点、可能过早停止的流程循环、“何时用 A 还是 B”的决策；不用于参考资料、代码示例、线性指令。
  • 代码示例规范：一个优秀示例胜过多个平庸示例；选择最相关的语言（测试技术用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python）；示例应完整可运行、注释解释原因、来自真实场景、清晰展示模式、可直接改编。
  • 反模式：叙述性示例、多语言稀释、流程图中的代码、通用标签。
  • 防合理化：明确关闭每个漏洞、用基础原则回应“精神与字面”之争、从基线测试构建合理化表格、创建红旗清单用于自检、在 description 中更新违规症状。

使用方式

个人技能存放在智能体专属目录（$DOTFILE_REPO_ROOT/ai/files/skills），项目技能存放在 .agents/skills/。使用前必须理解 superpowers:test-driven-development 技能，它定义了基本的 RED-GREEN-REFACTOR 循环。官方指导要求从 writing-skills 技能加载 anthropic-best-practices 资源。

RED 阶段：用子智能体运行压力场景，不提供技能，记录确切行为、合理化理由以及触发违规的压力类型。GREEN 阶段：编写针对这些具体合理化理由的最小技能，用相同场景加上技能运行，智能体应遵守。REFACTOR 阶段：智能体发现新的合理化理由时，添加明确的反驳，重新测试直到无懈可击。

创建技能时使用 TodoWrite 为每个清单项创建待办。完成任何技能后必须停止并完成部署流程，不要批量创建多个技能而不逐个测试，不要在当前技能验证前进入下一个。

可视化流程图可使用 scripts/writing-skills/ 中的 render-graphs.js 渲染为 SVG：

./scripts/writing-skills/render-graphs.js ./skills/some-skill # 每个图单独输出 ./scripts/writing-skills/render-graphs.js ./skills/some-skill --combine # 所有图合并为一个 SVG

适用场景

适合创建技能的情况：技术对你来说不是直觉显而易见的、你会跨项目再次参考、模式广泛适用（非项目特定）、其他人会受益。不适合创建的情况：一次性解决方案、其他地方已有充分文档的标准实践、项目特定约定（应放入 CLAUDE.md）。

限制

铁律：没有失败的测试就不写技能。这适用于新技能和对现有技能的编辑。先写技能再测试？删除重来。未测试就编辑技能？同样违规。没有例外：不适用于“简单添加”、“只是加一节”、“文档更新”。不要把未测试的更改保留为“参考”，不要在运行测试时“改编”，删除就是删除。

测试所有技能类型：纪律执行类技能在压力下测试（时间、沉没成本、疲惫）；技术类技能测试应用场景和边缘情况；模式类技能测试识别和反例；参考类技能测试检索和正确应用。关键原则：部署前测试，没有例外。

部署未测试的技能等于部署未测试的代码。