skillsmp-search

SkillsMP Skills Search

Search the SkillsMP marketplace (500K+ SKILL.md files harvested from GitHub) for an existing solution before building a new agent, command, or skill from scratch. Two modes: keyword search and AI semantic search.

Hard Rules

1. Confirm SKILLSMP_API_KEY is set before ANY call: [ -n "$SKILLSMP_API_KEY" ]. If empty/unset, do not call the API — show the setup message (Error Branches) and stop. Never fabricate results.
2. At most ONE keyword search + ONE AI search per topic. Never loop, retry, or paginate the same query hoping for better hits.
3. Read a skill's GitHub source (githubUrl) before recommending it — never recommend from the search snippet alone.
4. On any non-200 response (401/403, 429, other), take exactly the action in the Error Branches table — do not retry-loop, do not invent results.
5. Zero results is a valid outcome — say so and proceed to build from scratch.
6. Present results only in the Output Contract format below.

Phase 0 — Load Project Context

Read if present, skip silently if absent: CLAUDE.md or AGENTS.md. Use it to ground the query in the project's real stack (e.g. search go reviewer, not reviewer, for a Go project). Do not read it more than once per session.

When to Use

• Before writing a new agent — search if someone already built it.
• Before writing a new skill — check for community solutions.
• When exploring patterns — see how others solved a similar problem.
• When the user asks — "find a skill for X", "is there a skill that does Y".

Process

1. Preflight — run the key check (Hard Rule 1). Done-when: key confirmed present, or setup message shown and you stop.
2. Keyword search — run the keyword endpoint. Handle any non-200 per Error Branches. Done-when: you have a results list or a handled error.
3. AI search (conditional) — run ONLY when keyword results are poor/empty or the query is conceptual (e.g. "review code across multiple models"). Done-when: AI results obtained or keyword results judged sufficient.
4. Verify — for each skill you intend to recommend, open its githubUrl and read the actual SKILL.md. Done-when: every recommended skill's source was read.
5. Present — emit the Output Contract. Done-when: results rendered, or the zero-result / error message shown.