skill-mcp v0.2.0

skill-mcp v0.2.0

Local stdio MCP that lists, suggests, and binds at most 3 local SKILL.md files. Token budget never raises the cap.

A — Mac / local attach

./scripts/install.sh builds the server and writes absolute-path Claude Desktop / Cursor mcp.json snippets (docs/output/…). Mac path: ~/Library/Application Support/Claude/claude_desktop_config.json.

B — 30-second demo

Install too many skills → suggest_skills (cap 3) → bind_skills → write_host_contract. See README EN/ZH.

C — Host contract actually takes effect

write_host_contract / node dist/index.js write-contract writes Claude CLAUDE.md and Cursor .cursor/rules/skill-mcp-contract.mdc in one shot. Generated files list only bound skills and forbid others.

D — Offline goldens in CI

.github/workflows/ci.yml runs npm test, npx tsc --noEmit, npm run build, and npm run eval on pull requests and main.

E — Optional binary

./scripts/pack.sh (bun compile) produces skill-mcp-linux-x64. Fallback: npm run build && node dist/index.js. See docs/PACKAGING.md.

F — Empty suggest

When nothing matches: This directory has no matching skill for that prompt. / 该目录下没有匹配该提示的技能。

G — Auto-uninstall (dry-run / --apply)

• Default is dry-run: report idle and shadowed user-tier skills; never moves or deletes.
• Real move only with CLI --apply or MCP { "apply": true }.
• Destination: ~/.config/skill-mcp/archive/<timestamp>/ plus manifest.json. Recoverable. Never silent-deletes.

node dist/index.js archive-idle
node dist/index.js archive-idle --apply

H — Native skills bypass (toggle / restore / risk)

• native-skills enable writes Claude skillOverrides name-only so the host listing does not dump every description.
• native-skills restore (or { "enabled": false }) restores the previous ~/.claude/settings.json in one step.
• Risk: routing fight with Claude Code native skills. Plugin skills are not covered. Restore immediately if routing feels wrong. Does not delete SKILL.md files.

node dist/index.js native-skills enable
node dist/index.js native-skills restore

Constraints held

stdio MCP only · max 3 · CJK ZH/JA/KO · read_skill opt-in · no store · no ranker retrain · no GIF in README

v0.1.1

skill-mcp v0.1.1

This release ships the full local stdio MCP feature set and a new bilingual README (static SVG, no GIF).

README

• Redesigned README.md and README.zh-CN.md
• Hero, workflow, install, and v0.1.1 boards as static SVG
• Install and Claude Desktop / Cursor wiring with absolute-path mcp.json snippets

Features

1. One-shot ./scripts/install.sh writes docs/output/claude-desktop.mcp.json and docs/output/cursor.mcp.json using absolute dist/index.js paths
2. suggest_skills returns names[] ready for bind_skills plus a next_step
3. rescan_skills reloads skill roots without restarting the process
4. Shadowed skills include plain-language why (who shadows) and how to unshadow
5. Binding contract on get_binding and resource skill-mcp://binding/contract — host may use only these N skills
6. Session (in-memory) / project (.skill-mcp/binding.json) / global (~/.config/skill-mcp/binding.json) bind scopes; priority session > project > global
7. Lexical routing by default; optional Ollama embeddings as a soft dependency
8. Offline eval goldens: ZH / JA / KO plus multi-skill conflicts (npm run eval)
9. Review drafts moved to docs/ so they are not user-facing root artifacts

Invariants (unchanged)

• Local stdio MCP only
• Hard max 3 bound skills; token budget never raises the cap
• CJK (ZH/JA/KO) names and content
• doctor and archive_idle are dry-run only
• read_skill is explicit opt-in
• No store, auto-uninstall, or ranker retrain

v0.1.0

Local stdio MCP server for SKILL.md routing. Tools: list_skills, suggest_skills (cap 3 + budget), bind_skills, get_binding, why, estimate_tokens, doctor, archive_idle (dry-run), read_skill. 38 tests pass. No registry publish.