skill-picker

name	skill-picker
description	Recommends the best skill(s) to use for an ambiguous or multi-skill task by deep-verifying candidates against their SKILL.md contents, not just their one-line descriptions. Use when the user asks 'which skill should I use', 'what skill is best for X', 'help me pick a skill', 'find the right skill', 'what's the most targeted skill', or when several installed skills seem to overlap and the right choice isn't obvious. Also use proactively when a user's task could plausibly match 3+ skills with similar descriptions and you're genuinely uncertain which to reach for. Returns a structured recommendation with rejected candidates, better matches quoted from their actual descriptions, a primary skill + optional chain + tactical follow-up, and a handoff gate.
argument-hint	[what you want to work on]
allowed-tools	Read, Glob, Grep, AskUserQuestion

Skill Picker

Deliberate cross-skill reasoning for when auto-selection isn't good enough. The core insight: descriptions can lie. A skill's one-liner says X, but its SKILL.md does Y. Shallow matching fails exactly when it matters most — when the task is ambiguous and several skills seem close. This skill forces deep verification before recommending.

Quick Start

Example invocations:

"/skill-picker help me brainstorm where to add color to my portfolio site" "/skill-picker which of my skills should I use to audit UI copy" "/skill-picker I want to review an existing component for polish — what's best"

The user passes a task description. You return a structured recommendation.

---

How This Skill Thinks

1. Descriptions are hypotheses, not facts. A one-line description is how a skill wants to be invoked. The SKILL.md is what it actually does. Always verify finalists by opening the file.

2. The model already rejected some candidates silently. When shallow auto-selection picks 3-5 candidates, it's worth asking: what did it miss? The screenshot failure mode (4 obvious picks were all wrong, 3 better ones lived outside the obvious set) repeats often.

3. Quote word-for-word, from two sources. Never paraphrase. For each recommendation, the user should see both (a) the skill's description verbatim and (b) a short verbatim phrase from its SKILL.md body. The body quote is the fingerprint proving you deep-read. Paraphrasing is where hallucination lives, and description-only is where freestyle guessing lives.

4. Recommend chains, not just singles. Many real tasks need a primary skill + a follow-up (e.g., i-colorize then visual-taste as a taste filter, then oklch-skill for value picking). Surface these explicitly.

5. Never recommend a skill that doesn't exist in the user's available-skills list. If you can't point to it in the current context reminder, it isn't installed. Don't invent skills from training data.

---

The Algorithm

Step 1 — Intake

Read the user's $ARGUMENTS as the task they want help with. If arguments are empty, ask one question:

What task are you trying to accomplish? Describe it in your own words — I'll match it against your installed skills.

Step 2 — Shallow Pass (candidate shortlist)

Look at the available skills list in your current context (the <system-reminder> block that lists skills, or the tool harness's available-skills section). Do not invent skills. Only reason from what's actually listed.

Scan all skill names + one-line descriptions. Pick 3-5 candidates that plausibly match the task. Include both obvious fits and non-obvious ones — the failure mode is missing a non-obvious better match.

Also identify 2-3 "obvious but probably wrong" candidates — skills that look like a fit on first glance but might be too broad, too narrow, or aimed at a different problem. You'll explain why you rejected them.

Step 3 — Deep Verify (read SKILL.md for each finalist)

For each of the 3-5 shortlisted candidates, locate and read its SKILL.md. Try paths in this order:

1. User-level: ~/.codex/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md, then ~/.agents/skills/<name>/SKILL.md
2. Project-level: ./.codex/skills/<name>/SKILL.md, ./.claude/skills/<name>/SKILL.md, then ./.agents/skills/<name>/SKILL.md relative to the current working directory
3. Plugin-provided (names with colon like compound-engineering:ce-work): Glob for ~/.codex/plugins/**/skills/<skill-part>/SKILL.md, ~/.claude/plugins/**/skills/<skill-part>/SKILL.md, or broader ~/.codex/**/skills/<skill-part>/SKILL.md / ~/.claude/**/skills/<skill-part>/SKILL.md matches — the part after the colon is the skill name.

If you cannot locate a skill's file, note it in the output (don't fabricate its contents).

For each SKILL.md opened, scan its workflow/instructions body (not just frontmatter) and look for one of these five mismatch patterns:

The Mismatch Taxonomy

1. Over-scoped description — The one-line description implies broad capability, but the workflow only handles a narrow slice. Detector: description says "polish" or "audit" or "review" but the workflow's Phase 1 asks for specific artifacts (screenshots, a component file, a specific framework).

2. Outdated trigger list — The trigger keywords listed in the description don't match what the workflow actually branches on. Detector: description lists keyword X, but "Mode A vs. Mode B" routing inside the skill never looks for X.

3. Hidden prerequisite — The workflow assumes installed tooling, a design system, a file structure, or a prior skill output that the description never mentions. Detector: Phase 1 of the workflow says "ensure you have X installed" or "paste the output of skill Y here" but the description makes no mention of X or Y.

4. Output mismatch — The description promises one kind of artifact; the workflow produces something different. Detector: description says "recommends..." but the final phase writes files, or description says "generates code" but the workflow outputs a markdown report.

5. Audience or tone drift — The description sounds generic, but the workflow is calibrated to a specific user, stack, or aesthetic. Detector: principles or examples in the workflow name specific people, companies, or frameworks the description didn't mention.

For each finalist, record:

• Actual scope (one sentence from reading the workflow, not the description)
• Mismatch pattern(s) found, if any — cite by name from the taxonomy above
• Evidence quote — a short phrase (5-15 words) copied verbatim from the SKILL.md body, with a rough section reference. This is the fingerprint proving you deep-read; include it in the output.

Worked Example

User task: "help me polish my API documentation"

Shortlist includes i-polish (description: "Final quality pass before shipping. Fixes alignment, spacing, consistency, and detail issues that separate good from great.").

Shallow read: sounds like a match — polish is polish, right?

Deep read of i-polish/SKILL.md reveals Phase 1 asks for a screenshot of the UI and Phase 2 references "optical alignment" and "border radius." The workflow is calibrated to visual UI polish, not documentation polish.

Mismatch pattern: Over-scoped description ("polish" is broader than what the skill does).

Output line: "i-polish — Over-scoped description. Workflow body calls for 'optical alignment' and 'visual hierarchy', aimed at UI not prose. Not a fit."

That quoted phrase is the fingerprint. Without it, the rejection is freestyle.

Step 4 — Structured Recommendation

Produce the output using the template below. Use the exact structure.

Step 5 — Handoff Gate

After the recommendation, ask the user how they want to proceed using AskUserQuestion with these three options:

1. Invoke the primary skill now — Hand off directly to the recommended skill with the original task prompt
2. Generate a plan first — Write a full markdown plan document showing how the recommended skill (plus any chain) will be applied to the task, so the user can review before running anything
3. Just the recommendation — Stop here; the user will invoke manually when ready

---

Output Template

Use this exact structure. Copy the shape; fill in the content.

Out of your [N] likely candidates, [none / only one / two] is the right fit for this task. Here's my read:

### Why these candidates aren't ideal

Each rejection must cite one of the five mismatch patterns and include an evidence quote from the skill's SKILL.md body (not its description).

- **`skill-name-1`** — [Mismatch pattern name]. Evidence from its workflow: *"short quote, 5-15 words"*. [One-line conclusion.]
- **`skill-name-2`** — [Mismatch pattern name]. Evidence: *"quote"*. [Conclusion.]
- **`skill-name-3`** — [Mismatch pattern name]. Evidence: *"quote"*. [Conclusion.]

*(If you couldn't locate a skill's SKILL.md, explicitly tag the line as `description-only — file not located` instead of faking evidence.)*

### Better matches

Each recommendation must include BOTH (a) the skill's description quoted word-for-word AND (b) a second quote from its SKILL.md body showing the actual workflow aligns.

1. **`better-skill-1`**
   - Description: *"exact text from the description field"*
   - Workflow evidence: *"short quote from the body, 5-15 words"*
   - Why it fits: [one sentence]

2. **`better-skill-2`**
   - Description: *"..."*
   - Workflow evidence: *"..."*
   - Why it fits: [one sentence]

3. **`better-skill-3`**
   - Description: *"..."*
   - Workflow evidence: *"..."*
   - Why it fits: [one sentence]

### My recommendation

**Primary:** `better-skill-1` as the main lens.
**Chain (optional):** Follow with  to [specific reason — e.g., "filter through your taste preferences"].
  unless [specific condition that would trigger it].



Once you've landed on a direction,  is the right tool for [specific downstream step — e.g., picking actual color values].

---

Want to proceed?

The evidence quotes are non-negotiable. They are the audit trail proving you actually opened each skill's file. Without them, the recommendation is unverifiable — it might as well be default model guessing.

After this output, trigger the handoff gate (Step 5).

---

Handoff Modes

Mode A: Invoke the primary skill now

Hand off by invoking the recommended skill via the Skill tool with the user's original task as the argument. If the recommendation includes a chain, only invoke the primary — let the chained skill fire separately after the primary completes.

Mode B: Generate a plan first

Write a full markdown plan document with this structure and present it inline:

# Plan: Applying [primary-skill] to [task]

## Context
[2-3 sentences restating the user's task and what they're trying to accomplish.]

## Recommended workflow

### Step 1 — Run `primary-skill`
- **What this does:** [summary]
- **Expected output:** [what the user will see]
- **Input:** [how to invoke — e.g., "/primary-skill <task description>"]

### Step 2 — Chain `secondary-skill` (if primary converges on X)
- **Trigger condition:** [when to run this, when to skip]
- **What this does:** [summary]
- **Expected output:** [what the user will see]

### Step 3 — Tactical follow-up with `tactical-skill`
- **What this does:** [summary]
- **Input:** [how to invoke]

## Decisions the user needs to make
- [Decision 1 — what to choose and when]
- [Decision 2]

## What this plan intentionally skips
- [Alternative approach 1] — reason for skipping
- [Alternative approach 2] — reason for skipping

After writing the plan, ask:

Plan looks good? I can kick off Step 1 now, or you can run it manually.

Mode C: Just the recommendation

Stop. The user will invoke manually.

---

Gotchas

Common failure points — where this skill gets it wrong:

• Don't skip the deep-verify step on finalists. The whole value of the skill is catching description-vs-reality mismatches. A shallow-only pass is what the model does by default — adding a skill that just does the shallow pass again is worthless.

• Don't recommend skills that aren't in the user's available-skills list. Training data includes skill names from docs and public repos. If the skill isn't in the current context reminder, it isn't installed. Don't hallucinate.

• Don't paraphrase descriptions when recommending. Quote word-for-word from the skill's actual description field. Paraphrasing drifts the meaning and loses user trust when they notice.

• Don't recommend skill-picker itself as a candidate. Exclude this skill from the pool on every pass. Exception: if the user seems genuinely lost on a meta-task like "I can't figure out which of my skills do what" — then it's appropriate to point them at this skill. But never recommend it for an object-level task.

• Don't auto-chain without the handoff gate. The structured output is a recommendation, not an instruction. Always go through the handoff question before invoking anything. Exception: if the user's original prompt explicitly said "pick the right skill and run it" — then you have pre-authorization and can skip the gate.

• Don't treat plugin-prefixed skills as user-level. A name like compound-engineering:ce-work means the file lives in a plugin directory, not directly under a user-level skills/ folder. Use Glob to find it — don't assume a path.

• Don't recommend more than 3 skills as "better matches." If you're returning 5+ options, you haven't actually picked — you've passed the buck back to the user. Pick.

• Don't reason about skills without reading their SKILL.md. If you couldn't locate the file, say so explicitly in the output ("couldn't locate SKILL.md for X — reasoning from description only"). Don't pretend you read it.

• Don't force a "rejected candidates" section when the first-pass picks were actually correct. If the obvious candidates genuinely are the right answer, say so: "The obvious candidates were right. Here's why." The skill's value is rigorous analysis, not manufactured contrarianism.

• Don't skip the evidence-quote requirement. Every finalist in the output must include a short verbatim quote from the skill's SKILL.md body — not from its description. This is the audit trail that proves you deep-read. If a reader can't point to which file each quote came from, you've freestyled. The only legitimate exception is when a skill's file couldn't be located: in that case, tag the line explicitly as so the user knows.

---

Scope: What This Skill Considers

This skill should consider skills from all three locations:

1. User-level skills — ~/.codex/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md, and ~/.agents/skills/*/SKILL.md
2. Project-level skills — ./.codex/skills/*/SKILL.md, ./.claude/skills/*/SKILL.md, and ./.agents/skills/*/SKILL.md when a current project has them
3. Plugin-provided skills — Appear in the available-skills list with colon-prefixed names (plugin:skill-name). Located via Glob in plugin directories.

The available-skills list in the current context is the authoritative source of "what's installed right now." Start from that list. Do not attempt to recommend from memory of past installations.

---

Working With Incomplete Information

If the user's task description is too vague to do meaningful matching:

Your description is pretty open-ended. A few specifics would sharpen the pick:

• What's the artifact you're working on? (component, page, full site, doc, etc.)
• What's the goal? (polish, build from scratch, audit, refactor, explore)
• Any constraints? (specific framework, design system, platform)

Don't guess — wrong matches waste more time than asking.