skill-manager (skm)

English | 简体中文

A zero-dependency CLI to scan, recommend, deduplicate, audit, and visualize Claude Code / Codex skills and MCP servers.

When you keep adding skills to Claude Code or Codex, the local setup can become hard to reason about: duplicated skills, shared symlinks, unused tools, unclear names, and MCP servers that keep consuming context. skm turns that local toolbox into something you can inspect, search, compare, and clean up safely.

If skm helps you understand your local skill setup, a GitHub Star helps other AIDE users find the project.

Live preview · Click to play the complete English tour with voiceover and controls.

30-Second Start

git clone https://github.com/GrubbyLee/skill-manager.git
cd skill-manager
node scripts/install.mjs

skm scan
skm
skm ask "convert a web page to Markdown"
skm report --format html --output skm-report.html
skm graph --format html --output skill-graph.html

This is a source install. The install script runs npm link inside the cloned repository so the skm command becomes available on your machine. It also installs the bundled skill-navigator bridge skill into ~/.claude/skills/ and ~/.codex/skills/, so Claude Code and Codex can call your local skm command when you ask which skill to use. It does not install aide-skill-manager from the npm registry.

No npm package install is advertised yet. The package name aide-skill-manager is reserved, but the current recommended installation path is git clone plus node scripts/install.mjs.

CLI output supports language selection:

skm scan --lang en
SKM_LANG=zh-CN skm doctor

What It Solves

Command Cheatsheet

Detailed command manual: docs/usage.en.md.

Bundled bridge skill: skill-navigator is installed automatically for Claude Code and Codex to call local skm; it is not a CLI command.

Features

• Scans Claude Code and Codex CLI skills / MCP servers
• Detects shared symlinks, duplicate physical copies, and same-content copies
• Classifies skills with local rules
• Recommends skills from natural-language task descriptions
• Audits real usage from session logs
• Finds zombie skills and idle Claude-side MCP servers
• Exports JSON, Mermaid, and single-file HTML knowledge graphs
• Exports single-file HTML overview reports
• Uses zero third-party npm dependencies
• Runs on Node.js >= 18

Skill Recommendation

If you know what you want to do but do not remember which skill fits:

skm ask "convert a web page to Markdown"
skm recommend "create image cards for Xiaohongshu" --top 5
skm recommend "markdown to html" --why

By default, recommendations run locally. No external model is called, and no directory information is uploaded. The ranking combines skill name, category, description, task intent, conversion direction, usage history, recency, and whether the skill is available in both Claude Code and Codex.

Recommendation changes are checked against a public 40-case Chinese/English regression benchmark. Run npm run benchmark:recommend; see the recommendation guide for metrics and limitations.

You can explicitly ask a local AIDE CLI to help judge the short candidate list:

skm recommend "create a knowledge graph" --advisor codex --why
skm recommend "summarize meeting notes" --advisor claude

Advisor mode sends only a compact candidate list. It does not send real skill paths, config paths, MCP env values, API keys, passwords, private keys, or session log bodies.

Knowledge Graph

skm graph --format html --output skill-graph.html

The HTML graph is a zero-dependency single file. Open it in a browser and filter relationships from the left panel; the graph only shows nodes involved in the selected relationships. Nodes are draggable, which helps when you have many installed skills.

Current relationship types include same family, same category, duplicate, alternative, workflow, reverse conversion, shared platform, and uses MCP. Details are in docs/graph.md.

Overview Report

skm report --format html --output skm-report.html

The report puts health score, risks, usage, context cost, session logs, graph summary, and next commands on one local HTML page. Details are in docs/report.en.md.

Visual Story

Too many tools	Scan and label

Knowledge graph	Safe cleanup

Safe Troubleshooting Workflow

skm doctor
skm scan
skm
skm risks
skm report --format html --output skm-report.html
skm dupes
skm audit
skm list --mcp
skm sessions
skm sessions --clean --days 30 --keep 3 --dry-run

Start with read-only commands. Refresh facts first, then inspect health, risks, duplicates, usage, MCP servers, and session logs. Use dry-run before any cleanup.

Safety Boundaries

Most commands are read-only for Claude Code and Codex data. Some commands may update skm's own cache under ~/.skill-manager, but they do not modify your Claude/Codex configs, skills, MCP servers, or session logs. The explicit install script is the exception: it links skm locally and installs the bundled bridge skill into your user skill directories.

Inside the CLI, only three actions can modify AIDE files:

More details: docs/safety.md.

Use Inside AIDE

node scripts/install.mjs installs skill-navigator by default:

~/.claude/skills/skill-navigator
~/.codex/skills/skill-navigator

This thin skill is the bridge between your AIDE coding assistant and skill-manager: when you ask "which skill should I use for this task?", the assistant should call the local skm command instead of manually scanning directories. Re-run node scripts/install.mjs after pulling updates to refresh the bridge skill.

Documentation

Language and Platform Support

macOS / Windows: validated on demand through the manually triggered GitHub Actions workflow. Linux: validated locally by the maintainer with the same read-only build/test commands.

npm run check
npm test
npm pack --dry-run --registry=https://registry.npmmirror.com

skm help, argument validation, doctor, scan, status, risks, report, list, search, recommend, ask, graph, dupes, audit, sessions, disable, enable, and the local install script support English and Simplified Chinese output.

Use --lang en, --lang zh-CN, or SKM_LANG=en. JSON field names stay stable.

Manual validation entry: GitHub Actions / macOS / Windows CI.

Roadmap

• More real-world skm scan / skm recommend samples
• Better clustering and layout for large knowledge graphs
• More AIDE adapters, such as Cursor and Gemini CLI
• Per-server MCP tool schema token measurement

Full roadmap: docs/roadmap.en.md.

Community

If skm helped you understand your local skill setup, a GitHub Star helps more users find it. You can also:

• Share your skm scan result: https://github.com/GrubbyLee/skill-manager/discussions/9
• Discuss the roadmap: https://github.com/GrubbyLee/skill-manager/discussions/8
• Report issues or suggest features: https://github.com/GrubbyLee/skill-manager/issues

License

MIT