# Skills Sync > 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. - Skill: `shiquda/skills-sync` (Agent Skill) - Install (CLI): `npx skillmds@latest add shiquda/skills-sync` - Raw SKILL.md: https://api.skillmd.com/api/skills/shiquda/skills-sync/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: shiquda (https://skillmd.com/u/shiquda) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/shiquda/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: ```powershell 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: ```powershell npx @shiquda/skills-sync --help ``` Install this companion Skill from the GitHub repository with `npx skills`: ```powershell npx skills add shiquda/skills-sync --yes ``` ## Mental Model The data flow is: ```text 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 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: ```powershell 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: ```powershell skills-sync init --repo https://github.com//.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: ```powershell skills-sync sync --repo https://github.com//.git ``` ## Scan Skills Default scan searches global Skill locations: ```powershell skills-sync scan ``` Scan project-level Skills by passing a directory as the positional argument: ```powershell skills-sync scan . skills-sync scan E:\path\to\project ``` Include both project-level and global Skills: ```powershell skills-sync scan . --include-global ``` Filter by harness: ```powershell skills-sync scan --agent codex skills-sync scan --agent codex,claude-code ``` Use JSON when another script or agent needs structured output: ```powershell skills-sync scan --json ``` ## Preview Sync Use `plan` before syncing when the user wants to understand what will change: ```powershell skills-sync plan skills-sync plan . skills-sync plan --repo https://github.com//.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: ```powershell 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: ```powershell skills-sync sync --skill docx --skill pdf --yes ``` Upload from one harness: ```powershell skills-sync sync --agent codex --skill weread --yes skills-sync sync --agent cline --skill smart-search-cli --yes ``` Upload project-level Skills: ```powershell skills-sync sync . --skill my-project-skill --yes ``` Upload all discovered valid Skills without TUI: ```powershell skills-sync sync --all --yes ``` Control Git behavior: ```powershell skills-sync sync --skill docx --yes --no-push skills-sync sync --skill docx --yes --no-commit ``` ## Layers Use `--layer` to choose the repository layer: ```powershell skills-sync sync --layer curated skills-sync sync --layer experimental skills-sync sync --layer system skills-sync sync --layer root ``` Layer mapping: ```text curated -> skills/.curated// experimental -> skills/.experimental// system -> skills/.system// root -> skills// ``` These layouts are compatible with `npx skills` repository discovery. ## Repository Management Manage Skills already stored in the configured target repository: ```powershell 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 --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: ```text ~/.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: ```powershell 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 ` or pass `--repo` to each command. ## Install From Synced Repository After pushing Skills to the Git repository, users install them with `npx skills`: ```powershell npx skills add https://github.com//.git --list npx skills add https://github.com//.git --skill docx ``` Do not use `skills-sync` for downloading/installing Skills from the repository; that remains the job of `npx skills`.