skm

skm: skills manager

Manage your agent skills (folders with a SKILL.md) in one place, from the terminal or a local web UI. skm sees your global skills (in your home folder) and your local skills (in the project you are in) at the same time.

• No dependencies, no build step. Node.js 20 or newer is all you need.
• Runs on 127.0.0.1 only; nothing leaves your machine.
• Never really deletes: delete moves the skill to the system Trash (macOS ~/.Trash, Linux XDG trash; Windows: skm's own %LOCALAPPDATA%\skm\Trash, not the Recycle Bin).

Install

git clone https://github.com/henriquefps/skills-manager.git
cd skills-manager
node -v   # must be >= 20

Pick one way to get the skm command in your terminal:

Alias in your shell config (installs nothing globally). From inside the cloned folder:

echo "alias skm='node \"$PWD/bin/skm.mjs\"'" >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

Or npm link (puts a skm command on your PATH):

npm link

Check it with skm --help.

How skills are organized

skm assumes this convention, and the normalize command brings your skills to it.

The project root is the nearest ancestor of the current directory that has .git, .agents or .claude.

Quick start

cd my-project
skm            # opens the web UI (port 4747) for global + local
skm list       # table in the terminal
skm doctor     # lists problems and the command that fixes each one

The web UI

Running skm with no arguments starts the server and opens your browser. There you can:

• switch between Global and Local, search, and filter by status;
• activate/deactivate a skill with its toggle;
• Promote a local skill to global, or Copy to local a global one;
• Normalize a skill with a problem (for diverged, pick which side to keep);
• Delete (moves it to the system Trash), with a confirmation that shows the exact destination;
• open Details to see the SKILL.md and the file tree;
• use Fix all in the problems banner, with a preview of what will change;
• press Check for updates to see which tracked skills are outdated, and Update them one by one, with a diff of what will change;
• see the context cost of every skill and the total for your active ones, and sort by it;
• see lint findings per skill and filter by them;
• open the Projects tab to browse your projects (what they are, their stack, tags and status) and their skills;
• switch the theme (System, Light or Dark) with the toggle in the top right corner; your choice is remembered in the browser;
• mark skills as favorites, add tags, filter by them, and copy several skills into the project at once;
• keep profiles (named skill kits) in the Profiles tab and Apply one to a project in one step;
• open Instructions on a project card to see its CLAUDE.md / AGENTS.md files, which are links or plain copies, and a diff of any two (read only);
• open the Health tab for broken links, missing sources, forgotten inactive folders and diverged copies, each with a fix button.

Options: --port <n> picks the port (if it is taken, the next free one is used) and --no-open skips opening the browser.

Commands

skm                       open the UI for the current directory
skm list [--json]         global and local skills with status
skm doctor                problems found and the suggested fix
skm normalize [name|--all] [--keep agents|claude] [--dry-run]
skm activate <name>       [--local|--global]
skm deactivate <name>     [--local|--global]
skm promote <name>        local -> global (copy)   [--overwrite]
skm pull <name>           global -> local (copy)   [--overwrite] [--target agents|claude]
skm refresh <name...>     replace local copies with the global one   [--dry-run] [--yes]
skm delete <name>         [--local|--global]   # moves to the system Trash; restore it from there by hand
skm outdated [--json]     check the GitHub source of each tracked global skill
skm update <name>         [--force] [--dry-run] [--yes]
skm update --all          [--force] [--dry-run] [--yes]   # only the ones with an update available
skm diff <name>           [--json]   # installed vs upstream, before updating
skm diff <name> --local   [--json]   # local vs global, before refreshing
skm cost                  [--json] [--all]   # estimated context tokens of active skills
skm lint [name]           [--json] [--all]   # check SKILL.md content; exit 1 on errors
skm fav <name...>         |   skm unfav <name...>   # favorites
skm tag <name> <tag...>   |   skm untag <name> <tag...>   |   skm tags
skm list --fav            |   skm list --tag <tag>   # filters (FAV and TAGS columns)
skm pull <name...>        # copy one or more global skills (inactive ones too) into this project
skm projects              [--json] [--brief] [--all]   # scan the configured project folders
skm projects find <words...>   [--json] [--brief]   # search projects by name, description, tags, stack
skm projects show <name|path>  [--json]   # full sheet of one project
skm projects ignore <name|path|glob...>   |   skm projects unignore <entry...>   |   skm projects ignored   # hide folders from the scan
skm projects set <name|path>   [--desc "..."] [--tags a,b] [--add-tag t] [--rm-tag t] [--status active|paused|archived] [--note "..."] [--clear desc|tags|notes|status]
skm projects add <path>   |   skm projects rm <path>   |   skm projects depth <n>
skm config                # show the config file path and content
skm profile list|show|save|apply|rm   # named skill kits (skm profile --help)
skm check                 [--json] [--global|--local|--projects]   # health check with fixes; exit 1 on errors
skm instructions [name|path]   [--json]   # CLAUDE.md / AGENTS.md files of a project and the global one (read only)
skm instructions diff <a> <b>  [--project <name|path>] [--json]   # diff two of them (global = ~/.claude/CLAUDE.md)

General options: --yes (skip confirmation), --dry-run (only show what would happen), --json, --port <n>, --no-open.

If the same name exists in both global and local, pass --local or --global.

Checking and updating skills

Skills installed with npx skills are recorded in ~/.agents/.skill-lock.json (repo, path in the repo and the git tree hash of the folder). skm reads it, never needs it, and shows the repo in the ORIGIN column of skm list. A skill whose folder no longer matches the recorded hash is marked [modified].

skm outdated asks GitHub (one call pair per repo; it uses GITHUB_TOKEN, GH_TOKEN or gh auth token when available, otherwise it is anonymous) and reports up-to-date, update-available, removed-upstream or unreachable. It runs only when you ask.

skm update <name> clones the repo (with your git credentials), moves the old folder to the system Trash, copies the new one in place and updates the hash and updatedAt in the lock file; all other lock fields and its indentation are kept. A modified skill is refused unless you pass --force; an inactive skill is updated where it lives. Use --dry-run to see the plan first.

Before you conf