Agent 指令迁移（Agent Instruction Migration）
用途
当一个代码仓库依赖大型 Agent 指令文件（例如 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md 或同类文档）来同时承载“仓库上下文”和“工作流执行”时，使用本技能。
其目标是把重复出现或必须执行的行为迁移到合适的控制面，而不是用一个巨大的散文文件被替换成隐藏在技能或脚本里的巨大生成提示词。
资源
- 在最终审查时，或当某个候选迁移显得较弱时，加载 references/failure-modes.md。
- 技能目录下的随附脚本：
- scripts/validate-migration-skill.sh <skill-dir>：验证本技能或生成的迁移技能。
- scripts/validate-migration-report.sh <migration-report.md>：验证迁移报告是否包含必需章节。
适用性门槛（Applicability Gate）
当以下条件中至少有两项为真时，可以进行迁移：
- Agent 指令很长、存在重复或被频繁重读
- 仓库中存在期望 Agent 遵循的重复工作流
- 除非写在散文里，否则重要步骤经常被跳过
- 某些规则是可机械检查的
- 现有脚本或 CI 已经编码了部分工作流
- 项目很可能被维护或被再次访问
当以下条件中大多数为真时，优先只输出审计结果：
- 指令很短且大多是稳定的上下文
- 工作流是一次性的或不太可能重复出现
- 规则主要依赖品味、产品判断或人工审批
- 没有有意义的检查可以脚本化
- 迁移会产生比行为变化更多的文件
- 仓库正在归档，预计未来没有工作
如果不确定，就产出一份报告，并建议在用户确认迁移价值之前不要改文件。
路由模型（Routing Model）
抽取不同的操作规则，拆分跨越多个类别的规则，并为每条规则指定唯一的主要目标：
| 规则形态 | 主要目标 |
|---|---|
| 稳定的仓库上下文、架构约束、命名、编辑边界 | 精简的 AGENTS.md 策略 |
| 依赖、schema、生产配置、外部契约或关键删除的审批边界 | 精简的 AGENTS.md 策略；绝不要把审批自动化掉 |
| 在移除确定性检查后仍需要判断的可复用工作流 | skills/<name>/SKILL.md，仅当通过技能候选测试时 |
| 可机械检查的行为，如 lint、schema/文件校验、漂移检查、格式化或构建 | scripts/、hooks、CI 或任务运行器条目 |
| 必需的顺序、阻塞门、重试、回退或机器可读状态 | 任务运行器、脚本、CI、hook 配置或编排器 |
在创建技能之前先问“这能是运行时控制流吗？”。让 LLM 负责解释、权衡、说明和残余风险分析；对于强制或可机械判定的行为，使用确定性机制。仅当存在实际的脚本、hook、CI 作业、任务运行器或编排器来强制执行时，才把仅靠散文规定的必需行为标注为“强制”，否则标注为“建议”。
流程（Procedure）
- 发现指令入口：检查 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md、README 工作流章节、提到必需 Agent 行为的文档、辅助脚本、CI 以及 hook/配置文件。记录路径、用途、类型（上下文/流程/执行）、新鲜度。
- 抽取可执行陈述：把每条指令规范化为简洁的操作规则，例如“编辑后运行测试”或“添加依赖前请求批准”。不要保留修辞性措辞。
- 分类并建模规则：使用上面的路由模型。对于每个重复或强制的工作流候选，勾勒： inputs -> states -> deterministic checkpoints -> success/failure status -> next action 包括必需输入、有序状态、阻塞性检查、重试/回退行为、机器可读输出（如适用）、仅 LLM 判断、停止条件和升级条件。
- 决定每个候选的目标：把每个候选记录为创建技能、更新已有技能、合并、保留在 AGENTS.md 中、转换为脚本/hook/CI、转换为编排，或拒绝。在创建新技能前检查仓库本地技能和可用技能，并在选择技能前应用下面的技能候选测试。
- 在大规模编辑前产出迁移报告：写 migration-report.md，包含以下章节：
- Summary
- Workflow Migration Gate Decision
- Instruction Sources Found
- Rule Inventory
- Classification Table
- Runtime Shapes and Control-Flow Candidates
- Scriptable Checks and LLM-Only Judgments
- Proposed Migrations
- Files to Generate or Modify
- Control-Flow Assets Produced
- Skill Candidate Decisions
- Existing Skill Relationships
- Rules Intentionally Left in AGENTS.md
- Rules Not Safely Automatable
- Risks / Ambiguities
- Verification Plan
- Finalization State 如果仓库很大或含义不明确，到此停止，除非用户明确要求应用更改。
- 在用户要求时保守地应用更改：缩短 AGENTS.md，但不要让它变成空壳。当某个流程移入技能、脚本、hook、CI 作业、任务运行器或编排器后，从 AGENTS.md 中移除重复的流程性散文；保留简洁的上下文、策略、审批边界和指向新控制面的工作流入口。只产出已批准的制品：报告、更新后的指令、合格的仓库本地技能、确定性辅助工具或控制流配置。对于生成的技能，包含清晰的名称和触发条件、适用性边界、必需输入、有序流程、验证、停止/升级条件、输出期望以及指向执行机制的链接。不要把项目特定知识放进技能正文，仅当技能专门关于某个工具、框架或环境时才包含具体命令。仅为零例外的行为添加 hook。
- 审查失败模式：加载 references/failure-modes.md，确认没有引入薄弱的技能、README 重复、提示词搬家、虚假的执行声明、假状态机、无依据的策略推断或不必要的 hook。
- 验证：在安全时运行相关现有测试或轻量检查。对于本技能或生成的迁移技能，运行 scripts/validate-migration-skill.sh。对于报告，运行 scripts/validate-migration-report.sh。
技能候选测试（Skill Candidate Test）
仅当确定性控制流不足以覆盖，且以下大多数条件为真时，才创建或更新技能：
- 它能在至少三个未来任务或仓库中提供帮助
- 它描述的是 Agent 动作，而不是背景知识
- 它是有验证步骤的可重复流程
- 它包含无法被脚本、hook、CI 作业、任务运行器、schema 检查或简短 AGENTS.md 策略替代的非平凡判断
- 它调用或引用用于强制行为的确定性检查
- 它避免让 LLM 执行脚本可以执行的检查
- 它能防止已知的失败模式或被跳过的工作流
- 移除项目特定名称后仍然有用
- 它比 README 内容、脚本注释、issue 或报告笔记更好
拒绝那些只是搬移长指令、而没有可执行检查点、更清晰入口或真实判断流程的候选。宁可不新增技能，也不要一个狭窄、仓库特定或低复用性的技能。
安全边界（Safety Boundaries）
不要自动执行以下操作：
- 在没有替代物的情况下删除大型文档章节
- 启用具有破坏性副作用的 hook
- 为情境性行为添加昂贵或嘈杂的 hook
- 在用户未要求时更改 CI 行为
- 推断仓库中并不存在的审批策略
- 编造仓库证据不支持的架构约束
- 在没有实际执行机制的情况下声称某行为已被强制执行