Skm

skm — local skill admin

skm (npm package: skills-admin) is a management tool for skills already installed on disk — listing, auditing, deduplicating, and removing them across every AI coding agent. It does not install or update from remote sources; for that, use npx skills add / update.

When to use

Trigger this skill when the user:

• Asks where a skill is installed, or how many copies exist
• Mentions duplicate skills across agents, or wants only one canonical copy
• Wants to remove a skill from one specific agent, or from every agent
• Sees broken symlinks under ~/.claude/skills (or any agent skills dir) and wants them cleaned
• Mentions any of: ~/.claude/skills, ~/.agents/skills, ~/.cursor/skills, ~/.codex/skills, ~/.openclaw/skills, ~/.kiro/skills, ~/.factory/skills, ~/.gemini/skills, ~/.config/opencode/skills, or other agent skill dirs

Do not use for:

• Installing or updating skills from a repo — that's npx skills add / npx skills update
• Authoring a new skill — that's npx skills init

Vocabulary

• Location: a physical directory on disk (e.g. ~/.claude/skills). Same path is never listed twice even when multiple agents share it.
• Binding: an (agent, scope) pair that resolves to a location. Cline + Warp both bind to ~/.agents/skills globally; many "universal" agents bind to .agents/skills as project — same place, different bindings.
• Kind:
• dir — a real directory (independent content)
• link — a symlink to another path (often into ~/.agents/skills)
• BROK — a dead symlink whose target no longer exists
• file — a stray file (rare, usually wrong)
• Scope: global (in user home) vs project (in cwd). A single location can cover both.

Commands

skm ls       [-s global|project|all] [-a ] [-n ] [-p ]
             [-g] [-l] [-k ] [--broken] [--json]

skm rm  [-s ...] [-a ...] [-p ...] [--location-id ]
             [--all] [-y] [--dry-run]

skm doctor   [-s ...] [-a ...] [-p ...] [--fix] [--dry-run] [-y] [--json]

skm ls

Lists every skill across every existing agent directory. Discovery is cwd-independent — $HOME is always considered as a candidate cwd, so OpenClaw's bare skills/ dir at ~/skills is always found.

Useful invocations:

skm ls                              # everything
skm ls -n cold-email -g             # group by name → see all places this skill lives
skm ls -a claude-code               # only Claude Code locations
skm ls --broken                     # only dead symlinks
skm ls -k dir                       # only real (independent) directories
skm ls -k link                      # only symlinks
skm ls -l                           # extra column: symlink target
skm ls --json                       # JSON output for scripting

skm rm

Removes a skill from one or more locations.

Default behavior is interactive: shows every place that name lives and lets the user pick. --all deletes from every match unconditionally. Always confirms once before destructive action unless -y.

skm rm tempo-request                            # interactive picker across all matches
skm rm tempo-request --all -y                   # nuke from every agent dir
skm rm tempo-request -a cursor -y               # only from Cursor
skm rm tempo-request -p ~/.cursor/skills -y     # only from a specific dir (most precise)
skm rm tempo-request -s global -y               # only global scopes
skm rm foo bar baz --all --dry-run              # preview multi-skill removal

Symlinks vs dirs:

• Removing a link is harmless — only the symlink itself goes; the underlying target is untouched.
• Removing a dir deletes the real content. There's a confirmation prompt with red warning text.

Watch out: many Claude Code skills are symlinks pointing into ~/.agents/skills/. Deleting from ~/.agents/skills will turn those Claude entries into broken symlinks. Use the migration recipe below if the user wants to keep the skill working in Claude only.

skm doctor

Reports problems (no destruction by default):

• broken-symlink — a symlink whose target is gone
• missing-skill-md — a directory with no SKILL.md
• name-collision — same skill name resolves to two unrelated paths

--fix deletes broken symlinks (the only auto-fixable class). Always pair with --dry-run first when in doubt.

skm doctor                          # report only
skm doctor --fix --dry-run          # show what would be cleaned
skm doctor --fix -y                 # actually clean

Recipes

"Where is skill X installed?"

skm ls -n  -g

"Show me everything that's a duplicate across agents"

skm ls --json | jq '
  group_by(.name) | map(select(length>1)) |
  map({name: .[0].name, count: length, locations: map(.location.path)})
'

"Find and clean broken symlinks"

skm doctor --fix --dry-run    # preview
skm doctor --fix -y           # commit

Common cause: a previous npx skills remove deleted the canonical source under ~/.agents/skills/ but left dangling symlinks in ~/.claude/skills/ (and elsewhere). skm doctor --fix cleans them in one pass.

"Keep skill X only in Claude, remove everywhere else"

This is delicate when Claude's copy is a link pointing to ~/.agents/skills/, because deleting the source breaks Claude. Two-phase recipe:

# Phase 1: materialize Claude's symlink into a real dir.
SRC=~/.agents/skills/
DST=~/.claude/skills/
TMP=~/.claude/skills/.skm-migrate-
[ -d "$SRC" ] && [ -L "$DST" ] || { echo "preconditions fail"; exit 1; }
cp -R "$SRC" "$TMP" && rm "$DST" && mv "$TMP" "$DST"

# Phase 2: now safe to delete from every other dir.
skm rm  --all -y         # this picks up ~/.agents/skills + every other agent

If the Claude entry is already a dir (independent), skip Phase 1 — just skm rm --all -y (which excludes Claude only via -p exclusion if needed; the picker shows where it lives).

"What did npx skills add actually install?"

skm ls --json | jq '[.[] | select(.location.path == env.SKM_PATH)] | map(.name)'
# or simpler: skm ls -p ~/.claude/skills

"Move a skill from cwd-relative .agents/skills (universal) to Claude-only"

Same two-phase as above, replacing source path. The materialize step makes Claude independent, then skm rm -p ~/.agents/skills -y clears the universal source.

Safety rules

1. Never run skm rm with --all -y for a name the user hasn't named. Always confirm scope.
2. Always --dry-run first for any operation touching more than one location.
3. Never delete from ~/.agents/skills without first checking whether other agent dirs have symlinks pointing into it. skm ls -n -g shows that in one shot.
4. Don't write a script file to do destructive things — invoke ops inline so the user sees each command. bash -c '' is fine.
5. Don't materialize without permission when the user just said "delete". The materialize-then-delete recipe is for "keep in Claude only" intent.

Distribution

skm is shipped as the npm package skills-admin. Three ways to run it:

# 1. No install — one-off run
npx skills-admin ls
bunx skills-admin ls

# 2. Global install
npm install -g skills-admin   # then: skm ls
bun install -g skills-admin   # then: skm ls

# 3. From source (Bun + TypeScript)
git clone  && cd 
bun install
chmod +x bin/skm.ts
bun link
# now `skm` is on PATH via ~/.bun/bin/skm

If skm is not on PATH, fall back to bun run /bin/skm.ts .

What skm does NOT do (yet)

• Install / update from remote sources — use npx skills add/update
• Edit SKILL.md — open it directly with $EDITOR ~/.claude/skills//SKILL.md
• Search SKILL.md content — use rg ~/.claude/skills
• Convert between symlink and copy — manual cp -R + rm + symlink as needed
• Track install source — no manifest yet; use git log under ~/.agents/skills if it's a git repo

If the user asks for these, say so plainly and offer the manual command.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fatwang2
• Source: fatwang2/skills-admin
• License: MIT
• Homepage: https://www.npmjs.com/package/skills-admin

Install and usage instructions live in the source repository linked above.