skill-finder — local, zero-token skill & tool search

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Cluster arbitration — when two local skills look interchangeable

This table is authoritative for the clusters below. Load the named skill, not its neighbour, and treat the listed skill as out of scope for the other cases.

Before adding a skill to a cluster, check that no listed member already covers the same trigger; if one does, extend that skill or its bounds instead.

Picking the right skill/tool for a task is retrieval, not reasoning — so it should not cost paid cloud tokens. This module does the search locally and leaves the cloud model free for the actual work.

Two tiers

• Tier 0 — lexical matching: lexical + fuzzy match over each skill's name, description, tags, triggers and full SKILL.md body. Deterministic.
• Tier 1 — optional configured model: for ambiguous queries, a local model (via [[llm-backends]]) re-ranks the shortlist. Still no cloud spend.

Use it

python -m skills.skill_finder.cli "optimize slow postgres queries"
python -m skills.skill_finder.cli "set up an A/B test" --local      # local-LLM rerank
python -m skills.skill_finder.cli "audit dead code" --roots ~/.claude/skills --json

from skills.skill_finder import find
r = find("decide local vs cloud routing", top_k=5)
r.get("cloud_tokens") # runtime-reported field; not total host usage
r["matches"]        # [{name, score, why, description, path, tokens_est}, …]

--roots points at any directory tree containing SKILL.md files (your global skill library, a project's skills, etc.); defaults to this repo's skills/. Works whether or not a SKILL.md has YAML frontmatter — the body is always indexed.

Evaluate a shortlist

Use the installed runtime to rank candidate instructions, then check that the selected workflows actually fit the task. Compare loaded context and outcome quality against a declared baseline. The host agent may still consume model tokens to choose and follow instructions; this catalog supplies no measured saving.

Exposed via [[llm-mcp]] as the find_skills tool. Related: skill_project_optimizer (rule-based per-project filtering), auto_router.