skill-fetch

Skill Fetch

Search, score, and install agent skills from multiple registries in parallel.

When to Use

• A skill-eval hook outputs "MISSING EXTERNAL SKILL"
• The current task requires domain expertise not available locally
• The user asks to "fetch skill", "search for a skill", or "install a skill"

Critical Rules

1. Never use skillsmp_get_skill_content to preview before deciding — search descriptions are sufficient. Only use as a fallback if installation fails.
2. Stop on first results, continue only on zero (max 5 rounds) — any round with ≥1 result proceeds to analysis.
3. Only the user can decide to skip — the LLM must never skip installation on its own.
4. Always use plain-text interaction — do not use AskUserQuestion. Output analysis and wait for the user to reply with a number or command.
5. Show up to 5 results per page — with full analysis (content, pros, cons, repo URL) so the user can make an informed decision.

Platform Compatibility

This skill works across 6+ AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Amp). Tool names adapt automatically. See references/platform-adapters.md for the full mapping table.

Procedure

Step 0: SkillsMP MCP Self-Check (Claude Code only)

Before searching, verify that the SkillsMP MCP server is available:

1. First, try loading deferred tools: Run ToolSearch("skillsmp") to load any deferred SkillsMP MCP tools. In Claude Code, MCP tools are often deferred (not loaded until requested) and have namespaced names like mcp__skillsmp__skillsmp_search. The ToolSearch call resolves these.
2. After ToolSearch, check if any skillsmp_* or mcp__skillsmp__* tool is now available
3. If available → proceed to Step 1
4. If still not available → run: claude mcp add --scope user skillsmp -- npx -y skillsmp-mcp-server
5. Inform the user: "SkillsMP MCP server has been registered. It will be available after restarting the session. Continuing search with the remaining 7 sources for now."
6. Proceed to Step 1 (SkillsMP sources will be skipped this session, but available in future sessions)

Tool name note: SkillsMP tools may appear with MCP namespace prefix: mcp__skillsmp__skillsmp_search instead of skillsmp_search. Both forms work — use whichever is available.

Non-Claude Code agents: Skip this step. SkillsMP tools are Claude Code-specific.

Step 0.5: Load API Keys (MANDATORY — execute before Step 2)

Sources 8-9 require API keys. Read the config file to determine availability:

1. Read ~/.claude/skills/.fetch-config.json NOW — do not assume keys are absent without reading the file
2. Expected format:

``json { "SKILLHUB_API_KEY": "sk-sh-...", "SKILLS_DIRECTORY_API_KEY": "sk_live_..." } ``

1. Record the result — set two flags for use in Step 2b:
2. HAS_SKILLHUB_KEY: true/false
3. HAS_SKILLS_DIR_KEY: true/false
4. If config file does not exist → both flags = false, inform user they can create the file
5. If config file exists but a specific key is missing → that flag = false

⚠️ COMMON FAILURE MODE: LLM skips reading the config file and assumes "no key". This causes Sources 8-9 to be incorrectly skipped even when keys ARE configured. Always read the file first.

Step 1: Determine Search Keywords and Source

URL mode: If $ARGUMENTS is a URL (starts with https://github.com/... or any https://), skip directly to Step 3 installation flow.

Search mode:

• Has $ARGUMENTS: Use directly as search terms
• No search terms (auto-triggered): Prefer Suggested search terms from hook output, otherwise extract 2-3 queries from task context

Step 2: Parallel Search — ALL 9 Sources (mandatory)

⚠️ MANDATORY: You MUST fire ALL 9 sources. Do NOT proceed to scoring until all 9 sources have returned or failed.

⚠️ COMMON FAILURE MODE: LLM fires sources 1-2 (SkillsMP), gets results, then skips sources 3-9. This is WRONG. SkillsMP results alone are insufficient — GitHub, ClawhHub, skills.sh, and PolySkill contain different skills not indexed by SkillsMP.

⚠️ EXECUTION ORDER: You MUST complete BOTH Step 2a AND Step 2b before proceeding to Step 2.5. Step 2a alone is NOT sufficient.

Step 2a: Fire SkillsMP sources (1-2)

| # | Source | Tool Call | Fallback | |---|--------|-----------|----------| | 1 | SkillsMP AI | skillsmp_ai_search × 3 query variants (parallel) | Skip if MCP unavailable | | 2 | SkillsMP keyword | skillsmp_search(query) | Skip if MCP unavailable |

Step 2b: Fire non-SkillsMP sources (3-9) — DO NOT SKIP

⚠️ You MUST fire these sources even if Step 2a already returned results. These sources contain skills NOT in SkillsMP.

| # | Source | Tool Call | Fallback | |---|--------|-----------|----------| | 3 | GitHub repos | gh search repos "{query}" --json name,description,url,stargazersCount,updatedAt --limit 5 --sort stars (do NOT append "skill SKILL.md") | gh search code "{query}" --filename SKILL.md --limit 5 | | 4 | Anthropic Skills | gh search code "{query}" --repo anthropics/skills --filename SKILL.md --limit 5 | gh api tree fallback | | 5 | ClawhHub | npx -y clawhub search "{query}" | Skip on failure | | 6 | skills.sh | WebFetch("https://skills.sh/api/search?q={query}&limit=5") | curl -s via Bash | | 7 | PolySkill | npx -y @polyskill/cli search "{single_keyword}" --limit 5 (extract most specific single keyword from query — multi-word queries return 0) | Skip on failure (no REST API) | | 8 | SkillHub | If HAS_SKILLHUB_KEY = true (from Step 0.5): bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh "{query}". If false: npx -y @skill-hub/cli search "{query}" --limit 5 (timeout: 10000) | CLI fallback on failure | | 9 | Skills Directory | If HAS_SKILLS_DIR_KEY = true (from Step 0.5): bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh "{query}". If false: skip. Never use curl directly or WebFetch. | Skip only if key is confirmed absent in Step 0.5 |

⚠️ Sources 8-9 REQUIRE Step 0.5 to have been executed. If Step 0.5 was skipped, go back and read ~/.claude/skills/.fetch-config.json NOW before marking Sources 8-9 as skipped. {SKILL_BASE_DIR} = the base directory of this skill (shown at the top when skill loads).

See references/search-sources.md for detailed parameters, response formats, query variant examples, and curl fallback commands.

⚠️ POST-SEARCH CHECKLIST (mandatory before proceeding to Step 2.5):

Before scoring, output this checklist with actual status for EVERY source:

Step 0.5 config: HAS_SKILLHUB_KEY={true/false} HAS_SKILLS_DIR_KEY={true/false}
Sources queried: [1] SkillsMP AI ✅ [2] SkillsMP KW ✅ [3] GitHub ✅/❌ [4] Anthropic ✅/❌ [5] ClawhHub ✅/❌ [6] skills.sh ✅/❌ [7] PolySkill ✅/❌ [8] SkillHub ✅/❌ [9] Skills Dir ✅/❌

Validation rules — go back and fix before proceeding:

• If sources 3-7 are ALL ❌ → re-execute sources 3-7 NOW
• If HAS_SKILLHUB_KEY=true but [8] is ❌ → execute bash {SKILL_BASE_DIR}/scripts/fetch-skillhub.sh NOW
• If HAS_SKILLS_DIR_KEY=true but [9] is ❌ → execute bash {SKILL_BASE_DIR}/scripts/fetch-skills-directory.sh NOW
• If Step 0.5 was never executed (no config line above) → read ~/.claude/skills/.fetch-config.json NOW, then re-evaluate sources 8-9

After ALL sources return → deduplicate (see references/search-sources.md) → proceed to Step 2.5.

Round strategy (max 5 rounds): The "≥1 result → stop" rule applies to rounds, not individual sources. Within a single round, ALL 9 sources must be queried. Only if ALL 9 sources return 0 results in a round should you proceed to the next round with broader keywords. If any source returns ≥1 result in a round, proceed to scoring (do NOT start another round).

Step 2.5: Scoring and Ranking

Calculate a quality score (0-100) for each deduplicated result. See references/quality-signals.md for details.

Scoring formula: `Total = Relevan