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:

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

3. Record the result — set two flags for use in Step 2b:
   • HAS_SKILLHUB_KEY: true/false
   • 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 = Relevance(0-40) + Freshness(0-25) + Community(0-20) + Trust(0-15) + External Bonus(0-5)

Supplementary lookup: For the top 5 results, use gh api repos/{owner}/{repo} --jq '{pushed_at,stargazers_count}' to get update time and GitHub stars. Skip lookup for high-star (≥50) results with precisely matching descriptions. Maximum 3 gh api calls.

Grade labels: 🟢 85+ Strongly Recommended | 🟢 70-84 Recommended | 🟡 55-69 Worth Considering | 🟡 40-54 Marginal | 🔴 <40 Not Recommended

Step 3: Analyze, Select, Install

See references/installation-guide.md for the complete installation workflow.

Quick reference — flow:

1. 3a. Display sorted results (5 per page, score + pros/cons)
2. 3b. Wait for user reply (number to install, c for next page, skip to end)
3. 3c. Ask installation location (G=global, L=local) — MANDATORY
4. 3d. Execute installation (SkillsMP → trust-but-verify, GitHub → fetch the full bundle, not just SKILL.md, then pre-install scan every file). Use scripts/fetch-skill-bundle.sh for GitHub URLs.
5. 3e. Post-install verification (file existence, frontmatter, conflict check, bundle completeness, SHA-256 on every installed file)
6. 3f. Update ~/.claude/skills/.fetch-metadata.json
7. 3g. Activate and confirm with user

⚠️ Critical: When installing from GitHub, the skill is its entire directory — SKILL.md plus references/, scripts/, assets/, templates/, prompts/, data/, etc. Downloading only SKILL.md will produce a broken install for any skill that delegates to those files. Always fetch the complete bundle.

Step 4: Digest the Installed Bundle

An installed skill is a directory, not a single SKILL.md. Many skills split their content across subdirectories — references/ (docs), scripts/ (helpers), assets/, templates/, prompts/, data/, examples/, etc. If you only read SKILL.md you may miss instructions the skill author expects you to load on demand.

1. Use Glob to list the full installed tree: {install-path}/{skill-name}/**/*.
2. Verify bundle completeness. If SKILL.md references relative paths (bash scripts/foo.sh, See references/bar.md, Load assets/template.json) and those files are missing, the install is incomplete — re-run the GitHub bundle fetch (see references/installation-guide.md §3d).
3. Read files directly relevant to the current task (check the first 30 lines for relevance). Don't limit this to references/ — the relevant file may live under prompts/, templates/, or another subdir.
4. Summarize key knowledge for use in subsequent planning.

After completion, output: External skill installed successfully: {skill-name}

Completion Phrases

• Success: External skill installed successfully: {name}
• Skipped: External skill fetch: user chose to skip installation.

Additional Resources

Rationalization Table and Red Flags are in references/interaction-patterns.md. Consult when rationalizing skipping steps.

• references/interaction-patterns.md — Output templates, user reply handling, security review
• references/quality-signals.md — Quality assessment dimensions, lookup methods, ranking algorithm
• references/search-sources.md — Source-specific commands, error handling, deduplication rules
• references/platform-adapters.md — Cross-platform tool mapping, installation paths, fallback strategies
• references/installation-guide.md — Complete Step 3 installation workflow (3a-3g)
• references/local-index.md — Local skill/plugin scan implementation for pre-search deduplication
• scripts/fetch-skillhub.sh — SkillHub API search (reads key from ~/.claude/skills/.fetch-config.json)
• scripts/fetch-skills-directory.sh — Skills Directory API search (reads key from config)
• scripts/fetch-skill-bundle.sh — Download a complete skill bundle (SKILL.md + all sibling files/subdirs) from any GitHub blob/tree/raw URL, preserving directory layout