agent-file-synchronization
Identity
You synchronize project instruction files across modern AI tooling environments.
Today, AGENTS.md is an open cross-tool standard (Codex, Cursor, Antigravity, and portable agents),
while CLAUDE.md is used by Claude Code, GEMINI.md is used by Gemini CLI, and
.github/copilot-instructions.md is used by GitHub Copilot.
A blind full-copy destroys platform-specific sections; this skill detects and re-preserves those
sections automatically instead of requiring a human to re-append them by hand. It also respects
repos that only want a subset of target files (via --targets) rather than forcing all 4 formats.
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 |
Open cross-tool standard (preserves custom header lines before anchor if any) |
Header lines before anchor |
CLAUDE.md |
Anthropic Claude Code standard |
Header lines before anchor |
The shared body boundary is the fixed anchor line: "Behavioral guidelines to reduce
common LLM coding mistakes. Merge with project-specific instructions as needed." (or standard # Project Name / # Purpose anchors).
Steps
Dry-run first, always:
python3 ./scripts/sync_instruction_files.py --dry-run
Or with selective source and targets:
python3 ./scripts/sync_instruction_files.py --source AGENTS.md --targets GEMINI.md,CLAUDE.md --dry-run
Reports per-target line-count deltas and preserved sections.
If the dry-run summary looks right, execute:
python3 ./scripts/sync_instruction_files.py --execute
Verify — inspect target files (e.g. tail -20 GEMINI.md) to confirm preserved sections.
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.
Checking .agent/rules/ drift against plugin rule sources
.agent/rules/*.md and plugins/<plugin>/rules/*.md are a separate pairing from the
CLAUDE.md-family mirrors above — same filename, but drift direction isn't reliably one-way
(either side can be the one that's stale), so this mode never writes:
python3 ./scripts/sync_instruction_files.py --check-rules
Reports per rule file: IDENTICAL, DIFFERS (with a unified diff), or
NO PLUGIN COUNTERPART FOUND (a .agent/rules/-only file with no matching plugin source —
not necessarily a problem, just worth knowing). On DIFFERS, read both files and manually
apply the fix on whichever side is actually behind — do not assume the plugin copy always wins.
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
1---2name: agent-file-synchronization3plugin: cli-agents4description: >5 Synchronizes project instruction files across AGENTS.md, CLAUDE.md, GEMINI.md, and6 .github/copilot-instructions.md while preserving platform-specific sections (GEMINI.md tool7 mapping, copilot authoritative header). Supports AGENTS.md or CLAUDE.md as primary source,8 and selective target syncing. Also reports drift between .agent/rules/ and matching9 plugins/*/rules/ sources. Triggers: "sync instructions", "sync CLAUDE.md to GEMINI.md",10 "sync AGENTS.md", "replicate instruction files", "mirror CLAUDE.md", "check rule drift".11allowed-tools: Bash, Read, Write12---1314<example>15<commentary>User has edited instructions and wants specific agent files kept in sync.</commentary>16user: "sync instructions across my agent files"17assistant: [triggers agent-file-synchronization, runs sync_instruction_files.py --dry-run by default, reports the diff summary, then runs with --execute after user confirmation]18</example>1920<example>21<commentary>User only uses AGENTS.md and GEMINI.md and wants selective target sync.</commentary>22user: "sync AGENTS.md to GEMINI.md"23assistant: [triggers agent-file-synchronization, runs sync_instruction_files.py --source AGENTS.md --targets GEMINI.md --dry-run]24</example>2526<example>27<commentary>Negative — user wants a stylistic quality audit, not a mechanical sync.</commentary>28user: "audit my AGENTS.md against Karpathy's principles and rewrite it"29assistant: [triggers optimize-agent-instructions, not agent-file-synchronization — that skill owns content quality, this one owns mechanical replication]30</example>3132# agent-file-synchronization3334## Identity3536You synchronize project instruction files across modern AI tooling environments.37Today, **AGENTS.md** is an open cross-tool standard (Codex, Cursor, Antigravity, and portable agents),38while **CLAUDE.md** is used by Claude Code, **GEMINI.md** is used by Gemini CLI, and39**.github/copilot-instructions.md** is used by GitHub Copilot.4041A blind full-copy destroys platform-specific sections; this skill detects and re-preserves those42sections automatically instead of requiring a human to re-append them by hand. It also respects43repos that only want a subset of target files (via `--targets`) rather than forcing all 4 formats.4445**Scope**: This skill owns *mechanical replication*. It does not own *content quality*46(`optimize-agent-instructions`) or *initial project scaffolding* (`project-setup`).4748## What gets preserved per target4950| Target | Preserved section | Detected via |51|---|---|---|52| `GEMINI.md` | `## Gemini CLI Tool Mapping` table, appended at end of file | Tail marker match |53| `.github/copilot-instructions.md` | `# Copilot Instructions for <repo>` header + authoritative blockquote | Header lines before the shared body's first line |54| `AGENTS.md` | Open cross-tool standard (preserves custom header lines before anchor if any) | Header lines before anchor |55| `CLAUDE.md` | Anthropic Claude Code standard | Header lines before anchor |5657The shared body boundary is the fixed anchor line: *"Behavioral guidelines to reduce58common LLM coding mistakes. Merge with project-specific instructions as needed."* (or standard `# Project Name` / `# Purpose` anchors).5960## Steps61621. **Dry-run first, always**:63 ```bash64 python3 ./scripts/sync_instruction_files.py --dry-run65 ```66 Or with selective source and targets:67 ```bash68 python3 ./scripts/sync_instruction_files.py --source AGENTS.md --targets GEMINI.md,CLAUDE.md --dry-run69 ```70 Reports per-target line-count deltas and preserved sections.71722. **If the dry-run summary looks right, execute**:73 ```bash74 python3 ./scripts/sync_instruction_files.py --execute75 ```76773. **Verify** — inspect target files (e.g. `tail -20 GEMINI.md`) to confirm preserved sections.78794. **Reinstall + audit** per this repo's standing rules — sync only touches root-level docs,80 not `plugins/` source, so no plugin reinstall is needed for *this* step. But if the CLAUDE.md81 edit that triggered the sync also touched a skill/script, reinstall that plugin separately.8283## Checking `.agent/rules/` drift against plugin rule sources8485`.agent/rules/*.md` and `plugins/<plugin>/rules/*.md` are a **separate pairing** from the86CLAUDE.md-family mirrors above — same filename, but drift direction isn't reliably one-way87(either side can be the one that's stale), so this mode never writes:8889```bash90python3 ./scripts/sync_instruction_files.py --check-rules91```9293Reports per rule file: `IDENTICAL`, `DIFFERS` (with a unified diff), or94`NO PLUGIN COUNTERPART FOUND` (a `.agent/rules/`-only file with no matching plugin source —95not necessarily a problem, just worth knowing). On `DIFFERS`, read both files and manually96apply the fix on whichever side is actually behind — do not assume the plugin copy always wins.9798## Common Failures99100- **New platform section added to CLAUDE.md's own required structure**: if a future target needs101 a *new* kind of preserved section (not a header-before-anchor or tail-after-marker), the script's102 `TARGETS` list and marker-detection logic need a code change — this skill does not invent new103 preservation strategies on its own.104- **Anchor line changed or removed from CLAUDE.md**: the script hard-fails rather than guessing at105 the body boundary — if this happens, check whether CLAUDE.md's opening line changed and update106 `ANCHOR_LINE` in `scripts/sync_instruction_files.py` to match.107- **Target file has stray content between title and header that isn't actually platform-specific**:108 the script will treat it as preserved-header and keep re-appending it forever. Manually clean the109 target once; subsequent syncs will then preserve the cleaned version correctly.110111## References112113- [`acceptance-criteria.md`](references/acceptance-criteria.md)114- `CLAUDE.md` — "Instruction File Mirrors" section documents the same preservation rules this skill automates115- `optimize-agent-instructions` (agent-agentic-os) — deep content-quality audit, complementary not overlapping
richfrem