从提示词到可维护 Skill：一套三阶段迭代方法

当同一类提示词被复制第三次时，它通常已经不该继续留在聊天框里了。Skill 的价值不是“多写一份 Prompt”，而是把触发条件、执行步骤、质量标准和参考资料做成可维护的能力包。

01. 先确认它值得被复用

适合做成 Skill 的任务通常同时具备三点：会重复发生、存在稳定步骤、结果可以检查。例如代码审查、周报整理、文档发布和数据清洗。一次性的创意讨论不必急着固化，否则维护成本会超过收益。

Skill、命令和项目规则也不是一回事：Skill 提供可按需加载的完整工作方法；命令是一个明确入口；AGENTS.md 一类规则文件则约束整个仓库。前者回答“这类事怎么做”，后两者分别回答“如何启动”和“始终要遵守什么”。

02. V1：先做最小可用版本

第一版只保留角色、流程和输出格式。目录名使用小写连字符，并与 frontmatter 中的 name 保持一致。以 OpenCode 为例，项目级 Skill 可放在 .opencode/skills/<name>/SKILL.md；兼容目录还包括 .agents/skills/ 和 .claude/skills/。

.opencode/skills/rule-review/
└── SKILL.md

---
name: rule-review
description: 审查业务规则，定位冲突、遗漏与不可验证的描述
---

## Workflow
1. 读取待审查规则及其上下文。
2. 按“冲突、遗漏、歧义”分类问题。
3. 为每个问题给出证据、风险和修改建议。

## Output
输出摘要、问题表和待确认事项；没有证据时明确写“无法判断”。

这一版的目标不是覆盖所有场景，而是回答两个问题：Agent 能否在正确时机发现它？输出是否比原始提示词更稳定？

03. V2：把经验变成约束

实际使用三到五次后，再补上最常见的失败模式。不要堆抽象原则，要把判断写成可执行规则：

• 严重程度分为阻断、高、中、低，并写明判定条件。
• 每个问题必须引用输入中的原句或文件位置。
• 不得把偏好包装成缺陷；不确定项进入“待确认”。
• 输出顺序固定为结论、证据、建议、验证方法。

此时可以增加少量正反例。一个好例子应该突出边界，而不是展示漂亮措辞。比如“系统应尽快响应”属于不可验证描述；“95% 请求在 800 ms 内完成”才有可检查的阈值。

04. V3：把知识移出主文件

当 SKILL.md 开始变长，不要继续无限追加。把检查表、术语表和模板放进 references/，脚本放进 scripts/，主文件只负责路由：

rule-review/
├── SKILL.md
├── references/
│   ├── severity.md
│   └── review-checklist.md
└── scripts/
    └── validate-report.ts

在主流程中明确何时读取哪个文件。这样既节约上下文，也避免 Agent 在无关任务里加载整套知识库。OpenCode 的技能发现、目录和 frontmatter 约束可参考官方 Agent Skills 文档。

05. 用验证矩阵验收

至少准备四类输入，并保存每次结果：

每轮只修改一个主要变量，再比较召回率、误报率和输出一致性。没有测例的 Skill 只是更长的提示词；有了可重复验证，它才开始成为工程资产。