{
  "markdown": "# mcp-skill-search\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/tests-95%20passing-brightgreen)](https://github.com/PettHa/mcp-skill-search/actions)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/discover-plugins)\n\nToolSearch for skills. An MCP server that searches your `SKILL.md` files by keyword, exact name, or required-term filter — so the model can fetch a skill description on demand instead of paying its system-prompt cost on every turn.\n\n## When this helps you\n\n**In Claude Code specifically:** Claude Code already loads skill descriptions into the system prompt automatically (up to ~1% of the context window before falling back to names-only). With under 50 small skills you may not feel the cost. With 100+ skills, or descriptions over 200 chars each, it adds up. To force `names_only` mode and free that budget — while keeping `skill_search` as your description-on-demand fallback — run the bundled setup skill:\n\n```\n/optimize-skill-context\n```\n\nThe skill detects your platform and runs the appropriate command (`setx` on Windows; appends to `~/.zshrc`/`~/.bashrc` on macOS/Linux) — with your confirmation. Restart Claude Code afterward. Reverse with `/restore-skill-descriptions`.\n\nSlash-commands (`/skill-name`) keep working; descriptions are fetched via `skill_search` when the model needs them. If you'd rather set the env var manually:\n\n```bash\n# macOS / Linux\nexport SLASH_COMMAND_TOOL_CHAR_BUDGET=1\n```\n\n```powershell\n# Windows (persistent)\nsetx SLASH_COMMAND_TOOL_CHAR_BUDGET 1\n```\n\n**In other MCP hosts** (Claude Desktop, OpenAI Agents SDK, Gemini Code Assist): no native skill-loading exists. `skill_search` is the only way to surface skills. Point `SKILL_PATHS` at your skill directories and the tool finds them.\n\n## Install — Claude Code\n\n> Pending listing in the [official Anthropic marketplace](https://github.com/anthropics/claude-plugins-official). Once approved, install with:\n> ```\n> /plugin install mcp-skill-search@claude-plugins-official\n> ```\n> In the meantime, use one of the two paths below — both are fully functional.\n\n### Option A: Self-hosted marketplace (CLI users)\n\nIn a terminal, run `claude` to enter Claude Code, then:\n\n```\n/plugin marketplace add PettHa/mcp-skill-search\n/plugin install mcp-skill-search@mcp-skill-search\n```\n\n### Option B: VSCode extension users (`/plugin` not yet exposed)\n\nThe VSCode extension does not yet expose `/plugin`. Run the installer script instead — it does exactly what the CLI command does (clone into the plugin cache, register in `installed_plugins.json`, enable in `settings.json`):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/PettHa/mcp-skill-search/main/scripts/install-vscode.mjs | node\n```\n\nOr PowerShell:\n\n```powershell\niwr https://raw.githubusercontent.com/PettHa/mcp-skill-search/main/scripts/install-vscode.mjs -OutFile $env:TEMP\\install.mjs; node $env:TEMP\\install.mjs\n```\n\n### After install (any path)\n\n1. Fully restart Claude Code (close all VSCode windows + system tray; relaunch from Start Menu — \"Reload Window\" is **not** sufficient on Windows).\n2. Run `/mcp` to confirm `skill-search` is registered with `alwaysLoad: true`.\n3. Run `/optimize-skill-context` once to free your description budget (optional but recommended; see the Windows `setx` note inside the skill).\n\n> The plugin bundles two skills: `optimize-skill-context` (one-time setup) and `restore-skill-descriptions` (reverse). It auto-registers an MCP server pointed at the bundled `dist/index.js`. Default skill paths: `~/.claude/skills`, `<cwd>/.claude/skills`, `~/.claude/plugins`.\n\n## Install — Claude Desktop (manual)\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"skill-search\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-skill-search/dist/index.js\"],\n      \"env\": {\n        \"SKILL_PATHS\": \"~/.claude/skills\"\n      }\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/...` with your cloned repo path.\n\n## Install — OpenAI Agents SDK / Gemini Code Assist\n\nBoth support MCP via configuration — point them at the same `node dist/index.js` command with `SKILL_PATHS` env. Untested by us; PRs welcome.\n\n## Configure skill paths\n\n`SKILL_PATHS` accepts colon-separated (Unix) or semicolon-separated (Windows) paths. Globs are supported:\n\n```bash\nSKILL_PATHS=\"~/Documents/GitHub/*/.claude/skills:~/.claude/skills\"\n```\n\nThis expands at startup to every matching directory. Glob characters: `*`, `?`, `[`, `{`. Tilde is expanded to the home directory. Defaults (used when `SKILL_PATHS` is unset): `~/.claude/skills`, `<cwd>/.claude/skills`, `~/.claude/plugins`.\n\n## Tool: `skill_search`\n\n| Query form     | Example                          | Behavior                                                  |\n| -------------- | -------------------------------- | --------------------------------------------------------- |\n| Keyword        | `hetzner deploy`                 | Ranks all skills by score; returns top N                  |\n| Required-term  | `+browser playwright`            | Skills MUST match `browser` somewhere; ranked by `playwright` |\n| Direct lookup  | `select:auto-go,ship-to-prod`    | Returns those exact skills, score 0                       |\n\nReturns: `{ matches: [{ name, description, path, score, source }], query, total_skills, current_project }`. Description is the full frontmatter description, never truncated. `source` is one of `project | user | plugin | cross-project`. `current_project` is the absolute path to the active git-root (or CWD if not in a git repo).\n\n## How scoring works\n\nPorted 1:1 from Claude Code's internal `ToolSearch` algorithm (v2.1.x). Weights: exact-name-part match = 10, name-part substring = 5, full-name substring = 3, `whenToUse` word match = 4, `description` word match = 2. Required-term filter runs first; only skills passing it are scored. See [src/search/scoring.ts](https://github.com/PettHa/mcp-skill-search/blob/main/src/search/scoring.ts).\n\n## Repo-aware behavior\n\nWhen the same skill name exists in multiple repos (e.g. you have a `start-server` skill in both GAIN-MSP and GAIN-LANDING), the tool resolves the conflict using two signals:\n\n1. **Project boost**: skills under the current git-root's `.claude/skills/` get a `+5` score boost. They almost always rank above same-named cross-project skills.\n2. **Tie-tolerant dedup**: when a same-named cross-project skill matches the keyword query as well as the project version (raw match quality, ignoring boost), it surfaces alongside with its `source` field marked. You see \"the skill from your repo *and* its cousin from another repo, in case you meant the other one.\"\n\nSame logic applies to `select:` lookups — project version comes first; non-project siblings are appended.\n\n## Frontmatter contract\n\nRequired: `name`, `description`. Optional: `whenToUse`, `triggers`. Embedded colons and quotes in unquoted prose-style descriptions are tolerated via a recovery pass (matches Claude Code's permissive parsing). Malformed YAML still throws — see `tests/parseFrontmatter.test.ts` for examples.\n\n## Development\n\n```bash\ngit clone https://github.com/PettHa/mcp-skill-search\ncd mcp-skill-search\nnpm install      # `prepare` script auto-runs `npm run build`\nnpm test         # Vitest, 80+ tests\nnpm run dev      # rebuild on change\n```\n\n## Provenance\n\nThe scoring algorithm is a 1:1 port of Claude Code's `ToolSearchTool.searchToolsWithKeywords` (v2.1.88). The names-only env var (`SLASH_COMMAND_TOOL_CHAR_BUDGET`) is from `SkillTool/prompt.ts:31` — undocumented, may change in future Claude Code versions. License: MIT.\n\n## Status\n\nPrivate/local repo as of writing. Public release pending.\n",
  "bytes": 7775,
  "sha": "342f749ac7318840b02c2adaa9ccb5b70f463f1ef28e6ce994bf058cfd4c9233",
  "repo_slug": "pettha/mcp-skill-search",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_pettha_mcp_skill_search_mcp_skill_search_619200c0/readme"
}