SkillSearch

Find and surface the right Claude Code skill — automatically. Indexes every skill across all your installed plugins, searched instantly at every prompt.

(demo GIF coming soon)

The problem

Claude Code ships with 1700+ skills — but your agent sees only a fraction of them.

Two limits cut most skills out of view:

• skillListingBudgetFraction caps the skill listing at roughly 1% of the context window. On a 200k-token model that is ~2000 tokens — enough for maybe 60–80 skills, not 1700+.

• Description truncation: least-recently-used skills get their descriptions dropped entirely. The agent sees the name but not what the skill does.

Result: skills like impeccable, stop-slop, deep-research, and hundreds of plugin-bundled skills are invisible to the agent unless it happens to know the exact name.

SkillSearch fixes this by building a complete local index and routing skill lookups through BM25 search — so the agent finds impeccable when it needs copy polish, not just when someone types /impeccable.

Related MCP server: Skills MCP Server

What SkillSearch does

One index. Three surfaces.

~/.claude/skills/
~/.agents/skills/          ──► buildIndex() ──► SKILLS-INDEX.json
installed_plugins.json /                              │
  plugin caches                                       │
                                         ┌────────────┴────────────┐
                                         │                         │
                                   MCP tool                    CLI
                                skill_search            skillsearch search
                                (agent calls it)        (you call it)
                                         │
                                    hooks (auto)
                                SessionStart + UserPromptSubmit
                                inject top matches into context

• Index — scans ~/.claude/skills, ~/.agents/skills, and plugin caches discovered via installed_plugins.json. Deduplicates, namespaces plugin skills, parses YAML frontmatter.

• BM25 search — MiniSearch with name-boosted scoring. Finds impeccable for "polish prose", stop-slop for "remove filler", deep-research for "thorough web research".

• MCP tool — skill_search(query, top_k?) — the agent calls this when it needs to find a skill. Returns a text list of matching skills with name, description, and source.

• CLI — skillsearch search "<task>" for humans. skillsearch index [--if-changed] to refresh.

• Hooks — SessionStart prints a rotating generic nudge to use skill_search and fire-and-forget refreshes the index if stale; UserPromptSubmit runs BM25 on the actual prompt and injects up to 3 matching skill pointers into the system prompt (no injection when no match clears the pollution-guard threshold).

Install

Not on npm yet. Until skillsearch is published, use the clone-based install below. (npx skillsearch … will work once published — the name is reserved.) The index is built locally from your installed skills on first run; nothing is bundled, so your skill inventory never leaves your machine.

Option A — Claude Code plugin (recommended)

# Clone + install deps (needed so hooks and the MCP server have their Node deps at runtime)
git clone https://github.com/TheQmaks/skillsearch
cd skillsearch && npm install

# Register as a plugin marketplace, then install
/plugin marketplace add https://github.com/TheQmaks/skillsearch
/plugin install skillsearch

The plugin wires up the MCP skill_search server and both hooks via .mcp.json and hooks/hooks.json. The SessionStart hook builds the index on first run and refreshes it when it goes stale.

Option B — standalone CLI + MCP (any project)

git clone https://github.com/TheQmaks/skillsearch
cd skillsearch && npm install

node bin/cli.mjs index                                   # build the index for your machine
claude mcp add skillsearch node "$PWD/src/mcp-server.mjs" # expose skill_search to the agent

Usage

# Search for a skill
skillsearch search "product copy review"
# | skill | description |
# | --- | --- |
# | `impeccable` | Polish prose and remove filler words |
# | `stop-slop` | Ruthless filler-word removal |
# | `copy-editing` | Line-level editing for clarity |

# Rebuild the index (full)
skillsearch index

# Rebuild only if skills have changed since last index
skillsearch index --if-changed

# Ask "which skill should I use for X?"
skillsearch which "thorough web research"

MCP tool (called by the agent):

skill_search(query: string, top_k?: number) → text listing matching skills (name, description, source)

Hooks — no configuration needed after install. Control injection verbosity:

Injection is deliberately high-precision: the per-prompt hook stays silent unless a match clears a conservative BM25 threshold (filler words are filtered out first), so it never pollutes context on chatty or off-topic prompts. Borderline relevance is left to the skill_search tool.

Config

How it works

Every prompt                    Agent tool call             CLI / human
      │                               │                          │
      ▼                               ▼                          ▼
UserPromptSubmit hook          MCP skill_search          skillsearch search
      │                               │                          │
      └──────────────────────────────►│◄─────────────────────────┘
                                      ▼
                              loadIndex(SKILLS-INDEX.json)
                                      │
                              BM25 search (MiniSearch)
                              name boost × 2, top-k results
                                      │
                              ┌───────┴───────────────┐
                              │                       │
                        inject into            return to caller
                        system prompt          (tool / CLI output)
                        (seen-skill filter,
                         pollution guard)

The index is built once and loaded from disk on each search call. On a warm file-system cache, search latency is under 10 ms for 1684 skills.

Design & research

Full design spec and architecture decisions: docs/superpowers/specs/2026-06-28-skillsearch-design.md

Implementation plan: docs/superpowers/plans/2026-06-28-skillsearch-v0.1.md

License

MIT