AI Agent Skill Refactoring Methodology
Summary
Skill 重构不应从大重写开始。先明确单一职责、触发与跳过条件、硬安全线、合法例外和验证合约；主 SKILL.md 只保留执行时必须看到的规则，长案例和条件细节才进入 references/。
证据边界：本页综合公开的 Skill 演化材料和通用验证原则。它没有公开基准证明某种目录结构必然提高成功率，也不表示任何本地 Skill 已按此改造、审查或发布。Skill 格式、加载及执行命令应以目标宿主为准；SKILL.md / references/ 是常见文件式实例，不是所有 Agent 的必要接口。
When this method applies
适用于一个 Skill 已出现以下信号时：
- 主入口混入大量项目特例；
- 与其他 Skill 的职责边界模糊；
- 合法例外散落，快速扫描时容易误判；
- 安全或授权边界只藏在 reference；
- 完成声明缺少可重复的命令、输出或 artifact。
不适用于仅因“未来可能需要”而做的预防性重构。
Phase 0: Read-only baseline
先读取主文档、关联 references、调用入口和现有验证器，记录：
- Skill 的实际单一职责；
- 当前触发、跳过和升级条件；
- 常驻规则与条件细节的分布；
- 已存在的测试、静态检查和回滚点；
- 哪些内容只是一次项目经验，不能直接升级为通用规则。
Phase 1: Tighten the main contract
只修改共享 owner 能解决的问题：
- 把
When to use / When not to use前置； - 把数据、权限、生产副作用和不可逆操作边界放在主路径；
- 明确合法例外及其额外证据要求；
- 定义完成报告最少需要的可回读证据；
- 删除已被平台能力或其他 Skill owner 覆盖的重复规则。
不要先移动所有文件，也不要为一个实现新建接口或注册表。
Phase 2: Move conditional detail behind discoverable routes
只有当主入口已过重时才下沉 references。每条路由都应包含任务可识别的触发词，而不只是文件名。
例如：
- run ID collision / atomic report write / lock → CLI reliability reference；
- placeholder URL / source normalization / deduplication → search post-processing reference；
- production state / payment / notification → high-risk test boundary reference。
安全、授权、触发和验证底线仍留在主文档；reference 不能成为隐藏关键约束的地方。
Phase 3: Preserve behavioral evidence
重构前后至少验证：
- 代表性任务仍会触发该 Skill；
- 明确跳过条件仍不会误触发；
- 主路径能找到必要 reference；
- 风险边界没有被下沉或弱化；
- 原有验证器和最小回归检查通过。
对于委派任务，子 Agent 的自述不是证据。父级应回读变更并重跑关键检查；无法复验时把结果标为 provisional，而不是“通过”。
Phase 4: Bounded review and convergence
独立审查应针对实际变更，而不是只审计划。审查重点：
- 职责是否变窄而没有丢失必要行为；
- 触发词和 reference 是否可发现；
- 安全、授权和回滚是否仍显式；
- 合法例外是否在所有快速扫描位置一致；
- 完成声明能否由真实命令或 artifact 复验。
只修复经父级复核成立的具体问题。没有阻塞或重要问题后停止，不为“更完整”继续扩写。
Reusable checklist
- 是否确有重构需要，而不是规格性预建？
- 是否先查找并修改现有 owner？
- 主文档前部能否看见适用范围、跳过条件和硬边界？
- 哪些规则必须常驻，哪些只是条件细节？
- references 是否由任务语义触发？
- 是否保留一条可运行的回归检查？
- 子 Agent 或审查结论是否由父级读回验证？
- 变更是否减少重复、替换旧规则或退役过时入口？
Anti-patterns
- 把一次成功经验直接膨胀成长期通用规则；
- 用“更完整”为理由堆积项目特例；
- 把安全和授权边界藏到 reference；
- 只审计划，不审最终文件；
- 用审查标签替代父级验证；
- 只新增规则，不删除、合并或替换旧规则；
- 把示例配置写成已经部署或获得执行授权。
Takeaway
Skill 重构的目标不是写更多规则，而是让默认路径更短、责任更清楚、风险边界更可见、例外更明确、证据更可复验。
Relations
- depends_on: agent-self-validation-loops
- depends_on: subagent-orchestration-patterns
- related: hermes-context-layer-operating-rules
- related: hermes-knowledge-architecture