skill-sync

name	skill-sync
description	Synchronization across model directories. Trigger: After creating or modifying skills, agents, or prompts to sync across directories.
license	Apache 2.0
metadata	{"version":"1.1","type":"behavioral"}

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

Action	Sync Required?	How
Modify existing symlinked skill	No (auto)	Symlinks propagate changes
Create new skill	Yes	npx ai-agents-skills local
Delete skill	Yes	Remove from model directories
Modify AGENTS.md	Yes	Update CLAUDE.md, GEMINI.md if they exist
Modify prompts	No	Prompts are not copied to model dirs
Add skill dependency	Yes	Re-run npx ai-agents-skills local

✅ 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 - Standards for creating skills
• Makefile - Available build commands
• CLI source - Local installation logic