| name | agent-file-synchronization |
| plugin | cli-agents |
| description | Replicates CLAUDE.md into GEMINI.md, .github/copilot-instructions.md, and AGENTS.md as full-copy mirrors while auto-detecting and preserving each target's platform-specific section (GEMINI.md's Gemini CLI Tool Mapping table, copilot-instructions.md's authoritative header) instead of destroying it on overwrite. Use when the user asks to sync, replicate, propagate, or mirror CLAUDE.md into the other agent instruction files. Different from optimize-agent-instructions (deep Karpathy-principle content audit, doesn't cover AGENTS.md) and project-setup (initial onboarding scaffold for a new project, not an existing CLAUDE.md). Trigger with "sync CLAUDE.md to GEMINI.md", "replicate CLAUDE.md to agent files", "propagate CLAUDE.md changes", "update agent instruction files", "mirror CLAUDE.md".
|
| allowed-tools | Bash, Read, Write |
User has just edited CLAUDE.md and wants the other instruction files kept in sync.
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]
Negative — user wants a stylistic quality audit, not a mechanical sync.
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]
Negative — user is setting up a brand-new project's agent config, not replicating an existing CLAUDE.md.
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]
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.mdCLAUDE.md — "Instruction File Mirrors" section documents the same preservation rules this skill automatesoptimize-agent-instructions (agent-agentic-os) — deep content-quality audit, complementary not overlapping
