skills-sync

skills-sync syncs local Agent Skills into a git-backed skill repository. It is designed to complement npx skills: use this tool to upload and version your private skills, then use npx skills to list or install from that repository.

Install

Install the CLI:

npm install -g @shiquda/skills-sync

Install the companion Skill:

npx skills add shiquda/skills-sync --yes

Or run without installing globally:

npx @shiquda/skills-sync --help

During local development:

npm install
npm run build
node dist/cli.js --help

Configure

Create a project-local config:

skills-sync init --repo [email protected]:you/private-skills.git --branch main --layer curated

This writes .skills-sync/config.json. Command-line flags always override config values.

Typical Flow

skills-sync init --repo [email protected]:you/private-skills.git --branch main --layer curated
skills-sync scan
skills-sync plan
skills-sync sync

For project-level skills, pass the project as a positional argument:

skills-sync scan .
skills-sync plan .
skills-sync sync .

sync opens a tree-style selector grouped by harness. Press Space on a harness row to select that whole group, or Space on a skill row to select a single skill. Type to filter. Ctrl+A selects all visible rows, Ctrl+R inverts visible rows, and Enter confirms.

After copying files, sync commits and pushes by default. Use --no-push to commit locally only, or --no-commit to leave changes for manual review.

Identical duplicates are merged in the selector when they have the same name and content hash. The uploaded copy uses one representative directory, while the selector still shows how many local locations contain that same skill.

Scan Skills

By default, scan searches global skill locations for supported agents:

skills-sync scan

Scan a specific project's project-level skill locations:

skills-sync scan /path/to/project

When --project is set, project scan includes:

• root SKILL.md
• skills/
• skills/.curated/
• skills/.experimental/
• skills/.system/
• project agent paths such as .agents/skills/, .claude/skills/, .continue/skills/, .roo/skills/

Scan both project-level and global skills:

skills-sync scan /path/to/project --include-global

Limit to specific agents:

skills-sync scan --agent codex,claude-code,cursor

Scan custom directories:

skills-sync scan --path ./my-skills ~/.codex/skills

Plan And Sync

Compare discovered skills with the target repository:

skills-sync plan /path/to/project

status is kept as an alias for plan.

Sync all valid project skills into skills/.curated/:

skills-sync sync /path/to/project --all --commit --push

Sync selected skills:

skills-sync sync --skill docx --skill pdf --commit --push

Choose a layer:

skills-sync sync --layer experimental --all
skills-sync sync --layer system --all
skills-sync sync --layer root --all

Layer mapping:

| Layer | Target path | | --- | --- | | curated | skills/.curated/<skill>/ | | experimental | skills/.experimental/<skill>/ | | system | skills/.system/<skill>/ | | root | skills/<skill>/ |

Each sync writes .skills-sync/manifest.json in the target repository with source path, scope, agent, hash, and last sync time. Git remains the source of truth for review, history, rollback, and merge conflict handling.

When skills were installed by npx skills add, skills-sync also reads the npx skills lock file at ~/.agents/.skill-lock.json or $XDG_STATE_HOME/skills/.skill-lock.json. This provides source metadata such as source, sourceType, sourceUrl, skillPath, pluginName, installedAt, and updatedAt. Skills without lock metadata are treated as local skills.

Repository Management

Manage skills that already exist in the target repository:

skills-sync repo list
skills-sync repo search pdf
skills-sync repo info pdf
skills-sync repo remove pdf --commit --push
skills-sync repo history pdf
skills-sync repo restore pdf <commit> --commit --push

repo info and repo list show repository metadata including the last git change time when available. Deletes and restores are normal git changes, so rollback remains available through git history.

Install With npx skills

After pushing to GitHub, install with the existing CLI:

npx skills add [email protected]:you/private-skills.git --list
npx skills add [email protected]:you/private-skills.git --skill docx

Supported Agents

Run:

skills-sync agents

The built-in defaults cover common global and project locations for Codex, Claude Code, OpenClaw, Cursor, Cline, Roo Code, Continue, Gemini CLI, GitHub Copilot, OpenCode, OpenHands, Kiro CLI, Qwen Code, and Windsurf.

Use skills-sync doctor for health checks: local command availability, config, lock path, and target repository access.