skill_discovery_assistant v1.0.0

name: "skill_discovery_assistant" description: "Run a guided skill-picking session for any task: interview the requester to surface the real need, score candidate skills against a catalog-agnostic rubric, recommend the best fit with an honest scope, and log feedback so picks improve over time. Triggers on 'which skill should I use', 'help me find the right skill', 'recommend a skill for this job', or when building a skill-recommendation flow for an agent."

Skill Discovery Assistant

Purpose

Agents sit on catalogs of hundreds of skills and still grab the wrong one, or none at all. This skill is the method for picking the right skill for the job, from any catalog, without a fixed catalog of your own. It works for a human asking "which skill do I use for X", an agent choosing its own tooling, or a recommendation flow you build for others.

It does four things in order: a short needs interview, catalog-agnostic candidate matching with a written rubric, a scoped recommendation (including the honest "none of them fit"), and session feedback that validates the picks over time.

Workflow

1. Interview: surface the real need

Ask five questions, then stop. Open-ended first, converge at the end. The full script with a worked transcript lives in references/interview-script.md.

1. Goal in plain words. "What are you trying to get done?" Capture the outcome, not the method. If the answer names a solution ("I need the SEO skill"), ask why they think so, then proceed on the outcome.
2. Why it matters. "What happens if this goes wrong, and what does good look like?" Separates must-haves from nice-to-haves.
3. Inputs and outputs. "What do you start with, and what do you need in your hands at the end?" Defines the skill's working material.
4. Constraints. "Any limits: time, budget, permissions, things it must never touch?"
5. Out of scope. "What is explicitly NOT part of this?" Write the answer down. It catches more bad picks than any other question.

Rule: requirements are discovered, not given. If the requester cannot answer #1 in one sentence, drill one level deeper before matching anything.

2. Build a job profile

Condense the interview into a job profile, 6 lines max:

TASK:      <one-line outcome>
DOMAIN:    <finance | devtools | media | ops | ...>
INPUT:     <what the skill receives>
OUTPUT:    <what success looks like, measurable>
RISK TIER: <low | medium | high>  (high = money, publishing, deletion, accounts)
MUST-HAVE: <2-4 non-negotiable behaviors>

Risk tier matters: a high-risk task needs a skill with an explicit output contract and review step, not just a good keyword match. This follows the standing practice of gating irreversible actions.

3. Gather candidates, catalog-agnostic

Search each catalog you have access to using 3-5 keyword phrases derived from the job profile, not from the skill names you already know. Pull every candidate whose description plausibly touches the TASK line. Read the candidate's full SKILL.md, never just its description line. Catalog descriptions summarize; they do not tell you the workflow or the output contract.

Do not anchor on the first catalog. A weaker catalog match from the right category often beats a strong keyword hit from the wrong one.

4. Score against the rubric

Score each candidate 0-2 on five dimensions (full worksheet and worked example in references/matching-rubric.md):

| Dimension | 0 | 1 | 2 | |---|---|---|---| | Task fit | Wrong job | Adjacent job, needs adaptation | Built for this exact task | | Trigger clarity | Vague "use when" | Some trigger phrases | Triggers match the TASK line closely | | Workflow coverage | Missing key steps | Covers most, gaps noted | End-to-end, inputs to outputs | | Output contract | No stated output | Output implied | Explicit output contract matching OUTPUT line | | Trust signals | Unknown provenance | Known publisher, no reviews | Known publisher plus ratings, downloads, or signed |

Sum the scores. Anything under 6 is not recommended. If two candidates tie, prefer the one with the higher Workflow coverage score; a clear method beats a clever description.

Worked example: job "write a 1,200-word plain-English explainer of the EU AI Act for a newsletter." Candidates scored:

• long_form_research_writing — task fit 1 (research articles, not explainers), trigger 1, workflow 2, output 1, trust 2 = 7
• op_ed_writing — task fit 2 (explainer-style persuasion pieces, similar craft), trigger 2, workflow 1 (opinion arc, not explainer arc), output 2, trust 2 = 9
• technical_whitepaper — task fit 1, trigger 1, workflow 1, output 2, trust 1 = 6

Pick: op_ed_writing (9), runner-up long_form_research_writing (7).

5. Recommend with an honest scope

The recommendation has four parts:

1. Top pick and runner-up, with scores shown, so the reasoning is auditable.
2. What the pick will do well, tied to the MUST-HAVE lines.
3. What it will not do, tied to the out-of-scope line from the interview. This is the part that keeps agents from trusting a skill past its edges.
4. The "none fit" path, when nothing scores 6+: say so plainly and choose one of: compose two skills (name both and the seam between them), search a wider catalog, or write a brief for a new skill. Never recommend the 4 to be polite.

6. Log the session and close the feedback loop

After the pick, write one feedback entry (template in references/matching-rubric.md):

date | job profile (one line) | pick | score | outcome (worked / partial / wrong) | note

Outcomes come later: did the skill do the job? "Partial" and "wrong" are the valuable rows. Every 10 sessions, or monthly, review the log and adjust: reword trigger phrases that keep mismatching, note catalogs whose skills underperform their scores, and raise the bar on dimensions that keep predicting badly. This is the recommender feedback loop in miniature: explicit outcomes update the matching model, and coverage is watched so the loop does not narrow to the same five favorite skills.

Output Contract

A completed session returns all of the following:

• Job profile (the 6-line block)
• Candidate list with per-dimension scores and totals
• Recommendation: pick, runner-up, honest scope, and the "none fit" path when applicable
• Feedback-log entry, written immediately (outcome filled in after the skill is used)

Operating Rules

1. Never invent facts about a skill. Every claim about what a skill does comes from reading its SKILL.md or a verified review, never from its name or description alone. Unverifiable claims get cut or framed as your read of the evidence.
2. Read before scoring. A candidate is not scored on its description line; skim the workflow and output contract sections of its SKILL.md first.
3. Keep the interview to five questions. If the job is still unclear, one follow-up round, then pick the closest candidate and say the profile is thin.
4. Quality beats speed. If no candidate is a good fit, say so and take the "none fit" path. A weak recommendation costs more than a slow one.
5. Log every session, including skips. The feedback loop only works if misses are recorded.
6. Reuse the rubric as written. Adjust the dimension weights only after a log review shows a reason, not on a hunch mid-session.
7. Catalog-agnostic means exactly that. Never write recommendations that assume one catalog, one publisher, or one platform's skill set.