Skill Selector

Skill Selector

Adding a skill is cheap on disk and not free in context. Pick deliberately.

This skill separates two concerns:

1. Selection from a curated catalog — fast, opinionated, mostly enough.
2. Search-and-evaluate — broader, slower, only when phase 1 doesn't fit.

Run them as distinct passes. The catalog has been pre-vetted. Outside-catalog skills haven't, and need explicit evaluation before adoption.

When to use

• Starting a new project / new repo and you want it stocked with the right skills
• Mid-development, when a recurring task type is uncovered (suddenly need Playwright, suddenly need release automation)
• A slash command or another skill hints at a downstream skill not yet installed

When NOT to use:

• One-off task that won't recur — solve it inline; don't install a skill you'll never trigger again
• The project already lists the relevant skill in apm.yml — re-check before searching

Phase 1 — Curated catalog

The catalog lives in references/catalog.md. It is grouped by project signal (language / tool / process), with apm install strings inline.

Workflow:

1. Read references/catalog.md.
2. Identify project signals from three sources:
   • Repo files: package.json (Node), moon.mod.json (MoonBit), gleam.toml (Gleam), flake.nix (Nix), .github/workflows/ (CI), Playwright config, dotenvx keystore.
   • Stated user intent: in-message cues like "we plan to deploy to X", "we publish a small npm utility eventually".
   • CLAUDE.md mandates: persistent rules in user-level ~/.claude/CLAUDE.md or project-level CLAUDE.md (e.g., "task runner: justfile", "lint: ast-grep") count as signals even when the scenario text is silent. When mandate and stated intent disagree, surface the conflict to the user before installing. In the proposal, label mandate-driven rows explicitly (e.g., # from ~/.claude/CLAUDE.md: task runner = justfile) so a reviewer doesn't mistake them for padding.
3. Confirm with the user before installing — propose, let them subtract. Default to fewer skills, not more. Each skill consumes context every conversation.
   • Non-interactive contexts (subagent dispatch, scripted automation, batch runs): emit the proposal as the deliverable and stop. The caller subtracts. Do not stall waiting for a confirmation that will not come.
   • Active-in-language heuristic: if the user is actively writing code in a language with a <lang>-practice skill in the catalog (e.g. moonbit-practice, gleam-practice), include it. If they only consume a single binding or dep written in that language, hold off.
   • Platform-name caveat: when a catalog row's description names a specific CI provider / runtime / cloud:
     • Project platform matches: adopt as-is. Do not re-read the underlying SKILL.md; the catalog row already answered the question.
     • Project platform differs: read the underlying SKILL.md before deciding. The core capability may still apply — install for that core, note "integration glue N/A." Skipping for platform mismatch alone is wrong.
     • If you cannot read the underlying SKILL.md (no local install, no upstream clone, no network): do NOT silently skip the check. Surface the uncertainty in the proposal explicitly — e.g., note "adopting <skill> based on its catalog description; the SKILL.md was not consulted, so the core-vs-integration split is unverified." The user can then decide whether to verify before committing the install. Silently dropping the verification leaves a bug (the wrong skill adopted, or a usable skill rejected) that no later step recovers.
   • Out-of-band rows: rows tagged (out-of-band) in the catalog cannot be installed via public APM (chezmoi-local, gated, etc.). Mention them in prose if the project would benefit, but do NOT put them in apm.yml.
4. Install via APM. Read apm-usage first to confirm the exact apm.yml syntax — the manifest format is non-trivial and field names should not be inferred from this skill alone.
   • Project scope: edit apm.yml, run apm install. Commit apm.lock.yaml.
   • Global scope: apm install -g <repo>/<path>, verify in ~/.apm/apm.yml.
   • targets: declaration is required. APM 0.12+ does not fall back to a default target when no marker directory (.claude/ / .github/ / etc.) exists at the repo root — apm install errors out asking for an explicit choice. Write targets: [claude] (or whatever the host harness is) in apm.yml unconditionally; do not rely on directory auto-detection.
   • targets: does not strictly gate deploy directories. Even with targets: [claude], APM 0.12+ may also write to .agents/skills/ alongside .claude/skills/. Inspect the apm install output (Skill integrated -> ...) and treat every listed path as a deploy target for the gitignore decision below.
   • Pinning: catalog entries do not carry tags. Resolve a concrete tag or SHA via apm view <repo> (or check the upstream repo's release page) before committing apm.yml. Floating refs are listed under Common mistakes.
5. Decide the gitignore policy before the first commit. apm install auto-adds apm_modules/ to .gitignore but does NOT add the deploy targets. Pick one and stick to it:
   • Commit deploy targets (.claude/skills/, .agents/skills/, …): repo is self-contained, teammates / CI can clone without running apm install. Cost: file count balloons (7 skills ≈ 700 files in a recent utels install). Choose when teammates may not have APM, or when you want skill content reviewable in PRs.
   • Gitignore deploy targets: leaner repo; teammates run apm install --frozen-lockfile after clone. Add the exact paths emitted by apm install (e.g., .claude/skills/, .agents/skills/). Caveat: if the project also keeps local skills under the same directory (.claude/skills/<local-skill>/), gitignore only the APM-managed subpaths, not the whole directory.
   • Always commit apm.yml and apm.lock.yaml regardless. Without the lockfile the install is not reproducible — the deploy-target gitignore choice only changes whether the generated artifacts live in git.
   • Propose the choice to the user when the install lands the first APM skills in the repo. Don't silently pick — file-count bloat vs. clone-time install are both legitimate but the trade-off is repo-specific.
6. If a need is unmet, escalate to Phase 2. Do not skip Phase 1 — even if a search query is already forming in your head, scanning the catalog is cheaper.

Phase 2 — Search and evaluate (delegated to skill-finder)

Phase 2 is owned by the skill-finder skill. Trigger it only when all of the following are true:

• Phase 1 has no candidate (catalog scanned, no row matched within ~30 seconds).
• The need is recurring, not a one-off setup task. One-off scaffolding (Vite/React init, single-shot config conversion, ad-hoc data migration) belongs inline.
• The need is stated as an active pain or near-term task, not just an ambient signal. A Rust service that exists in the repo but isn't currently causing skill-shaped questions does not by itself justify Phase 2 — wait until the recurring need surfaces.

If any of the three is false, do nothing. Re-read the "When NOT to use" section above before escalating.

To run Phase 2: tell the user "Phase 1 catalog has no fit; want me to invoke skill-finder for a cross-source search?" and only proceed on explicit go-ahead. skill-finder performs the cross-source survey (Anthropic official → claude-skill-registry → VoltAgent → ComposioHQ → Superpowers → GitHub topic), applies the same rubric, and gates adoption through a mandatory waxa eval. Do not duplicate that workflow inline.

Phase boundary — do not blur

The two phases solve different problems:

• Phase 1 trades breadth for confidence. The catalog is curated; trust it.
• Phase 2 trades confidence for breadth. Compensate with explicit evaluation.

Common failure: starting in Phase 2 ("let me grep GitHub for a Playwright skill") when Phase 1 already has playwright-test. Always read the catalog first.

Reverse failure: forcing a Phase 1 fit when the catalog truly has nothing suitable. If no row matches within ~30 seconds of scanning, escalate — don't pad the install list with adjacent-but-not-quite skills.

Maintenance of the catalog

• Catalog is part of this skill. Keep it in sync when mizchi/skills (and upstream skill repos referenced) gain or lose skills.
• A skill discovered through Phase 2 (skill-finder) may be promoted into the catalog after it has been used in 2+ projects without issue and after passing its waxa eval.
• If the catalog feels stale, cross-check against mizchi/skills README before falling back to skill-finder.

Common mistakes

Related

• skill-finder — Phase 2 owner; cross-source survey + waxa eval gate when the catalog has no fit
• apm-usage — actual apm install syntax and manifest format
• empirical-prompt-tuning — how to test a candidate skill before adopting it
• superpowers:writing-skills — when no existing skill fits, write one instead of adopting a poor match
• chezmoi-management — for skills that must stay private (the APM-vs-chezmoi boundary)