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.

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

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

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.

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.

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.

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.

Only three actions can modify files:

More details: docs/safety.md.

Use Inside AIDE

Install the thin navigator skill into Claude Code or Codex, then ask your coding assistant which skill to use for a task:

cp -r integrations/skill-navigator ~/.claude/skills/
cp -r integrations/skill-navigator ~/.codex/skills/

Visual Story

Too many tools	Scan and label

Knowledge graph	Safe cleanup

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

Documentation

Cross-Platform Validation

GitHub Actions validates macOS and Windows. Linux is 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

CI entry: GitHub Actions / macOS / Windows CI.

Language Support

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.

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