Agent compat sync

Skill wquguru/skills/skills/agent-compat-sync

Practical Agent Skills — English-for-engineers coaching, Pi Agent setup, and more. Install via npx skills add.

Install

npx -y skills add wquguru/skills --skill agent-compat-sync

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

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

Keep repository-level Claude and Codex agent instructions compatible by creating safe symlinks between CLAUDE.md and AGENTS.md, and between .claude/skills/* and .agents/skills/*. Use when a repository should work with both Claude and Codex, when one agent instruction file exists but the other is missing, when migrating agent skills between .claude and .agents directories, or when asked to improve Claude/Codex compatibility for a repo.

SKILL.md

3.0 KB, as published. Nobody here has run it

Agent Compat Sync

Make a repository usable by both Claude and Codex without duplicating instruction files or skill folders. Prefer symlinks so one canonical source stays authoritative.

Workflow

Inspect the repository root for CLAUDE.md, AGENTS.md, .claude/skills, and .agents/skills.
Choose the canonical side:
- If CLAUDE.md exists and AGENTS.md is missing, treat Claude as canonical.
- If AGENTS.md exists and CLAUDE.md is missing, treat Codex as canonical.
- If one instruction file is already a symlink to the other, treat the real target side as canonical.
- If both instruction files exist as independent real files, stop and ask the user which file should become canonical.
Create the missing instruction-file symlink:
- Claude canonical: AGENTS.md -> CLAUDE.md
- Codex canonical: CLAUDE.md -> AGENTS.md
Mirror skill entries with per-entry symlinks:
- Claude canonical: create .agents/skills/<name> -> ../../.claude/skills/<name> for each item in .claude/skills.
- Codex canonical: create .claude/skills/<name> -> ../../.agents/skills/<name> for each item in .agents/skills.
Treat an existing path as acceptable when it already resolves to the same real target, even if the symlink is on a parent directory or points in the reverse direction.
Never overwrite existing real files or directories without explicit user approval. Report conflicts with exact paths.

Scripted Sync

Use the bundled script for normal execution:

python3 scripts/sync_compat.py --repo /path/to/repo

From the target repository root, this is also valid:

python3 /path/to/agent-compat-sync/scripts/sync_compat.py

Useful options:

--dry-run: show planned changes without writing.
--repo PATH: run against a repository other than the current working directory.

The script is intentionally conservative. It creates missing symlinks and directories, leaves correct or equivalent symlinks alone, and exits non-zero when it finds ambiguous or conflicting existing paths.

Manual Fallback

If the script cannot be used, apply the same rules manually with relative symlinks.

Claude canonical:

ln -s CLAUDE.md AGENTS.md
mkdir -p .agents/skills
ln -s ../../.claude/skills/<skill-name> .agents/skills/<skill-name>

Codex canonical:

ln -s AGENTS.md CLAUDE.md
mkdir -p .claude/skills
ln -s ../../.agents/skills/<skill-name> .claude/skills/<skill-name>

Before creating any symlink manually, check whether the destination already exists. If it exists and is not already the expected symlink, stop and ask the user.