| name | skills-sync |
| description | Manage, upload, and version local Agent Skills with the `skills-sync` CLI. Use this skill whenever the user wants to scan local/global/project Skills, upload selected Skills to a private or public GitHub skill repository, automate non-interactive Skill syncs, inspect remote Skill metadata/history, remove or restore repository Skills, or troubleshoot `skills-sync` workflows. |
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.
