Agent file synchronization

Skill richfrem/agent-plugins-skills/plugins/cli-agents/skills/agent-file-synchronization

repo for reusable plugins and skills

Install

npx -y skills add richfrem/agent-plugins-skills --skill agent-file-synchronization

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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

SKILL.md

5.4 KB, as published. Nobody here has run it

<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

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