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

writing-skills

写作与研究

查看项目

更新于 10-15 17:15

技能介绍

用途

Writing Skills 用于在创建新技能、编辑已有技能，或在部署前验证技能是否有效时提供指导。它把测试驱动开发（TDD）应用到流程文档编写上：先写测试用例（用子代理运行压力场景），观察其失败（基线行为），再编写技能（文档），观察测试通过（代理遵守），最后重构（堵住漏洞）。

核心原则：如果没有先看到代理在没有该技能时失败，就无法确定技能教的是对的东西。

使用前提：必须先理解 superpowers:test-driven-development，该技能定义了 RED-GREEN-REFACTOR 基本循环，本技能把 TDD 适配到文档编写。

什么是技能

技能是关于经过验证的技术、模式或工具的参考指南，帮助未来的代理找到并应用有效方法。技能是可复用的技术、模式、工具、参考指南；技能不是关于你曾经如何解决某个问题的叙述。

TDD 映射

  • 测试用例 → 带子代理的压力场景
  • 生产代码 → 技能文档（SKILL.md）
  • 测试失败（RED）→ 代理在没有技能时违反规则（基线）
  • 测试通过（GREEN）→ 代理在技能存在时遵守
  • 重构 → 在保持遵守的同时堵住漏洞

先写测试：在编写技能之前运行基线场景。观察失败：记录代理使用的确切合理化说辞。最小代码：编写针对这些具体违规的技能。观察通过：验证代理现在遵守。重构循环：发现新的合理化说辞 → 堵住 → 重新验证。

何时创建技能

创建：技术对你来说并非直觉明显；你会跨项目再次参考；模式广泛适用（非项目特定）；他人会受益。

不要创建：一次性解决方案；别处已有良好文档的标准实践；项目特定约定（放入你的指令文件）；机械约束（如果可用正则/验证强制执行，就自动化它——把文档留给需要判断的地方）。

技能类型

  • 技术：有步骤可循的具体方法（condition-based-waiting、root-cause-tracing）
  • 模式：思考问题的方式（flatten-with-flags、test-invariants）
  • 参考：API 文档、语法指南、工具文档

目录结构

skills/ skill-name/ SKILL.md # 主参考（必需） supporting-file.* # 仅在需要时

扁平命名空间——所有技能在一个可搜索命名空间中。重参考（100+ 行）或可复用工具（脚本、实用程序、模板）单独成文件；原则与概念、代码模式（< 50 行）保持内联。

SKILL.md 结构

Frontmatter（YAML）：两个必填字段 name 和 description；总计最多 1024 字符；name 只用字母、数字和连字符；description 用第三人称，只描述何时使用（不描述做什么），以 "Use when..." 开头，包含具体症状、情况和上下文，绝不总结技能流程或工作流，尽量控制在 500 字符以内。

正文建议分段：Overview（1-2 句核心原则）、When to Use（症状与用例列表、何时不用）、Core Pattern（前后代码对比）、Quick Reference（表格或要点）、Implementation（简单模式内联代码，重参考或可复用工具链接到文件）、Common Mistakes、Real-World Impact（可选）。

技能发现优化（SDO）

未来代理需要能找到你的技能。

  1. 丰富的 description 字段：代理读取 description 来决定加载哪些技能。description 只描述触发条件，不总结流程。测试发现：当 description 总结工作流时，代理可能照 description 执行而不读完整技能内容。例如描述写 "code review between tasks" 导致代理只做一次审查，而技能流程图明确显示两次审查（规范符合性、代码质量）；改为只写触发条件后，代理正确读取流程图并遵循两阶段审查。

  2. 关键词覆盖：使用代理会搜索的词——错误消息、症状、同义词、工具（实际命令、库名、文件类型）。

  3. 描述性命名：主动语态、动词优先，如 creating-skills 而非 skill-creation，condition-based-waiting 而非 async-test-helpers。

  4. Token 效率：getting-started 和频繁引用的技能会加载进每次对话。目标词数：getting-started 工作流 <150 词；频繁加载技能总计 <200 词；其他技能 <500 词。技巧：把细节移到工具帮助（引用 --help）、使用交叉引用、压缩示例、消除冗余。可用 wc -w skills/path/SKILL.md 验证。

  5. 交叉引用其他技能：只用技能名并加明确要求标记，如 REQUIRED SUB-SKILL: Use superpowers:test-driven-development；REQUIRED BACKGROUND: You MUST understand superpowers:systematic-debugging。不要用 @ 链接，因为 @ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 上下文。

流程图使用

仅在以下情况使用流程图：非显而易见的决策点；可能过早停止的流程循环；"何时用 A 还是 B" 的决策。不要用于：参考材料（用表格、列表）、代码示例（用 Markdown 块）、线性指令（用编号列表）、无语义含义的标签。可用本目录的 render-graphs.js 把技能流程图渲染为 SVG：

node ./render-graphs.js ../some-skill # 每个图单独 node ./render-graphs.js ../some-skill --combine # 所有图合并为一个 SVG

代码示例

一个优秀示例胜过许多平庸示例。选择最相关的语言：测试技术 → TypeScript/JavaScript；系统调试 → Shell/Python；数据处理 → Python。好示例应完整可运行、注释解释为什么、来自真实场景、清晰展示模式、可直接改编。不要用 5+ 种语言实现、不要填空模板、不要牵强示例。

文件组织

  • 自包含技能：SKILL.md 全部内联
  • 带可复用工具：SKILL.md + example.ts 等可改编的工作辅助代码
  • 带重参考：SKILL.md + 大段 API 参考、XML 结构文档、scripts/ 可执行工具

在正文中通过解释器调用捆绑脚本（bash scripts/tool.sh、node scripts/tool.js），不要用裸路径：某些 harness 插件打包器会剥离可执行位，裸 scripts/tool.sh 会因 Permission denied 失败。

铁律（与 TDD 相同）

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

测试所有技能类型

  • 纪律强制型技能（规则/要求）：用学术问题、压力场景、多重压力组合测试；识别合理化说辞并添加明确反驳；成功标准是代理在最大压力下遵守规则。
  • 技术技能（操作指南）：用应用场景、变体场景、缺失信息测试；成功标准是代理成功把技术应用到新场景。
  • 模式技能（心智模型）：用识别场景、应用场景、反例测试；成功标准是代理正确识别何时/如何应用模式。
  • 参考技能（文档/API）：用检索场景、应用场景、缺口测试；成功标准是代理找到并正确应用参考信息。

跳过测试的常见合理化说辞

"技能显然清晰"——对你清晰 ≠ 对其他代理清晰，测试它。"只是参考"——参考可能有缺口、不清晰部分，测试检索。"测试是过度杀伤"——未测试的技能总有问题，15 分钟测试省下数小时。"有问题再测"——问题就是代理无法使用技能，部署前测试。"测试太繁琐"——比在生产中调试坏技能更不繁琐。"我有信心"——过度自信保证有问题，仍要测试。"学术审查足够"——阅读 ≠ 使用，测试应用场景。"没时间测试"——部署未测试技能会浪费更多时间修复。所有这些都意味着：部署前测试，没有例外。

让形式匹配失败

在编写指导之前，先对基线失败分类。让一种失败类型无懈可击的形式，在另一种失败类型上可能适得其反。

  • 基线失败：在压力下跳过/违反规则（明知更好却仍这样做）→ 正确形式：禁止 + 合理化说辞表 + 红旗；错误形式：软指导（"prefer..."、"consider..."）
  • 基线失败：遵守但输出形状错误（提示膨胀、埋没的验证）→ 资料在此处截断，后续内容暂未提供。

适用场景与限制

适用：创建新技能、编辑已有技能、部署前验证技能。限制：必须先理解 superpowers:test-driven-development；技能存放路径因运行时不同（Claude Code 为 ~/.claude/skills/，Codex、Copilot CLI、Gemini CLI 也识别 ~/.agents/skills/ 作为跨运行时别名）；官方最佳实践另见 anthropic-best-practices.md。