The Skillsync CLI works with agent skills stored as directories containing a SKILL.md file. Local discovery covers user and project skill roots for Claude-compatible and cross-agent layouts.
Remote operations require skl login. Local listing and upload --dry-run do not.
Local skill locations
skl looks in these roots:
| Scope | Locations |
|---|---|
| User | ~/.claude/skills, ~/.agents/skills |
| Project | <cwd>/.claude/skills, <cwd>/.agents/skills |
Project skills take precedence over user skills with the same canonical path. Symlinked copies are deduplicated where possible.
List local skills
skl skills list
skl skills list --scope user
skl skills list --scope project
skl skills list --json
When you are logged in, the human-readable listing also makes a short best-effort request for skills available through your account and workspaces.
Find and inspect shared skills
Search skills available to your account, then inspect one before installing it:
skl skills search "code review"
skl skills show @owner/skill-name
Both commands accept --json for machine-readable output.
Install a skill
Install for the current user:
skl skills install @owner/skill-name
Install into the current project:
skl skills install @owner/skill-name --scope project
The CLI writes conventional installations to both .claude/skills and .agents/skills. If a destination already exists, an interactive run asks before replacing it. Use --force for an intentional non-interactive overwrite.
Installed skills include a .skl.json provenance file so skl skills update can identify their source.
Update installed skills
Check every skill installed from Skillsync:
skl skills update --dry-run
Apply available updates:
skl skills update
skl skills update skill-one skill-two
Only installations with valid Skillsync provenance are updated. The command does not manage unrelated local skills.
Sync workspace skills
sync is a pull operation. With no skill name it compares workspace skills with local copies without changing files.
skl skills sync
skl skills sync --workspace <slug>
Apply one workspace skill locally:
skl skills sync <name>
skl skills sync <author/name> --workspace <slug>
| Option | Effect |
|---|---|
--workspace <SLUG> | Limit the comparison to one workspace. |
--project | Put a new skill in the current project instead of the user scope. |
--dry-run | Show per-file changes without writing them. |
-f, --force | Replace a differing local copy without prompting. |
--json | Emit machine-readable results. |
Sync preserves files that are not part of the server copy. It does not upload local changes or link the current directory to a workspace.
Publish a local skill
Validate without sending anything:
skl skills upload <skill-or-path> --dry-run
Publish privately, which is the default:
skl skills upload <skill-or-path>
Publish publicly:
skl skills upload <skill-or-path> --public
Omit the argument to choose a user skill interactively. Add --project when resolving a project skill by name. An explicit skill directory or SKILL.md path is also accepted.
The skill must have a non-empty Markdown body and a description in its frontmatter. Publishing includes SKILL.md plus readable, non-hidden text files under the skill directory. Inspect the directory before publishing. Binary files and dotfiles are skipped.
Publishing the same skill again under the same owner updates it. A name already owned elsewhere is reported rather than overwritten.
Automation
Use JSON output and non-interactive flags in scripts:
skl skills search "deploy" --json
skl skills install @owner/deploy --force
skl skills sync owner/deploy --dry-run --json
Set SKL_TOKEN when browser or device login is not appropriate. Treat it as a secret; it overrides the credentials stored by skl login.