Sync Skill

Detect and resolve documentation drift between equivalent AI doc files across Claude Code, Cursor, and Codex CLI. Respects each tool's format requirements during conversion.

Step 1: Determine Sync Direction

Parse $ARGUMENTS to determine the sync direction:

• claude-to-all — Claude docs are the source of truth; propagate to Cursor and Codex
• cursor-to-claude — Cursor docs are the source of truth; propagate to Claude (and optionally Codex)
• codex-to-claude — Codex docs are the source of truth; propagate to Claude (and optionally Cursor)
• auto — Automatically detect which files were most recently modified and use those as source

If no argument provided, default to auto.

For auto mode: check file modification times using git log -1 --format="%ai" [file] or Bash stat. The most recently modified file in an equivalent group is the source of truth.

Step 2: Map Equivalent Files

Build a mapping of files that carry equivalent information across agents.

Tier 1 — Root project guide:

Claude Code	Cursor	Codex CLI
CLAUDE.md	.cursor/rules/general.mdc	AGENTS.md (overview section)

Tier 2 — Per-package guide (monorepo):

Claude Code	Cursor	Codex CLI
packages/[name]/CLAUDE.md	.cursor/rules/[name].mdc with package glob	packages/[name]/AGENTS.md

Tier 3 — Topic rules:

Claude Code	Cursor	Codex CLI
.claude/rules/[topic].md	.cursor/rules/[topic].mdc	AGENTS.md § [Topic] section

Tier 4 — Ignore files:

Claude Code	Cursor	Codex CLI
deny rules in .claude/settings.json	.cursorignore	.codexignore

Check for all files in each tier. Record which exist and which are missing.

Step 3: Read All Equivalent Files

For each equivalent group, read all files that exist. Extract the core semantic content, stripping format-specific elements:

From Claude rules (.md): Extract all ALWAYS/NEVER/DO/DON'T rules and code examples
From Cursor MDC: Strip YAML frontmatter, extract rules and examples
From AGENTS.md: Identify relevant section, extract rules and examples

Store extracted content in a normalized form for comparison.

Step 4: Detect Drift

Compare normalized content across equivalent files. Report drift as:

Commands drift:

• Dev command differs across files
• Test command differs
• Build command differs
• Lint command differs

Rules drift:

• A rule present in Claude docs is absent from Cursor/Codex
• A rule in Cursor docs contradicts a rule in Claude docs
• Different code examples that demonstrate the same principle differently
• A forbidden pattern allowed in one tool's docs

Style drift:

• Different project name / description
• Different framework version referenced

Coverage drift:

• Entire topic present in one tool's docs but completely absent in another

For each drift, classify severity:

• Minor: Formatting difference only (bold vs header), same semantic content
• Moderate: Different examples, same principle
• Major: Contradictory rules, missing critical rule in one agent, wrong commands

Step 5: Present Drift Report

Output a structured drift report before making any changes:

## Sync Drift Report

### Commands
- [file A]: dev command is `bun dev`
- [file B]: dev command is `npm run dev`  ← DRIFT (Major)

### Rules
- Rule "Never use new Date() with strings" present in CLAUDE.md
  - Missing from: AGENTS.md  ← DRIFT (Moderate)
  - Present in: .cursor/rules/general.mdc (as "NEVER: new Date('...')")

### Coverage Gaps
- .cursor/rules/testing.mdc exists but no equivalent AGENTS.md section  ← DRIFT (Moderate)

---
Proceed with sync? (yes / pick specific items / no)

Wait for user confirmation before applying any changes.

Step 6: Apply Sync

After confirmation, convert and apply content. Use the format conversion rules below.

Token efficiency during conversion — do not copy verbatim:

• Compact prose to imperative bullets and tables when converting to any format
• Syncing TO Cursor alwaysApply: true rules: keep the body focused and brief — these rules load on every interaction; trim or split if source is verbose
• Syncing TO AGENTS.md root: keep it a concise overview, not an exhaustive guide; move detailed rules to package-level AGENTS.md
• Eliminate duplication introduced by the sync: if the same rule already exists at the target, skip or cross-reference it

Format Conversion Rules:

Claude .md → Cursor .mdc

1. Add YAML frontmatter:

   ---
   description: [derive from Claude rule title and first paragraph]
   alwaysApply: [true if global rule, false if topic-specific]
   globs: [add if topic applies to specific file types]
   ---

2. Convert XML-style tags to bold headers:

   • <required> / </required> → ## ALWAYS
   • <forbidden> / </forbidden> → ## NEVER
   • <preferred> / </preferred> → ## PREFERRED

3. Convert list items to bold-prefixed items:

   • Preserve all DO/DON'T code examples as-is
   • Keep code fences with language identifiers

4. Add Cursor-specific frontmatter for paths: if the Claude rule has a paths: field or is clearly scoped to specific files.

Claude .md → AGENTS.md section

1. Identify where this content belongs in AGENTS.md (existing section or new section)
2. Use ## heading for the section
3. Convert code examples to standard markdown fences
4. Remove XML tags — use plain bold or headers instead
5. Ensure commands use the detected package manager

Cursor .mdc → Claude .md

1. Remove YAML frontmatter entirely
2. Convert bold ALWAYS/NEVER headers to ## ALWAYS DO / ## NEVER DO sections
3. Preserve all code examples
4. Add any Claude-specific cross-references if needed

AGENTS.md section → Claude/Cursor

1. Extract the relevant section
2. Apply the appropriate conversion (above) for the target format
3. Preserve all code examples

Ignore file sync

For deny rules ↔ .cursorignore ↔ .codexignore:

• Extract file patterns from each source
• Find union of all patterns
• Apply union to all three locations (with format conversion):
  • .claude/settings.json → add to permissions.deny as Read(.env*)
  • .cursorignore → add raw glob patterns
  • .codexignore → add raw glob patterns

Step 7: Report Applied Changes

After applying sync, output a summary:

## Sync Complete

### Files Updated
- [file]: [brief description of what changed]
- [file]: [brief description of what changed]

### Files Created
- [file]: [new file created from equivalent content]

### Drift Resolved
- [n] major drifts resolved
- [n] moderate drifts resolved
- [n] minor drifts resolved

### Remaining (manual review recommended)
- [any drift that was too complex to auto-resolve, with explanation]