agent-file-synchronization

Identity

You keep GEMINI.md, .github/copilot-instructions.md, and AGENTS.md as accurate mirrors of CLAUDE.md — the single source of truth for this repo's agent instructions. A blind full-copy destroys each target's platform-specific section; this skill detects and re-preserves those sections automatically instead of requiring a human to notice and re-append them by hand.

Scope: This skill owns mechanical replication. It does not own content quality (optimize-agent-instructions) or initial project scaffolding (project-setup).

What gets preserved per target

Target	Preserved section	Detected via
`GEMINI.md`	`## Gemini CLI Tool Mapping` table, appended at end of file	Tail marker match
`.github/copilot-instructions.md`	`# Copilot Instructions for <repo>` header + authoritative blockquote	Header lines before the shared body's first line
`AGENTS.md`	None currently required — verified fresh each run, not assumed	Header lines before the shared body's first line (empty if none)

The shared body boundary is CLAUDE.md's fixed opening line: "Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed." Everything in a target file between its own title and that line is treated as a preserved header. Everything after a known tail marker (currently only GEMINI.md's table) is treated as a preserved tail.

Steps

Dry-run first, always:
```
python3 ./scripts/sync_instruction_files.py (no flags, dry-run is the default)
```
Reports per-target line-count deltas and how many header/tail lines were detected and will be preserved. Review this before writing anything.

If the dry-run summary looks right, execute:

python3 ./scripts/sync_instruction_files.py --execute

Verify — read at least one target file's tail (tail -20 GEMINI.md) to confirm the preserved section actually landed, don't just trust the script's own summary line.
Reinstall + audit per this repo's standing rules — sync only touches root-level docs, not plugins/ source, so no plugin reinstall is needed for this step. But if the CLAUDE.md edit that triggered the sync also touched a skill/script, reinstall that plugin separately.

Common Failures

New platform section added to CLAUDE.md's own required structure: if a future target needs a new kind of preserved section (not a header-before-anchor or tail-after-marker), the script's TARGETS list and marker-detection logic need a code change — this skill does not invent new preservation strategies on its own.
Anchor line changed or removed from CLAUDE.md: the script hard-fails rather than guessing at the body boundary — if this happens, check whether CLAUDE.md's opening line changed and update ANCHOR_LINE in scripts/sync_instruction_files.py to match.
Target file has stray content between title and header that isn't actually platform-specific: the script will treat it as preserved-header and keep re-appending it forever. Manually clean the target once; subsequent syncs will then preserve the cleaned version correctly.

References

acceptance-criteria.md
CLAUDE.md — "Instruction File Mirrors" section documents the same preservation rules this skill automates
optimize-agent-instructions (agent-agentic-os) — deep content-quality audit, complementary not overlapping