Skills sync

Skills Sync CLI

Use this skill when the user is working with the local skills-sync command or asks to manage Agent Skills across local harnesses and a Git-backed Skill repository.

skills-sync complements npx skills: skills-sync uploads and manages Skills in a Git repository; npx skills installs/downloads Skills from that repository.

Install CLI

The published npm package is @shiquda/skills-sync.

Install the CLI globally when the user wants the skills-sync command available in the shell:

npm install -g @shiquda/skills-sync
skills-sync --version
skills-sync doctor

Run without a global install when the user only needs a one-off command:

npx @shiquda/skills-sync --help

Install this companion Skill from the GitHub repository with npx skills:

npx skills add shiquda/skills-sync --yes

Mental Model

The data flow is:

local harness skill dirs
  -> skills-sync scan / plan
  -> optional TUI or non-interactive selection
  -> copy to target repo under skills/.curated, skills/.experimental, skills/.system, or skills/
  -> update .skills-sync/manifest.json
  -> git commit and push by default
  -> use npx skills add <repo> later to install/download

Local Skill sources include global harness directories such as ~/.agents/skills, ~/.codex/skills, ~/.claude/skills, ~/.openclaw/skills, and project-level directories such as .agents/skills, .claude/skills, skills/, and layered skills/.curated directories.

First Checks

Before changing anything, inspect the current setup:

skills-sync doctor
skills-sync agents
skills-sync scan

Use skills-sync doctor for health checks: Node, Git, GitHub CLI, configured repository, and the npx skills lock path.

Use skills-sync agents to show supported harnesses and their global/project Skill paths.

Configure Target Repository

Configure a default target repository once per workspace:

skills-sync init --repo https://github.com/<owner>/<repo>.git --branch main --layer curated

This writes .skills-sync/config.json in the current workspace. Command flags still override config values.

If no config exists, pass --repo directly:

skills-sync sync --repo https://github.com/<owner>/<repo>.git

Scan Skills

Default scan searches global Skill locations:

skills-sync scan

Scan project-level Skills by passing a directory as the positional argument:

skills-sync scan .
skills-sync scan E:\path\to\project

Include both project-level and global Skills:

skills-sync scan . --include-global

Filter by harness:

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

Use JSON when another script or agent needs structured output:

skills-sync scan --json

Preview Sync

Use plan before syncing when the user wants to understand what will change:

skills-sync plan
skills-sync plan .
skills-sync plan --repo https://github.com/<owner>/<repo>.git

status is an alias for plan.

The status kinds are:

• new: local Skill is not present in the target repo.
• same: local Skill content matches the target repo.
• modified: local Skill differs from the target repo.
• invalid: Skill is missing required metadata or has validation warnings.

Interactive Upload

Run:

skills-sync sync

The selector is tree-style:

• Top rows are harness/source groups.
• Press Space on a group to select or deselect all Skills in that group.
• Press Space on a Skill row to select or deselect one Skill.
• Type to filter.
• Press Enter to confirm.
• Ctrl+A selects all visible rows.
• Ctrl+R inverts visible rows.
• Esc cancels.

After selection, skills-sync sync commits and pushes by default. Use --no-push to commit locally only, or --no-commit to copy files without committing.

Non-Interactive Upload

For agent-driven uploads, prefer explicit filters and --yes.

Upload specific Skills:

skills-sync sync --skill docx --skill pdf --yes

Upload from one harness:

skills-sync sync --agent codex --skill weread --yes
skills-sync sync --agent cline --skill smart-search-cli --yes

Upload project-level Skills:

skills-sync sync . --skill my-project-skill --yes

Upload all discovered valid Skills without TUI:

skills-sync sync --all --yes

Control Git behavior:

skills-sync sync --skill docx --yes --no-push
skills-sync sync --skill docx --yes --no-commit

Layers

Use --layer to choose the repository layer:

skills-sync sync --layer curated
skills-sync sync --layer experimental
skills-sync sync --layer system
skills-sync sync --layer root

Layer mapping:

curated      -> skills/.curated/<skill>/
experimental -> skills/.experimental/<skill>/
system       -> skills/.system/<skill>/
root         -> skills/<skill>/

These layouts are compatible with npx skills repository discovery.

Repository Management

Manage Skills already stored in the configured target repository:

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

Use repo info when the user asks for metadata such as layer, target path, last git change time, and last commit.

Use repo history when the user wants rollback context or audit history.

Use repo restore to recover a Skill from an earlier commit.

Provenance

skills-sync reads npx skills provenance from:

~/.agents/.skill-lock.json
$XDG_STATE_HOME/skills/.skill-lock.json

When present, source metadata can identify where a local Skill came from, such as anthropics/skills, shiquda/roadmap-skill, or another GitHub repository. If no lock metadata exists, treat the Skill as local or manually authored.

Troubleshooting

If sync refuses to continue because the target repository has uncommitted changes, inspect the target repo:

skills-sync doctor
git status
git diff

Commit, stash, or intentionally remove those changes before syncing again. This guard prevents accidental overwrite of repository edits.

If a sync appears to use a cached repo path under .skills-sync/work, that is normal for remote Git URLs. The cache is the local clone used for commits and pushes.

If doctor reports no configured repo, run skills-sync init --repo <repo> or pass --repo to each command.

Install From Synced Repository

After pushing Skills to the Git repository, users install them with npx skills:

npx skills add https://github.com/<owner>/<repo>.git --list
npx skills add https://github.com/<owner>/<repo>.git --skill docx

Do not use skills-sync for downloading/installing Skills from the repository; that remains the job of npx skills.