Manage AI agent skills in one place and sync them to Cursor, Claude, Hermes, Codex, Gemini, OpenCode, and more. The source of truth is .skillset/skills (project) or ~/.skillset/skills (user-level).
macOS & Linux · WSL 2 supported
curl -sSL https://raw.githubusercontent.com/webteractive/skillset/main/install.sh | sh -s -- --download
skillset listOn first run, a default config is created at ~/.config/skillset/config.json.
curl -sSL https://raw.githubusercontent.com/webteractive/skillset/main/install.sh | sh -s -- --downloadInstalls to ~/.local/bin or ~/bin—ensure it's on your PATH.
From a clone:
./install.sh --download # Download release binary
./install.sh /path/to/skillset # Use existing binary
./install.sh # Use ./target/release/skillsetgit clone https://github.com/webteractive/skillset.git && cd skillset
cargo install --path .Updating: Re-run the same install command; config and skills are preserved.
- Source: Skills live in
.skillset/skills(workspace) or~/.skillset/skills(user-level). - Targets: Config lists where to sync (e.g.
~/.cursor/skills,~/.claude/skills,~/.hermes/skills). - Scope: Use
--useror-Gto operate on user-level; otherwise, workspace.
| Command | Description |
|---|---|
skillset list |
Show skills and their status per target |
skillset sync |
Symlink skills from source to selected targets by default |
skillset install <path-or-package> |
Install skills from a local path or GitHub repo |
skillset migrate-to-symlinked |
Convert target skills to symlinks pointing at source |
skillset migrate-to-copy |
Convert target skills back to copied directories |
skillset add <name> |
Scaffold a new skill with template |
skillset remove <name> |
Remove a source-managed skill from source and matching targets |
skillset validate |
Check SKILL.md frontmatter for errors |
skillset where [skill] |
Show where skills are installed (tracked instances) |
skillset config <action> |
Manage configuration (show, add/remove targets, reset) |
skillset completions <shell> |
Generate shell completions (bash, zsh, fish) |
skillset self-update |
Update skillset to the latest version |
skillset doc --agents-md |
Output AGENTS.md snippet |
Common flags: --user / -G (user-level), --sync (with install), --symlink (default sync mode; retained for compatibility), --force (skip all prompts), --dry-run (preview without changes)
Install skills from a local path or GitHub repo. Package format can be a local directory, owner/repo (HTTPS by default), or a full Git URL. Local paths can point to a repo root, a skills directory containing skill subdirectories, or a single skill directory containing SKILL.md. Remote packages clone via git, so if you can git clone a repo, you can install from it—no extra auth. Your existing SSH keys, credential helper, or PAT in the URL all work as usual.
- Local paths:
skillset install ../my-skillsorskillset install ~/skills/my-skill - Public repos:
skillset install owner/repo - Private repos: Use the same URL you’d use for
git clone. With SSH keys set up,git@github.com:org/private-repo.gitworks. Orhttps://github.com/org/private-repo.gitif you use a credential helper or PAT. Setinstall.use_ssh: truein config to makeowner/reporesolve to SSH by default.
# Workspace vs user-level
skillset list # Workspace .skillset/skills
skillset list --user # User-level ~/.skillset/skills
# Install from local paths or repos (find more at https://skills.sh)
skillset install ../my-skills
skillset install ~/skills/my-skill
skillset install webteractive/skillset
skillset install anthropics/skills --skill=frontend-design
skillset install org/repo --sync --user
# Private repos—use whatever URL works with your git setup
skillset install git@github.com:org/private-repo.git
skillset install https://github.com/org/private-repo.git # if using credential helper or PAT
# Create and sync
skillset add my-skill
skillset sync
# Preview what would happen
skillset sync --dry-run
skillset install webteractive/skills --dry-run
# Show diff before overwriting
skillset sync --diff
# Convert existing target installs
skillset migrate-to-symlinked --user --force
skillset migrate-to-copy --user --force
# Filter skills
skillset list --filter="test"
skillset list --status=missing
skillset list --status=synced
# Validate skill frontmatter
skillset validate
# Shell completions
skillset completions bash >> ~/.bashrc
skillset completions zsh >> ~/.zshrc
skillset completions fish > ~/.config/fish/completions/skillset.fishskillset config show # Pretty-print current config
skillset config add-target "My Editor" ~/.myeditor/skills # Add a target
skillset config remove-target "My Editor" # Remove a target
skillset config reset # Restore defaults
skillset config validate-paths # Check which target paths existEdit ~/.config/skillset/config.json:
| Option | Description |
|---|---|
source |
Skills directory path (resolved by scope) |
targets |
List of { label, path } for sync destinations |
install.use_ssh |
Use SSH URLs for owner/repo format |
install.skill_dirs |
Dirs to search in repos (default: [".claude/skills", "skills"]) |
See config.example.json for the full default config.
skillset where shows where skills are installed across all targets:
# Show all tracked instances
skillset where
# Show instances for a specific skill
skillset where my-skill
# Scan existing targets and register instances (run once after upgrading)
skillset where --scanThe registry is auto-managed — instances are tracked on every sync and cleaned up when paths no longer exist.
skillset validate checks each SKILL.md for proper frontmatter:
$ skillset validate
Validating 3 skill(s):
✓ my-skill (author, version, tags)
✗ bad-skill — missing 'description'
✓ other-skill
1 error(s) found.Required fields: name, description. Optional: author, version, tags.
Skills can include optional metadata in their frontmatter:
---
name: my-skill
description: Does something cool
author: Glen
version: 1.0.0
tags: [testing, automation]
---By default, skillset sync places directory symlinks in configured targets so target skills stay live-linked to the source of truth. It skips targets that already point at the source skill directory. In copy mode, skillset skips skills whose SKILL.md is identical at the target. Use --force to skip prompts when a target needs to be rewritten.
Use skillset migrate-to-symlinked to convert existing copied target skills to symlinks, and skillset migrate-to-copy to convert symlinks back into real copied directories.
skillset remove <name> only removes skills that exist in the active source (.skillset/skills or ~/.skillset/skills). Target skills are removed only when they point to that source skill or match its SKILL.md, so independently installed same-named target skills are left alone.
skillset doc --agents-md >> AGENTS.mdTells AI agents where to store skills and how to use the CLI.
cargo build --release
cargo run -- list
cargo testReleasing: Update Cargo.toml, Cargo.lock, and CHANGELOG.md, then run cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --locked. Commit the release changes, tag it with git tag vX.Y.Z, and push the tag; GitHub Actions builds the release binaries and publishes the GitHub release.
- Rust 1.70+ (when building from source)
- git (for remote
skillset installpackages) - macOS, Linux, or WSL 2
MIT