Skill Finder

Skill Finder

Adopting a skill found outside the curated catalog has two failure modes the in-catalog flow does not carry:

1. Low-quality content — registries vary wildly in vetting; some are SEO scrapes.
2. Registry blindness — Tier-1 official sources can already cover the need; jumping to GitHub grep first wastes effort and lands in noisier listings.

This skill exists to make the cross-source search deliberate and to refuse adoption of anything that has not passed a waxa eval.

When to invoke

Explicit user request only. Triggering phrases:

• "find a <X> skill"
• "is there a skill for <X>?"
• "evaluate <owner/repo> as a skill before adopting"
• "search the registries for <X>"

When NOT to use:

• The catalog already has a fit → stop immediately and tell the user to use skill-selector Phase 1 instead. Do NOT continue into Tier 1-4 search, do NOT propose install steps, do NOT survey other sources. Even if the catalog skill is plausibly improvable by something external, the existing fit is the answer; respect Phase 1.
• One-off task with no recurrence → solve inline; do not adopt a skill you will trigger once.
• The user did not ask for discovery → as a meta-skill, this never auto-fires (cf. user-level CLAUDE.md "Skill 利用方針").

Pre-flight check (mandatory first step)

Before doing anything else, scan the skill-selector/references/catalog.md rows against the user's stated need. If any row matches:

1. State the matching catalog row to the user.
2. Recommend they invoke skill-selector (Phase 1) for the install.
3. Stop. Do not run the workflow below. Do not survey Tier 1+ sources.

Only proceed past this check when the catalog scan finds no row matching within roughly 30 seconds of reading.

Sources

Priority tiers. Always start at the top and only escalate when the tier above has no fit.

Workflow

0. Pre-flight catalog check (see above). If skill-selector/references/catalog.md has a fit, stop and defer to skill-selector. Only continue past step 0 when no catalog row matches.
1. State the recurring need. A skill is justified only by a recurring task type. If the user cannot name one, do not adopt — solve inline.
2. Sweep top-down. Hit Tier 1 first. Stop at the first usable hit; do not survey lower tiers when Tier 1 already matches. Capture per candidate: skill name, resolved GitHub URL, one-line description, last-update date, license.
3. Apply the rubric. A candidate passes only if all seven axes are acceptable:
   • Fit — does the skill's "Use when..." actually match the project task? Re-read the description, not the title.
   • Non-redundancy — does the project's already-installed skill set cover this need? A "Fit ✓" candidate that overlaps with skills already in the stack should still be rejected (or at most project-pinned to one project that genuinely lacks the coverage). Common overlap pairs: skill-creation skills vs superpowers:writing-skills + empirical-prompt-tuning + waxa-eval; testing skills vs playwright-test; dotfile skills vs chezmoi-management. A redundant skill costs context every conversation without a unique payoff.
   • Maintenance — last commit recent? Visible upstream activity?
   • License — SPDX present and compatible with the consuming project?
   • Frontmatter health — name matches dir; description ≤1024 chars and triggering-condition-shaped (per superpowers:writing-skills CSO).
   • Body quality — explicit "When NOT to use"? Concrete patterns vs vague advice?
   • Footprint — body length, demand-loaded vs always-loaded references, cross-skill dependencies.
4. waxa audit (recommended). Before spending the eval-gate budget, run npx @mizchi/waxa audit <candidate-skill-dir> to surface structural problems cheaply: frontmatter shape, body length, missing "When NOT to use", suspicious scripts, missing LICENSE, plus apm audit's hidden-Unicode (prompt-injection) scan. A candidate with audit errors is a probable Reject without spending LLM time on the eval gate.
5. waxa eval gate (mandatory). Adoption without empirical evaluation is the failure mode this skill exists to prevent. For each shortlisted candidate:
   • Install temporarily: apm install <owner>/<repo>/skills/<name> into a sandbox project (or symlink for local audit).
   • Author 1-2 representative tasks/*.yaml matching the project's actual recurring task. See skill-selector/evals/ and nix-setup/evals/ (skill-local layout from waxa 0.2.0) for working templates.
   • Run waxa run with trials_per_task: 2 minimum.
   • Iterate (waxa iterate) until the ledger converges. Convergence = 2 consecutive runs with zero unclear-points (cf. empirical-prompt-tuning).
   • If unclear-points persist across 2 iterations with no decreasing trend → treat as divergent, reject.
6. Decide and pin. Adoption is always pinned; pinning is non-negotiable.
   • Catalog-promote — passes eval AND used in 2+ projects without issue → propose addition to skill-selector/references/catalog.md with the project signal that should trigger it.
   • Project-pin — fits one project; add to that project's apm.yml with a tag or SHA resolved via apm view <repo> (or the upstream release page). Pin to the exact ref the waxa eval passed against — adopt after eval, pin the ref that was eval'd. Floating refs (main, master, HEAD) are forbidden for production projects.
   • Reject — record the reason in references/rejection-log.md (this skill) and / or the project's own docs/skills-rejected.md so the same candidate is not re-evaluated quarterly. Common reject reasons: license absent, body quality below floor, non-redundancy axis fails (already covered by installed stack), or maintenance signal too weak.
7. Fork-and-fix path. If a candidate is close-but-not-quite, prefer forking it into mizchi/skills/<name> (or the project's local skills dir) and reshaping it, over working around its shortcomings at call sites. Document the divergence so an upstream PR can converge.

Source-specific resolution notes

• anthropics/skills: skills live under skills/<name>. Install string: apm install anthropics/skills/skills/<name> (the path includes "skills/skills" — not a typo).

• anthropics/claude-plugins-official: includes external_plugins/ (asana, linear, playwright, serena, laravel-boost, github, gitlab, firebase, terraform). These are plugins, not raw skills — verify the plugin manifest exposes a SKILL.md before treating them as APM dependencies.

• majiayu000/claude-skill-registry: ships its own sk CLI; you do not need it. apm install owner/repo/skills/name works once you have the path. Use the registry's web UI / data files for discovery only.

• VoltAgent/awesome-agent-skills: README is org-grouped (Anthropic / Stripe / HashiCorp / Cloudflare / Sentry / etc.). Extract entries with:

  bashCopy code
  curl -sL https://raw.githubusercontent.com/VoltAgent/awesome-agent-skills/main/README.md \
    | grep -oE '\[[^]]+\]\(https?://officialskills\.sh[^)]+\)'
  

  Each officialskills.sh URL routes to a GitHub repo; traverse to that repo before evaluating.

• GitHub topic search: use the API. topic:claude-skill (1.4k repos) and topic:agent-skills (4.3k) are both noisy — filter by SKILL.md presence and recent activity. The path:SKILL.md qualifier helps narrow. Star count is mostly signal-less past Tier 3 (top-starred repos are awesome-lists, not skills).

waxa eval template

For a candidate at <owner>/<repo>/skills/<name>, scaffold:

Copy code
evals/
└── <name>/
    ├── eval.yaml
    └── tasks/
        ├── scenario-typical.yaml
        └── scenario-edge.yaml

eval.yaml skeleton:

yamlCopy code
name: <name>-eval
skill: <name>
version: "0.1"

config:
  trials_per_task: 2
  timeout_seconds: 180
  parallel: false
  executor: claude-cli   # mock for smoke; claude-cli for real eval
  model: claude-opus-4-8

graders:
  - name: <task-specific>
    type: text | code | llm | self_report
    config: { ... }

tasks:
  - "tasks/*.yaml"

Working references in this repo: skill-selector/evals/eval.yaml, nix-setup/evals/eval.yaml (skill-local layout from waxa 0.2.0).

Common mistakes

Related

• skill-selector — Phase 1 catalog selection. Always run before this skill. If Phase 1 covers the need, do not invoke skill-finder.
• apm-usage — apm.yml syntax for the install / pinning step
• empirical-prompt-tuning — convergence/divergence semantics underlying the waxa eval gate
• superpowers:writing-skills — when no candidate passes the rubric, write the skill yourself instead of forcing a poor match