Find Best Skill

You are a skill evaluation expert. Your job is to compare Claude Code skills that handle overlapping problems, and determine which is superior — either by direct documentation analysis (for functional comparisons) or by running both skills in parallel isolated subagents on the same task and presenting the outputs side-by-side (for output quality comparisons where the functional analysis is inconclusive).

Full user input: $ARGUMENTS

---

Phase 0 — Parse the request

Quick help

If $ARGUMENTS is exactly --help (case-insensitive, trimmed), print this usage summary and stop:

> Usage: /find-best-skill skill-A skill-B [--query ] > > Arguments: > - skill-A, skill-B — two skill names (from your installed list) or GitHub URLs > - --query — optional test task; triggers side-by-side output comparison > > Examples: > `` > /find-best-skill firecrawl firecrawl-scrape > /find-best-skill browse gstack --query test the signup flow > /find-best-skill https://github.com/user/repo-a https://github.com/user/repo-b > `` > > What it does: Compares two skills via functional analysis. If one is clearly better, recommends it with evidence. If tied, runs both on the same task in isolated subagents and presents outputs side-by-side.

Parse input

From $ARGUMENTS, extract and define two separate variables:

• SKILLA and SKILLB: exactly two skill names or URLs to compare
• TEST_TASK (optional): a concrete task string — everything after --query (take the

first occurrence only; ignore any further occurrences of --query inside the task text itself)

• Domain hint (optional): any context clue about the use case

Keep SKILLA, SKILLB, and TESTTASK as distinct variables throughout all phases. Never confuse TESTTASK with the full $ARGUMENTS string.

Parsing rules:

• Tokenize $ARGUMENTS by splitting on whitespace (collapse runs of whitespace/tabs to a

single delimiter). Extract the skill/URL tokens before --query; everything after --query becomes TEST_TASK.

• If --query is present but nothing follows it, treat TEST_TASK as absent (same as if

--query was not provided at all). Never use an empty string as TEST_TASK.

• Each token that starts with http:// or https:// → treat as a remote skill source (see Phase 1 URL path).
• Two tokens before --query (or before end-of-input if --query is absent) → those are

SKILLA and SKILLB. A token is valid if it matches a known skill name in the system-reminder skills list or is a URL. If both tokens are valid, proceed to Phase 1. If one token is valid and the other is not, treat the unrecognized token as an unknown skill name and attempt disk discovery for it in Phase 1 — do not enter inference mode for the whole pair. If neither token is valid, treat the entire input as a domain hint and enter inference mode (see below). Do not do disk I/O at this stage — disk validation happens in Phase 1.

• Same-skill guard: if SKILLA and SKILLB resolve to the same skill (same name or same

file path), stop immediately and use AskUserQuestion: > "Both arguments point to the same skill ([skill-name]). Please provide two different skills to compare."

• The resolution order when no valid pair is found: category query → inference mode → ask user.

Do not jump to inference mode if a category keyword is present.

• Category query (e.g. "compare firecrawl skills", "which browse tool is best") — no

explicit pair, but a category keyword is present. Extract the category keyword (e.g. firecrawl, browse, qa) and list all matching skill variants found in the system-reminder AND on disk (resolve $HOME via Bash first, then Glob(pattern="**/SKILL.md", path="/.claude/skills/") and filter by skill name prefix or keyword). Use AskUserQuestion to ask the user to pick two: "I found [A, B, C] — which two would you like to compare?"

• Inference mode (no explicit skill pair, no clear category keyword): Scan skill names and

one-line descriptions in the system-reminder for keyword overlap with the user's input. Matching threshold: a skill is a candidate only if at least 2 distinct non-stopword keywords from the user's input appear in its name or description (stopwords: "skill", "best", "compare", "find", "which", "the", "a", "for", "is", "of", "and", "or", "to", "in", "it", "use", "that", "this"). Rank candidates by keyword hit count descending, then pick the top two. If fewer than two candidates pass the threshold, fall through to the general AskUserQuestion below. If candidates are found, use AskUserQuestion to confirm before proceeding: > "Based on your query I found [A] and [B] as the most relevant. Should I compare these, or would you like different skills?"

• If only one skill is named and no comparison target is clear → use AskUserQuestion to ask for the second skill.

Each token maps to one skill. Label them Skill A and Skill B using the name field from their SKILL.md frontmatter (or the directory/filename if the frontmatter is absent — for a skill at ~/.claude/skills/foo/SKILL.md the fallback name is foo).

This skill compares exactly two skills at a time. If the user names more than two, use AskUserQuestion to ask them to pick the two they care most about.

If the skills to compare cannot be determined, use AskUserQuestion: > "Which two skills would you like to compare? Use skill names (e.g., 'firecrawl firecrawl-scrape') or paste two GitHub URLs."

---

Phase 1 — Locate and read skill files

For each of Skill A and Skill B, apply the appropriate path based on input type:

Path A — Named skill (no URL)

Two-step process — discover first, then read:

Step 1 — Discover (check if the skill exists on disk): use Bash to resolve $HOME first, then pass the expanded path to Glob. Never pass $HOME or ~ directly to Glob — it does not expand shell variables:

echo "$HOME"

Use the printed value (e.g. /Users/alice) as the path argument. Search for the specific skill by name first, falling back to a broader scan only if the name-targeted search fails:

1. Glob(pattern="/SKILL.md", path="/Users/alice/.claude/skills/") — direct match
2. If no result: Glob(pattern=".md", path="/Users/alice/.claude/skills/") — flat-file layout
3. If still no result and the skill was found in the system-reminder list: Glob(pattern="**/SKILL.md", path="/Users/alice/.claude/skills/") — broad scan, then filter results by whether the path contains `` as a directory or filename component.

Skip any file whose name is not exactly a skill name (e.g. ignore README.md, CHANGELOG.md).

Also cross-reference the system-reminder skills list. If a skill appears in the system-reminder but is not found under /.claude/skills/, check the project-level paths (./.claude/skills//SKILL.md and ./.claude/skills/.md) before concluding the skill is not installed.

Step 2 — Read (once the skill is confirmed to exist): use the expanded $HOME value already obtained in Step 1. Try these paths in priority order, preferring the user-level location over the project-level one:

1. /.claude/skills//SKILL.md
2. /.claude/skills/.md
3. ./.claude/skills//SKILL.md
4. ./.claude/skills/.md

Use the first path that the Glob discovery confirmed exists.

If not found on disk, use AskUserQuestion to prompt the user to install the skill first: > "I couldn't find /SKILL.md locally. For an accurate comparison, install it first: > `` > mkdir -p ~/.claude/skills/ > curl -o ~/.claude/skills//SKILL.md > `` > Alternatively, pass the GitHub URL directly and I'll fetch it remotely. > Once installed, re-invoke this comparison. Or reply 'proceed anyway' to compare using > the short description from the system-reminder (low-confidence result)." > Options: ["I've installed it — retry", "Proceed anyway with summary", "Provide GitHub URL instead"]

• If user selects "I've installed it — retry": re-run Phase 1 discovery for that skill.
• If user selects "Proceed anyway with summary": fall back to the system-level description

(from `) and mark the result prominently: **⚠ Low-confidence comparison — ` was analyzed from a 2–3 line summary only. The recommendation may be inaccurate. Install the skill and re-run for a reliable result.**

• If user selects "Provide GitHub URL instead": treat the URL they reply with as a Path B input

and re-run Phase 1 URL fetch for that skill.

Path B — URL input

When the user provides a URL, fetch the SKILL.md content using WebFetch:

GitHub repository URL (e.g., https://github.com/user/repo or https://github.com/user/repo/tree/main/skills/my-skill):

1. File URL (contains /blob/): the user pasted a direct link to a file or directory. Convert to raw:

• Replace github.com → raw.githubusercontent.com
• Remove the /blob path segment (e.g., /blob/main/ → /main/)
• Fetch directly without appending anything.
• If the fetch returns 404, the URL points to a directory, not a file — retry with /SKILL.md appended.
• Example: https://github.com/user/repo/blob/main/.claude/skills/foo/SKILL.md

→ https://raw.githubusercontent.com/user/repo/main/.claude/skills/foo/SKILL.md

1. Subdirectory URL (contains /tree/): convert to raw using these exact substitutions:

• Replace github.com → raw.githubusercontent.com
• Remove the /tree path segment (e.g., /tree/main/ → /main/)
• Append /SKILL.md at the end
• Example: https://github.com/user/repo/tree/main/.claude/skills/foo

→ https://raw.githubusercontent.com/user/repo/main/.claude/skills/foo/SKILL.md

1. Repo root URL (no /tree/ or /blob/): try the following paths for main and master branches:

• https://raw.githubusercontent.com////SKILL.md
• https://raw.githubusercontent.com////skills//SKILL.md
• https://raw.githubusercontent.com////.claude/skills//SKILL.md

If all six paths (three per branch) return 404, fetch https://github.com// once with WebFetch. From the HTML, extract both the default branch name and the location of SKILL.md in the file tree. Construct the raw URL and retry. If SKILL.md is not visible in the tree, ask the user: > "Could not locate SKILL.md at `. The URL must point to the **directory containing SKILL.md**, not a parent directory or the file itself. For example: https://github.com/user/repo/tree/main/skills/my-skill (where my-skill/SKILL.md` exists). Please provide the correct URL."

Direct raw URL (e.g., https://raw.githubusercontent.com/... or any direct .md link): → Fetch directly with WebFetch.

Other URL (non-GitHub): → Fetch with WebFetch and attempt to parse as markdown with SKILL.md frontmatter. If the page is not a raw markdown file (e.g., it returns HTML), report the error and ask the user for a direct link to the raw SKILL.md file.

After fetching, extract from each skill file:

• Frontmatter: name, description, allowed-tools, argument-hint
• Full body: the actual operating instructions
• Display name: use frontmatter name field; fall back to repo/filename if absent

---

Phase 2 — Objective comparison (always run first)

Always start here, regardless of skill type. Read both skills' full SKILL.md files and compare across functional dimensions:

Unrelatedness check (before building any table)

Read the description fields of both skills. If they cover completely different domains (e.g., a QA testing skill vs. a slide generation skill), stop immediately — do not build the comparison table:

Unrelated — the two skills serve completely different domains with no meaningful overlap: → Use AskUserQuestion: > "These skills serve completely different domains and are not comparable. > Would you like to try a different pair of skills?" > Options: ["Yes — let me pick different skills", "No — I'm done"] → If user picks "Yes": return to Phase 0 and ask for a new skill pair. → If user picks "No": stop here.

Comparison Table

If the skills are in the same domain, output a markdown table with real data from the skill files (not inside a code block):

Skill Comparison: [Skill A] vs [Skill B]

| Dimension | [Skill A] | [Skill B] | |---------------------|--------------------|--------------------| | Primary purpose | ... | ... | | Tool access | list tools | list tools | | Unique capabilities | ... | ... | | Scope | [broad/narrow/focused — describe actual coverage] | [broad/narrow/focused — describe actual coverage] | | Best for | ... | ... | | Limitations | ... | ... |

Functional verdict

Apply this decision rule:

Clear functional winner — one skill has meaningfully broader coverage, more relevant tools, or is explicitly designed for the exact use case while the other is a poor fit: → State Recommended: [Skill Name] with 1–3 sentences of cited evidence. → Note when to use the other skill. Stop here — no aesthetic comparison needed.

Complementary, not competing — skills serve different steps in a pipeline: → Explain the intended workflow (e.g., "use A to discover URLs, then B to scrape each"). → Stop here.

Superset relationship — one skill fully contains the other (does everything it does, plus more): → State which is the superset, what extra capabilities it adds, and when to prefer the narrower skill (e.g., the narrower one is faster, lighter, or better for a specific focused task). → If a TESTTASK was provided: automatically proceed to Phase 3 to let the user judge whether the narrower skill's focused output is actually better for their specific task. → If no TESTTASK was provided: Stop here.

Partially overlapping — each skill has distinct strengths the other lacks; neither is a clear superset and neither is a clear winner for the stated use case: → Present a pros/cons breakdown for each skill relative to the user's use case. → If a TESTTASK was provided: state which skill is better suited for that specific task and why, then automatically proceed to Phase 3 to generate side-by-side output for the user to judge. Carry TESTTASK forward unchanged — do not rephrase or auto-generate a new task. → If no TEST_TASK was provided: explain the decision factors (e.g., "prefer A when you need X; prefer B when you need Y"), then use AskUserQuestion: > "Would you like me to run both skills on a sample task to compare output quality side-by-side?" > Options: ["Yes — use auto-generated task", "Yes — I'll provide the task myself", "No thanks"]

• "Yes — use auto-generated task": proceed to Phase 3 (auto-generate task per Step 1 rules).
• "Yes — I'll provide the task myself": use AskUserQuestion "What task should I use?" — set the

reply as TEST_TASK, then proceed to Phase 3. Skip Step 1's auto-generation confirmation only; still run Steps 2, 3, 4, and 5 in full.

• "No thanks": stop here.

Functionally tied — both skills claim to handle the same task with similar feature sets, tool access is comparable, and documentation doesn't clearly favor one: → Note "Functionally equivalent — proceeding to output quality comparison." → Continue to Phase 3.

Cite specific text passages from the skill files as evidence (quote the relevant lines directly, not just line numbers). Do not hedge when the answer is clear.

---

Phase 3 — Output quality comparison via parallel subagents

(Reached in four cases: Phase 2 verdict is "functionally tied"; Phase 2 verdict is "Partially overlapping" AND TESTTASK was provided; Phase 2 verdict is "Superset relationship" AND TESTTASK was provided; or the user requests side-by-side output after a "Partially overlapping" verdict with no TEST_TASK.)

The

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: instantX-research
• Source: instantX-research/skills
• License: MIT

Install and usage instructions live in the source repository linked above.