skill-manager

# Tool List > When your Claude Code / Codex has hundreds of skills and a bunch of MCPs—duplicated features, ones you've never used, and ones you can't even remember the names of—the startup gets slower and slower, and you can't tell which one to use when you need it. skm is here for this moment. skm is a command-line tool for inventorying, organizing, and managing skills and MCPs in AIDE (Claude Code / Codex CLI): it gives you a clear view of the skills you currently have installed, automatically categorizes them by capability, detects four levels of duplication, tracks **actual usage frequency**, identifies unused skills, and safely cleans up session logs and soft-disables unused skills / MCPs. It operates in read-only mode by default and has zero third-party dependencies (only Node.js ≥ 18 required).  ## Features - **Dual-tool coverage**: scans both Claude Code (user-level / project-level / plugin-built-in skills, `~/.claude.json`, and `.mcp.json` MCPs) and Codex (`~/.codex/skills`, `config.toml` MCPs) - **Symlink awareness**: correctly handles symbolic links to shared libraries (e.g., `~/.agents/skills`) and distinguishes between "soft-linked shared entities" and "duplicate copies" - **Rule-based categorization**: built-in categorization rules (extensible / overridable via `~/.skill-manager/rules.json`); near-zero uncategorized rate - **Four-level duplication detection**: same-name multiple installations → different-name same-content → same-category multiple implementations → highly similar text - **Usage auditing**: parses session logs from both sides to track actual usage frequency of each skill / MCP, identifies unused skills, and automatically archives snapshots - **Session management**: views session log distribution by workspace, safely cleans up logs according to retention policies - **Default read-only**: only `sessions --clean` / `disable` / `enable` modify files, with confirmation and backup protection - **Zero third-party dependencies**: no npm packages required; all functionality based on Node.js built-in modules; only Node.js ≥ 18 required ## Installation ```bash # Method 1: global installation via npm npm i -g aide-skill-manager --registry=https://registry.npmmirror.com # Method 2: source installation (GitHub main repository; Gitee mirror available at https://gitee.com/synovation/skill-manager) git clone https://github.com/GrubbyLee/skill-manager.git cd skill-manager npm link # then use skm command globally; or use node bin/skm.js ``` ## Usage and Examples All examples are real outputs (tables truncated to show first few lines; workspace paths anonymized). All commands support `--json` output for scripting or AI consumption; output is color-highlighted in terminal (automatically disabled when piped / redirected, following `NO_COLOR` convention). ### skm — Health Check (dashboard) Running `skm` without any arguments provides an overall health check of your AIDE: ``` $ skm 📊 skill health check (scanned today; can re-scan if outdated) Total skills 165 skills / 6 MCPs Unused skills 105 unused (64%) Duplicated 40 sets of duplicate entities Idle MCPs drawio Session logs 1.8GB (can release 219.2MB with 30-day ∪ keep 3 strategy) Health score 35 / 100 Suggestions 1. Clean up 20 unused duplicates: skm disable baoyu-compress-image baoyu-cover-image … (see full list with skm audit --json) 2. Disable idle MCP: skm disable --mcp drawio 3. Session cleanup (plan first): skm sessions --clean --days 30 --keep 3 --dry-run 4. Full report: skm audit (usage frequency and unused list) | skm dupes (duplication details) ``` Health score is a heuristic rating from 0-100: 40 points deducted for high unused rate, 1 point for each duplicate entity (up to 20), 5 points for each idle MCP (up to 15), and 10 points per GB of session logs (up to 15). ### skm scan — Scan and Build Catalog Scans all skills and MCPs, generating `~/.skill-manager/catalog.json`. Options: `--verbose` shows all parsing warnings. ``` $ skm scan Scan completed ✓ Claude Code: 87 skills (72 user / 15 plugins), 6 MCPs Codex: 118 skills (118 user), 3 MCPs Deduplicated 165 skills, 40 with same-name installations on both sides Estimated resident context overhead: Claude ~9529 tokens, Codex ~10577 tokens Categorization distribution: Office Collaboration (Feishu) 25 | Content Extraction & Conversion 15 | Third-party Service Integration 15 | Image & Vision 14 | … Archived directories (_ or . prefix, not counted): claude 0, codex 2 Catalog written to ~/.skill-manager/catalog.json ``` ### skm list — Categorized List Lists all skills categorized (merges same-name entries by default). Options: `--category <keyword>` filters by category, `--tool claude|codex`, `--scope user|project|plugin`, `--mcp` lists MCPs, `--raw` shows installation records without merging. ``` $ skm list --category Publishing 【Publishing】 (4) Name Tool Description ──────────────────── ────── ──────────────────────────────────────────────── baoyu-post-to-wechat both Posts content to WeChat Official Account (微信公众号)… baoyu-post-to-weibo both Posts content to Weibo (微博). Supports regular posts… baoyu-post-to-x both Posts content and articles to X (Twitter). Supports… wechat-to-markdown codex Fetch WeChat Official Account (微信公众号) articles… Total 4 skills (scanned on 2026-07-18 23:09; can re-scan if outdated) ``` ### skm search — Keyword Search Searches by name / category / description (name match has higher weight), answering "which skill should I use for XX". ``` $ skm search convert to markdown Name Tool Category Description ────────────────────────── ────── ────────────── ──────────────────────────────── baoyu-danger-x-to-markdown both Content Extraction & Conversion Converts X (Twitter) tweets and… baoyu-format-markdown both Content Extraction & Conversion Formats plain text or markdown… baoyu-markdown-to-html both Content Extraction & Conversion Converts Markdown to styled HTML… baoyu-url-to-markdown both Content Extraction & Conversion Fetch any URL and convert to… wechat-to-markdown codex Publishing Fetch WeChat Official Account… ``` ### skm dupes — Four-level Duplication Detection ``` $ skm dupes 1. Same-name multiple installations (40 sets) baoyu-comic [claude/user + codex/user] identical content, consider symlinking or keeping one baoyu-cover-image [claude/user + codex/user] identical content, consider symlinking or keeping one … 2. Different names but identical content (0 sets) None 3. Multiple implementations in same category (15 categories have multiple implementations) 【Image & Vision】14: baoyu-* (6) | graphify | canvas-design | gpt-image-2 | … 【Design & UI】13: grill-me | huashu-design | ui-ux-pro-max | brainstorming | … … 4. Highly similar names and descriptions, suspected to be renamed duplicates (threshold 0.4, top 15 shown) 60% connect ↔ connect-apps ``` ### skm audit — Usage Frequency and Unused Skills Parses session logs to track actual usage; runs an auto-archive snapshot each time, use `--history` to view previous snapshots. ``` $ skm audit Observation window: from 2026-05-19 (based on existing session logs and aggregated tombstones) 1. Top 20 usage frequency (57 skills used) Name Count Last Used Category ─────────────── ───── ────────── ──────────── baoyu-image-gen 117 3 days ago Image & Vision ui-ux-pro-max 12 6 days ago Design & UI taste-skill 11 yesterday Design & UI … 2. Unused skills: 105 (64%) 【Office Collaboration (Feishu)】22: lark-approval、lark-attendance、… … 3. MCP usage (usage signals from Claude side calls; Codex side config not observable) Name Count Last Used ──────────────── ────── ────────── codex 13 today web-search-prime 10 12 days ago drawio 0 — ⚠ Unused MCP on Claude side: drawio — suggests disabling 4. Resident context overhead Top 10 (name+description estimation) … Suggestions 1. Clean up 20 unused duplicates: skm disable baoyu-compress-image … (see full list with skm audit --json) 2. Disable idle MCP: skm disable --mcp drawio 3. Cross-check duplication details before cleanup: skm dupes ``` ``` $ skm audit --history Archive Time Total In-use Unused File ───────────────── ───── ───── ───── ────────────────────────────── 2026-07-18 18:32 165 57 108 audit-2026-07-18T10-32-20.json 2026-07-18 22:28 165 57 108 audit-2026-07-18T22-28-41.json ``` ### skm sessions — Session Log Distribution and Cleanup Shows session log distribution by workspace. ``` $ skm sessions Session Count Volume Oldest Latest Workspace ────── ──────── ────────── ────────── ───────────────────── 60 349.8MB 2026-04-14 2026-07-18 ~/codes/project-a 27 153.0MB 2026-05-21 2026-07-17 ~/codes/project-b 28 150.2MB 2026-07-05 2026-07-18 ~/codes/project-c … Total 555 sessions, 1.8GB (Claude 126.2MB + Codex 1.6GB) ``` Cleanup: `--clean` with `--days <N>` and/or `--keep <N>` (union of both, more kept than deleted); use `--dry-run` to see plan, then confirm and re-run; script mode adds `--yes`. ``` $ skm sessions --clean --days 30 --keep 3 --dry-run Cleanup plan (retention policy: recent 3 ∪ 30 days ∪ 24-hour active): ~/codes/project-a Delete 41 sessions, release 208.7MB (newest one stops at 2026-06-15) … Total 76 sessions to delete, 219.2MB to release. [dry-run] Not executed. Confirm and re-run without --dry-run. ``` ### skm disable / enable — Soft-disable Skills and MCPs Disables skills by renaming directory with `_disabled-` prefix (AIDE no longer loads); completely reversible; MCP disable modifies config files, with backup and confirmation. ``` $ skm disable gsap-plugins Disabled claude/user/gsap-plugins Disabled codex/user/gsap-plugins $ skm enable # lists all disabled items without arguments Currently disabled 2 skills: gsap-plugins (claude/user) gsap-plugins (codex/user) $ skm enable gsap-plugins # re-enable $ skm disable --mcp drawio Will disable MCP: drawio (modifies AIDE config files; auto-backup before modification) Confirm to proceed? Input yes to continue, any other key to cancel: yes claude: removed drawio from ~/.claude.json (backup: ~/.skill-manager/backups/claude.json.drawio.2026-07-18T22-29-07) codex: disabled [mcp_servers.drawio] in config.toml (3 lines; backup: …) ``` ## Write Operation Boundary The tool does not modify AIDE config or skill files; only the following three actions modify files, each with protection: | Action | Modification | Protection | |---|---|---| | `sessions --clean` | Deletes session log files | Requires explicit retention policy; prints full cleanup plan; interactive confirmation or `--yes`; never deletes 24-hour active sessions; unknown workspaces only accept `--days` strategy; auto-aggregates usage stats into cache (tombstone mechanism) before deletion | | `disable/enable <skill>` | Renames skill directory | Completely reversible; does not delete files; refuses to handle plugin skills | | `disable/enable --mcp` | Modifies `~/.claude.json` / `config.toml` | Independent backup for each MCP operation (filename includes name + timestamp; never overwrites); Codex side only comments out lines; enable skips if user manually rebuilds same config; requires confirmation | ## audit Data Source - Claude Code: parses `~/.claude/projects/**/*.jsonl` for Skill tool calls and slash command records; MCP counts calls by `mcp__<server>__` tool - Codex: parses `~/.codex/sessions/**/*.jsonl`, **only counts `function_call` that actually reads `SKILL.md`** (Codex injects all available skill paths into session context; direct path matching would be highly inflated; mitigated) - Streaming line-by-line reading (constant memory; GB-sized files not affected by Node string limit); incremental caching by file size + mtime (`~/.skill-manager/usage-cache.json`, v2); initial scan takes ~10 seconds; subsequent scans in milliseconds - Parsing layer does not filter by name (filtering on consumption side); skills installed after logs can still be traced back - **Tombstone mechanism**: after log files are cleaned, aggregated stats are merged into resident aggregation bucket; each `audit` run archives a snapshot to `~/.skill-manager/audit-history/` - All dates displayed in Asia/Shanghai timezone; data files still store ISO/UTC ## Usage in AIDE (Recommended) Install thin-entry skill into either/both tools, then ask AI "I want to do XX, which skill should I use"; model will call `skm` to read latest catalog and answer: ```bash cp -r integrations/skill-navigator ~/.claude/skills/ # Claude Code cp -r integrations/skill-navigator ~/.codex/skills/ # Codex ``` ## Custom Categorization Rules Create `~/.skill-manager/rules.json` (user rules override built-in rules; `overrides` specifies single skill categorization): ```json { "rules": [ { "category": "My Category", "prefixes": ["my-"], "keywords": ["some keyword"] } ], "overrides": { "some-skill": "Development Assistant" } } ``` ## Data Description - Scan result: `~/.skill-manager/catalog.json`, does not contain any secrets / environment variable values (MCP `env` not read) - Context overhead estimation: skill resident part only includes `name + description` (body loaded on demand); MCP is full tool schema injection; more governance benefits - Archiving convention: directories with `_` prefix are ignored by scan (e.g., `_archived-xxx`) ## Directory Structure ``` bin/skm.js CLI entry (argument parsing & validation, command dispatch) src/adapters/ claude-code / codex scanning adapters src/commands/ scan / list / search / dupes / audit / sessions / toggle(disable+enable) src/classify.js categorization rule engine (DEFAULT_RULES + DEFAULT_OVERRIDES + user rules) src/usage.js session log usage statistics (streaming parsing, incremental caching, tombstone aggregation) src/sessionsIndex.js session file → workspace index & cleanup strategy src/catalog.js catalog read/write & same-name merging src/utils.js shared utilities (timezone formatting, atomic JSON read/write, confirmation interaction) integrations/ skill-navigator thin-entry skill test/ node --test unit tests ``` ## Roadmap - HTML overview report, more AIDE adapters (Cursor, Gemini CLI, etc.) - MCP per-server tool schema token measurement ## Final Note The more skills and MCPs in your ecosystem, the more crucial it is to manage them. skm does not make deletion decisions for you—it only lays out the facts: which are duplicated, which are unused, and which are slowing down your startup. After seeing the facts, cleanup is just a matter of convenience. If this tool helps you regain control over your skill directory, feel free to star [GitHub](https://github.com/GrubbyLee/skill-manager) or Gitee mirror: <https://gitee.com/synovation/skill-manager>. For issues or ideas, please open an [Issue](https://github.com/GrubbyLee/skill-manager/issues). ## License [MIT](LICENSE)