SkillsAdd

wquguru/skills · Archived

agent-compat-sync

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/*.

First seen Jul 14, 2026

Installation

$ npx skills add wquguru/skills --skill agent-compat-sync
View on skills.sh ↗ GitHub repository ↗

Summary

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

Stronger alternatives

This repository is archived — consider an actively maintained alternative.

fable5-best-practice Same source · more installs
wquguru/skills

Advise, prompt, and design workflows for Claude Fable 5. Use when choosing whether Fable is wor…

40 installs
english-swe-daily Same source · more installs
wquguru/skills

Daily English expression coach for intermediate software engineers. Use this skill whenever the…

30 installs
fable-5-best-practice Same source · more installs
wquguru/skills

Route Claude tiers, effort, and subagents for Fable-led work, and handle Fable-specific prompti…

22 installs
gpt-5-6-best-practice Same source · more installs
wquguru/skills

Route GPT-5.6 tiers, reasoning effort, and subagents to minimize accepted-result cost subject t…

9 installs

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

find-skills Same topic
vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "fi…

3.3M installs
agent-browser Same topic
vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, includ…

810.4K installs
vercel-react-best-practices Same topic
vercel-labs/agent-skills 697.8K installs
web-design-guidelines Same topic
vercel-labs/agent-skills

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "chec…

617.3K installs
microsoft-foundry Same topic
microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and …

576.5K installs
azure-prepare Same topic
microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Te…

568.3K installs

Also in this package

Other skills from wquguru/skills.

npx skills add wquguru/skills
fable5-best-practice 40 english-swe-daily 30 fable-5-best-practice 22 gpt-5-6-best-practice 9 skills-finder 2 pi-setup 2 clean-my-loop 1 free-my-cpu 1 free-my-disk 1

Browse all from wquguru/skills

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Not declared
Codex Declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 87
Default branch main
Open issues 0
Status Archived

Skill metadata

Parsed from SKILL.md frontmatter.

Declared agents claude-code codex

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 3,113 B
  • docs SUMMARY.md 463 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 1 installs

SKILL.md

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

  1. Inspect the repository root for CLAUDE.md, AGENTS.md, .claude/skills, and .agents/skills.
  2. 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.

  1. Create the missing instruction-file symlink:

- Claude canonical: AGENTS.md -> CLAUDE.md - Codex canonical: CLAUDE.md -> AGENTS.md

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

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