Skill 运营手册：让可复用工作流长期可维护
这篇文章解决什么问题
写一个 Skill 不难，难的是让它长期可用。很多 Skill 一开始能触发，过一段时间就失效：项目结构变了、脚本路径变了、模型行为变了、输出格式漂移、用户不知道什么时候该用。
Skill 运营手册的目标是把 Skill 当成产品和工程资产来维护：有版本、触发条件、验收标准、测试样例、变更记录、回滚策略和使用反馈。
Skill 的生命周期
| 阶段 | 目标 |
|---|---|
| Idea | 明确重复场景和用户问题 |
| Design | 定义触发条件、输入、流程、输出 |
| Implement | 编写 SKILL.md、脚本、模板和参考资料 |
| Test | 覆盖触发、流程、输出、安全和回归 |
| Release | 标记版本、写 changelog、更新入口 |
| Operate | 收集使用反馈、监控失败、修复漂移 |
| Retire | 废弃无用 Skill，迁移到新版本 |
不要把 Skill 当成一次性提示词，它更像一个轻量流程产品。
什么时候值得写 Skill
适合写 Skill 的场景：
- 重复出现的博客内容批处理。
- 项目版本发布和检查流程。
- 简历、作品集、面试材料整理。
- MCP Server 创建和测试流程。
- 数据清洗、文档生成、报告格式化。
- 多步骤且容易漏检查项的任务。
不适合写 Skill 的场景：
- 一次性问题。
- 需求还没稳定的探索任务。
- 需要大量临场判断且没有固定验收标准的任务。
- 高风险操作但没有审批和测试的流程。
Skill 设计卡片
每个 Skill 可以先写一张设计卡：
| 字段 | 内容 |
|---|---|
| skill_name | 名称 |
| user_problem | 解决什么重复问题 |
| trigger | 什么时候应该使用 |
| inputs | 需要用户或仓库提供什么 |
| procedure | 固定步骤 |
| outputs | 交付物格式 |
| validation | 如何验证完成 |
| safety | 哪些操作不能做或需要确认 |
| examples | 典型输入输出 |
| owner | 维护者 |
设计卡比直接写长文更容易审查。
SKILL.md 结构建议
一个可维护 Skill 的 SKILL.md 可以包含：
- 适用场景
- 不适用场景
- 输入要求
- 操作步骤
- 文件/脚本约定
- 验收标准
- 安全限制
- 常见失败和处理
- 示例输出
- Changelog
其中“验收标准”和“安全限制”最容易被忽略，但它们决定 Skill 是否可靠。
版本管理
Skill 也应该有版本号。
| 变更 | 版本策略 |
|---|---|
| 修正文案、补充说明 | patch |
| 增加可选步骤或新模板 | minor |
| 改变触发条件、输出格式、脚本接口 | major |
| 删除能力 | major + migration note |
建议每次变更写 changelog：
- 变更了什么。
- 为什么变更。
- 是否影响旧输出。
- 需要重新测试哪些样例。
测试类型
| 测试 | 检查点 |
|---|---|
| Trigger Test | 用户描述是否会正确触发 Skill |
| Procedure Test | 步骤是否完整，不会跳过关键检查 |
| Output Test | 输出格式是否符合预期 |
| Script Test | 依赖脚本是否能运行 |
| Safety Test | 是否避免危险操作、越权、误删 |
| Regression Test | 历史样例是否仍然通过 |
| Handoff Test | 失败时是否能给出清晰下一步 |
Skill 测试不一定全自动，但至少要有固定样例和人工验收清单。
运营指标
如果 Skill 被频繁使用，可以记录这些指标：
| 指标 | 含义 |
|---|---|
| usage_count | 被调用次数 |
| success_rate | 成功完成比例 |
| intervention_rate | 需要用户补充信息比例 |
| edit_after_output | 输出后人工修改程度 |
| failure_reason | 常见失败分类 |
| avg_time_saved | 节省时间估计 |
| stale_reference_count | 引用路径或脚本失效次数 |
这些指标可以帮助决定 Skill 是继续维护、重构还是废弃。
Skill 漂移和修复
Skill 漂移常见原因：
- 仓库目录结构变化。
- 依赖脚本路径变化。
- 外部工具 API 变化。
- 用户目标变化。
- 模型对指令的执行方式变化。
- 输出格式没有被测试固定。
修复方法：
- 增加更明确的触发和不触发条件。
- 把复杂步骤脚本化，减少自然语言歧义。
- 增加示例输入输出。
- 增加回归样例。
- 更新 changelog 和迁移说明。
安全边界
Skill 可能引导 Agent 执行文件修改、Git、网络请求或部署操作，因此必须写安全边界。
建议包含：
- 不修改代理配置、密钥、系统设置。
- 删除、重置、覆盖前必须确认。
- 只提交指定源文件，不提交生成目录和密钥。
- 网络资料要标注来源，不复制长篇版权内容。
- 高风险命令要先解释影响。
- 失败时停止并报告，不假装验证通过。
Skill 的安全边界越清晰，越适合长期复用。
Skill 和 AGENTS.md 的关系
| 文件 | 作用 |
|---|---|
| AGENTS.md | 仓库级长期规则、项目背景、通用检查 |
| SKILL.md | 某类任务的可复用流程和验收标准 |
| scripts | 可执行检查、生成、转换和验证 |
| templates | 输出格式和样板 |
| references | 背景资料、术语表、案例 |
AGENTS.md 解决“这个仓库怎么协作”，Skill 解决“这个任务怎么稳定完成”。
面试表达模板
我会把 Skill 当成可维护工作流，而不是一次性提示词。设计时先定义触发条件、输入、步骤、输出、验收标准和安全边界；实现时尽量把可重复检查脚本化；发布时记录版本和 changelog；后续通过触发测试、流程测试、输出测试、安全测试和回归样例维护稳定性。这样 AI 协作流程可以长期复用，而不是每次靠临时提示词。
常见误区
误区一：Skill 越长越好
Skill 不是百科全书。它应该清晰告诉模型什么时候用、怎么做、怎么验收。
误区二：没有不适用场景
没有不适用场景的 Skill 容易误触发，导致错误流程套到不合适任务上。
误区三：没有回归样例
模型和项目都会变化，没有回归样例就很难发现 Skill 已经漂移。