Agent file synchronization

<example> <commentary>User has just edited CLAUDE.md and wants the other instruction files kept in sync.</commentary> user: "sync CLAUDE.md to the other agent files" assistant: [triggers agent-file-synchronization, runs sync_instruction_files.py (dry-run by default), reports the diff summary, then --execute after confirmation] </example> <example> <commentary>Negative — user wants a stylistic quality audit, not a mechanical sync.</commentary> user: "audit my CLAUDE.md against Karpathy's principles and rewrite it" assistant: [triggers optimize-agent-instructions, not agent-file-synchronization — that skill owns content quality, this one owns mechanical replication] </example> <example> <commentary>Negative — user is setting up a brand-new project's agent config, not replicating an existing CLAUDE.md.</commentary> user: "scaffold Claude and Gemini config for this new repo" assistant: [triggers project-setup, not agent-file-synchronization — no CLAUDE.md exists yet to sync from] </example>

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

1. 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.

2. If the dry-run summary looks right, execute:

   python3 ./scripts/sync_instruction_files.py --execute
   

3. 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.

4. 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