Skill Sync

Maintain synchronization across all model directories after modifications to skills, agents, or prompts. With symlink-based installation (CLI local command), most syncing is automatic. This skill covers when manual sync is needed.

When to Use

• After creating or modifying skills, agents, or prompts
• After bulk changes or git pull with skill updates
• When model directories appear out of sync

Don't use for:

• Initial installation (use npx ai-agents-skills local)
• Adding skills from external repos (use npx ai-agents-skills add)

Critical Patterns

✅ REQUIRED: Understand Sync Architecture

With symlink-based local installation:

skills/react/          → Source of truth
.agents/skills/react/  → Symlink to ../../skills/react
.claude/skills/react/  → Symlink to ../../.agents/skills/react

Symlinked skills auto-sync - modifying source propagates instantly. Manual sync is only needed for:

• New skills not yet installed
• Copied (non-symlinked) installations
• AGENTS.md / model instruction file changes

✅ REQUIRED: Know When Sync Is Needed

✅ REQUIRED: Sync Targets

Model skill directories (updated via CLI):

• .github/skills/ (GitHub Copilot)
• .claude/skills/ (Claude)
• .codex/skills/ (Codex)
• .gemini/skills/ (Gemini)
• .cursor/skills/ (Cursor)

Model instruction files (manual update):

• AGENTS.md (root, source of truth)
• .claude/instructions.md (Claude-specific)
• .gemini/instructions.md (Gemini-specific)
• .github/copilot-instructions.md (Copilot-specific)

✅ REQUIRED: Sync Commands

# Re-install all skills (creates symlinks for new skills)
npx ai-agents-skills local

# Validate all skills are properly installed
npx ai-agents-skills validate --all

# List installed skills per model
npx ai-agents-skills list

❌ NEVER: Edit Model Directory Files Directly

Always edit the source in skills/ directory. Model directories should contain only symlinks (local) or copies that get overwritten on sync.

Decision Tree

What changed?
  → Existing skill content → No sync needed (symlinks auto-propagate)
  → New skill created → Run: npx ai-agents-skills local
  → Skill deleted → Remove symlinks from model dirs
  → AGENTS.md modified → Update model instruction files if they exist
  → Skill dependencies changed → Re-run: npx ai-agents-skills local
  → Multiple changes → Run: npx ai-agents-skills local

Workflow

After Modifying a Skill (Symlinked)

No action needed - symlinks propagate changes automatically.

After Creating a New Skill

1. Verify skill follows skill-creation standards
2. Run npx ai-agents-skills local to install to all model directories
3. Run npx ai-agents-skills validate --skill {name} to verify

After Modifying AGENTS.md

1. Identify changes in frontmatter or content
2. If .claude/instructions.md exists → regenerate via CLI
3. If .gemini/instructions.md exists → regenerate via CLI
4. Validate consistency across files

Bulk Synchronization

After git pull or multiple changes:

npx ai-agents-skills local    # Re-install all skills
npx ai-agents-skills validate --all  # Verify everything

Example

Syncing a newly created skill (my-skill) across all installed model directories.

# 1. Skill was just created at skills/my-skill/SKILL.md
#    It does not yet exist in any model directory — symlinks are missing.

# 2. Verify it follows skill-creation standards
npx ai-agents-skills validate --skill my-skill
# → Output: ✓ my-skill passes all checks

# 3. Run local install to create symlinks in all model directories
npx ai-agents-skills local
# → Creates:
#   .agents/skills/my-skill  → symlink → ../../skills/my-skill
#   .claude/skills/my-skill  → symlink → ../../.agents/skills/my-skill
#   .cursor/skills/my-skill  → symlink → ../../.agents/skills/my-skill
#   (all installed model dirs receive the symlink)

# 4. Verify sync is complete
npx ai-agents-skills validate --all
# → Output: ✓ All 63 skills validated across 4 model directories

# 5. Any future edits to skills/my-skill/SKILL.md are auto-propagated
#    via symlinks — no additional sync command needed.

Key takeaway: only new skills need the sync command. Edits to existing symlinked skills propagate automatically.

Edge Cases

No model directories installed: Skip sync. Skills will be installed when user runs npx ai-agents-skills local for the first time.

Partial installation: Only sync to existing model directories. Suggest npx ai-agents-skills local to install missing models.

Copied (non-symlinked) installations: Must manually re-copy or re-run CLI to sync. This happens with external install type.

Conflicting content in model dirs: Always prioritize skills/ as source of truth. Re-run CLI to overwrite.

Checklist

• Modified skills exist in all installed model directories
• Symlinks are intact (not broken)
• New skills installed via CLI
• AGENTS.md and model instruction files are consistent
• All referenced skills exist in skills/ directory
• No orphaned skill directories in model dirs

Resources

• [skill-creation](../skill-creation/SKILL.md) - Standards for creating skills
• [Makefile](../../Makefile) - Available build commands
• [CLI source](../../src/commands/local.ts) - Local installation logic