skill-sync

Manage AI agent skills across multiple directories. Auto-discovers skill locations, maintains a manifest, and provides create/edit/sync/validate/deploy/doctor commands.

The problem

Different AI coding agents look for skills in different directories:

| Agent | Scans | |-------|-------| | OpenCode | ~/.agents/skills/, ~/.config/opencode/skills/, ~/.claude/skills/ | | Codex | ~/.agents/skills/, ~/.codex/skills/ | | Claude Code | ~/.claude/skills/ only |

No single directory is scanned by all three. Skills end up duplicated across locations, versions drift, and symlinks don't work reliably (Claude Code's skill discovery breaks on symlinks).

The solution

skill-sync treats ~/.agents/skills/ as the canonical source and syncs real copies to agents that need them (currently Claude Code). A manifest tracks what syncs where. A config file allows custom sources and targets.

Quick start

Via npm (recommended)

npm install -g @vikasagarwal101/skill-sync     # global install
skill-sync doctor                                # verify health

Or one-off without installing:

npx @vikasagarwal101/skill-sync doctor

Via git clone

git clone https://github.com/vikasagarwal101/skill-sync ~/dev/skill-sync
cd ~/dev/skill-sync
./install.sh
skill-sync doctor    # verify health

Commands

Core

sync [name]                Sync all manifest skills, or just one
add <name> [--to T]        Deploy a skill to a target (default: claude)
remove <name> [--from T]   Remove from target(s) — use --purge to also delete source
status                     Show sync state for all tracked skills

Authoring

create <name> [--scope S]  Scaffold new skill with valid frontmatter (default: agents)
edit <name>                Open SKILL.md in $EDITOR, offer sync on exit
rename <old> <new>         Rename a skill across source + all targets + manifest

Inspection

info <name>                Show source, sync state, health for one skill
list [--all]               List synced skills, or --all for every skill everywhere
search <query>             Find skills by keyword in name or description
diff <name>                Show content diff between source and target copies

Health

validate [name]            Check frontmatter + naming (one or all)
doctor                     Full health check across all locations

Target management

target list                Show all configured sources and targets
target add <label> <path>  Add a new sync target (persists to config)
target remove <label>      Remove a target (directories untouched)

Maintenance

init                       Rebuild manifest from current state
pull <name> [--from T]     Reverse sync: copy target edits back to source

Global flags

--dry-run                  Preview any command without making changes

Configuration

Config file

~/.config/skill-sync/config is auto-generated when you use target add/remove. It's a sourceable bash file that overrides the defaults at startup. You can also edit it manually:

# Example: add a project-local target
declare -A TARGETS=(
    [claude]="$HOME/.claude/skills"
    [work-project]="/path/to/project/.claude/skills"
)

Environment variables

All paths have env var overrides (checked before the config file):

| Variable | Default | Description | |----------|---------|-------------| | SKILLSYNC_BIN_DIR | ~/.local/bin | Where the CLI is installed | | SKILLSYNC_CONFIG_DIR | ~/.config/skill-sync | Manifest and config storage | | SKILLSYNC_AGENTS_DIR | ~/.agents/skills | Shared canonical source | | SKILLSYNC_OPENCODE_DIR | ~/.config/opencode/skills | OpenCode-only source | | SKILLSYNC_CODEX_DIR | ~/.codex/skills | Codex-curated source | | SKILLSYNC_CLAUDE_DIR | ~/.claude/skills | Claude Code sync target |

Architecture

Canonical sources (where skills live — auto-discovered)
  ~/.agents/skills/          ← shared (scanned by OpenCode + Codex)
  ~/.config/opencode/skills/ ← opencode-only
  ~/.codex/skills/           ← codex-curated

Sync targets (real copies, pushed from sources)
  ~/.claude/skills/          ← Claude Code (can't follow symlinks)

Config file (sourced at startup, overrides defaults)
  ~/.config/skill-sync/config

Manifest (tracks which skills sync to which targets)
  ~/.config/skill-sync/manifest

Nested skills

Skills with no root SKILL.md but subdirectories containing SKILL.md are detected as nested skills with parent/child naming (e.g., greptile/check-pr). This matches Codex's depth-6 scanning behavior.

YAML frontmatter support

The parser handles all common YAML scalar styles:

• Inline: description: My skill
• Quoted: description: "My skill"
• Folded: description: > (multi-line, joined with spaces)
• Literal: description: |- (multi-line)

Supported agents (8)

| Agent | Detection path | Registration method | |-------|---------------|-------------------| | OpenCode | ~/.config/opencode/ | Rule file + opencode.json instructions array | | Claude Code | ~/.claude/ | Rule file + @import in CLAUDE.md | | Codex | ~/.codex/ | Marker section in AGENTS.md | | Kilo Code | ~/.config/kilo/ | Rule file + kilo.jsonc instructions array | | Gemini CLI | ~/.gemini/ | Rule file + @import in GEMINI.md | | Auggie | ~/.augment/ | Rule file (auto-discovered in ~/.augment/rules/) | | Devin | ~/.devin/ | Marker section in AGENTS.md | | Antigravity | ~/.gemini/antigravity/ | No registration needed (reads AGENTS.md + scans ~/.agents/skills/) |

Install

git clone https://github.com/vikasagarwal101/skill-sync ~/dev/skill-sync
cd ~/dev/skill-sync
./install.sh

Interactive mode detects all installed agents and prompts for each:

Detected agents: opencode, claude, codex, kilo, gemini, auggie, antigravity

  Register with opencode (rule file + opencode.json)? [Y/n]
  Register with claude (rule file + CLAUDE.md import)? [Y/n]
  Register with codex (AGENTS.md section)? [Y/n]
  Register with kilo (rule file + kilo.jsonc instructions)? [Y/n]
  Register with gemini (rule file + GEMINI.md import)? [Y/n]
  Register with auggie (rule file, auto-discovered)? [Y/n]
  Antigravity: automatic — no registration needed

Non-interactive options:

./install.sh --with-rules all                    # register with all detected agents
./install.sh --with-rules opencode,claude,kilo   # specific agents only
./install.sh --no-rules                           # CLI only, no agent registration
./install.sh --uninstall                          # remove everything (prompts per agent)

Requirements

• Bash 4.0+ (associative arrays)
• awk, find, md5sum, du
• Linux or macOS