writing-skills

name	writing-skills
description	在创建新技能、修改已有技能或发布前验证技能有效性时使用。

编写技能

概览

将 TDD 思想应用到技能文档编写：先验证问题，再写技能，再验证技能是否真正改变行为。

核心原则

如果没有观察到“无技能时会失败”的基线行为，就无法确认技能是否真正有效。

与 TDD 的映射

• 测试用例：压力场景/子代理任务。
• 生产代码：SKILL.md 与配套资源。
• RED：无技能时出现错误行为。
• GREEN：引入技能后行为符合预期。
• REFACTOR：堵漏洞并保持通过。

何时应写技能

• 可复用的方法/模式/工具。
• 跨项目可复现、可迁移经验。

不应写技能：

• 一次性问题。
• 项目私有约定（应放仓库约定文件）。
• 可用机械校验替代的人肉规范。

目录约定

• skills/<category>/<skill-name>/SKILL.md 必需；安装后 ~/.codex/skills/<skill-name>/ 应是指向该源码目录的符号链接。
• 仅在必要时增加辅助文件。
• 重资源（长参考、脚本、模板）拆分到独立文件。

SKILL.md 规范

• frontmatter 仅 name 与 description。
• description 只描述“何时使用”，不要描述执行流程。
• 命名、关键词与触发描述要有可搜索性。
• 追求 token 效率，避免冗长背景叙述。

迭代方法

1. 先跑基线场景（无技能）。
2. 写最小可行技能文本。
3. 再跑相同场景验证。
4. 记录新的绕过路径并补规则。
5. 重复至行为稳定。