用途：以 CLAUDE.md 为单一事实来源，把其内容镜像同步到 GEMINI.md、.github/copilot-instructions.md 和 AGENTS.md，同时自动识别并保留每个目标文件的平台专属段落，避免整文件覆盖时丢失这些内容。技能只负责机械复制，不负责内容质量（由 optimize-agent-instructions 负责）和项目初始搭建（由 project-setup 负责）。
保留规则：GEMINI.md 保留末尾的 “## Gemini CLI Tool Mapping” 表格，通过尾部标记匹配识别；.github/copilot-instructions.md 保留 “# Copilot Instructions for <repo>” 标题及其后的权威引用块，通过共享正文首行之前的内容识别；AGENTS.md 当前无需保留段落，但每次运行都会重新验证而非假设。共享正文边界为 CLAUDE.md 固定开头行 “Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.”。目标文件中位于其自身标题与该行之间的一切，被视为需保留的头部；已知尾标记之后的一切被视为需保留的尾部。
使用方式：先默认干跑，执行 python3 ./scripts/sync_instruction_files.py（无参数即干跑），查看各目标行数变化及检测到的头部/尾部保留行数；确认无误后执行 python3 ./scripts/sync_instruction_files.py --execute；再用 tail -20 GEMINI.md 等方式人工核对，不要只信脚本摘要。该同步只涉及根级文档，不触及 plugins/ 源码，因此本步骤无需重装插件；但若触发同步的 CLAUDE.md 修改同时改动了技能或脚本，需单独重装对应插件。
限制与常见失败：若未来需要新的保留策略（非锚点前头部或标记后尾部），需修改脚本的 TARGETS 列表与标记检测逻辑，技能本身不会自行发明新策略；若 CLAUDE.md 的锚点行被改动或删除，脚本会硬失败而非猜测边界，需同步更新 scripts/sync_instruction_files.py 中的 ANCHOR_LINE；若目标文件标题与头部之间存在并非平台专属的杂散内容，会被当作保留头部反复追加，需手工清理一次。参考资料包括 acceptance-criteria.md、CLAUDE.md 中的 “Instruction File Mirrors” 章节，以及 optimize-agent-instructions（agent-agentic-os）。