Task-to-skill matcher

Purpose: Provide one consistent flow for choosing the best installed skill for a user task. Use this when the user asks "what skill should I use?", asks to "pick the best", or when skill choice is unclear.

When to use this skill

• User asks for skill recommendation or best-skill selection.
• Task-to-skill match is uncertain.
• User asks to auto-pick skills for a multi-step or batch run.

Do not use this skill

• If user names a specific skill to run, load that skill directly and skip this matcher.

Sources and scope

• Read installed-skill candidates from the current platform's context loader/index (see

  _localsetup/docs/PLATFORM_REGISTRY.md

  ).
• Cursor:

  .cursor/rules/localsetup-context-index.md

  (or skills section of

  .cursor/rules/localsetup-context.mdc

  ).
• Claude Code:

  .claude/CLAUDE.md

  .
• Codex:

  AGENTS.md

  .
• Other platforms: workspace context per platform registry (see PLATFORM_REGISTRY.md).
• Use public-skill suggestions from

  _localsetup/docs/PUBLIC_SKILL_INDEX.yaml

  .

Mode detection

• Treat as batch when user request includes multiple distinct subtasks, or says "batch", "multiple steps", or "run the whole thing".
• Otherwise treat as single task.

Workflow

1. Collect intent

   • Extract user intent and any task constraints.
   • If user already named a skill, stop matching and load that skill.

2. Rank installed skills

   • Compare intent against each installed skill's "when to use" text.
   • Rank by relevance (keyword and description relevance).
   • If uncertain, prepare top 3 candidates with one-line "why it fits".

3. Single-task flow

   • If one clear installed match exists, ask once: "Use this skill?"
   • Same turn: include up to 3 complementary public skills (one-line reason each).
   • If public index is missing or stale, still show match and "Use this skill?" first, then ask: "Complementary suggestions need the public index. Want me to refresh it now so I can recommend installable skills?"

4. Batch / long-running flow

   • Prompt once at start with options:
     • Auto-pick best skill for the whole run.
     • Parcel-by-parcel prompts.
     • Parcel auto-pick.
   • If auto-pick is chosen, show planned skill sequence first (best-effort), then proceed without repeated skill prompts.
   • If user chooses parcels and phases are unclear, propose one parcel (whole task), then ask prompt-vs-auto-pick for that parcel.

5. No installed fit

   • State that no installed skill is a good fit.
   • Offer up to 3 complementary public skills to import.
   • Optionally suggest creating a new skill with

     localsetup-skill-creator

     .

Public index rules

• Stale definition:

  _localsetup/docs/PUBLIC_SKILL_INDEX.yaml

  missing, missing

  updated

  , or

  updated

  older than 7 days.
• For complementary suggestions: return up to 3 public skills, each with one-line fit reason.
• To import suggestions, point user to

  localsetup-skill-importer

  (or run it if user asks).

Output style

• Keep outputs short, actionable, and consistently structured.
• For uncertain match: show top 3 installed candidates, each with one-line reason, then ask user to choose or say "pick the best".
• For single clear match: ask once, then show complementary public options in the same response.
• For public complementary suggestions, use available enriched fields from

  _localsetup/docs/PUBLIC_SKILL_INDEX.yaml

  :
  • Prefer

    summary_short

    over raw description.
  • Include notable

    requirements

    or

    risk_flags

    in one short line.
• Rendering fallback:
  • Rich/basic markdown: numbered list with labeled fields.
  • Plain text/ascii: numbered list with

    Skill:

    ,

    Why:

    ,

    Risks:

    .

References

• _localsetup/docs/TASK_SKILL_MATCHING.md

• _localsetup/docs/SKILLS_AND_RULES.md

• _localsetup/docs/PLATFORM_REGISTRY.md

• _localsetup/docs/PUBLIC_SKILL_INDEX.yaml

• localsetup-skill-importer

• localsetup-skill-creator