Aha skills finder

Aha Skills Finder

Use this skill when a target outcome needs the agent to identify the skill or capability that matches the target need, not merely the first candidate an obvious registry, package search, or query returns. The output is an aha-shaped discovery artifact: multiple traceable candidates, source gaps, query corrections, and raw signals. Not one best answer.

This is runtime-agnostic. Treat this SKILL.md as a portable agent-readable method contract, not as a Codex-only package or an install recipe. Runtime-specific metadata belongs in adapters/ only after evidence-gated validation.

This is not a tutorial or marketing surface. Optimize for agent execution, machine-readable artifacts, and compact scope checks. Do not add quickstarts, screenshots, or docs-site prose unless they directly improve agent execution.

There is no universal best skill. Aha names the discovery moment when an agent identifies the skill or capability that matches the target need. Expanded source surfaces, query expansion, raw signals, and traceable surprises are methods for reaching that moment; adoption judgment stays in later gates.

Timing matters. Discovery is not abstract optimization: too early means the ecosystem may not exist yet, too late means the useful window may have passed. Capture why the search should happen now.

The core advantage is not confidence theater. It is recall with provenance. A run of aha-skills-finder reduces false negatives by searching the places where the capability is likely to live, including registry-native surfaces that may not have standalone repos or packages, and package-registry tooling that may function as skill libraries, routers, loaders, managers, installers, or marketplaces rather than individual skills.

aha-skills-finder complements third-party skill libraries, finders, routers, managers, installers, marketplaces, and MCP loaders. Those tools are valid discovery surfaces and candidates, but they often search one ecosystem, mix find/adopt actions, or turn package/list metadata into recommendation language. This method fills the gap by producing cross-surface, lane-scoped, raw-signal candidate pools for later stages to audit or adopt separately.

Load supporting references only when needed:

• Query templates: references/query-recipes.md.
• Schema compatibility notes: references/schema-compat-0.3.md.
• QA fixture design: references/qa-fixtures.md.
• Contract fixture validator: scripts/validate_contract_fixtures.py.

Find-Stage Scope

This is find-stage only.

Do:

• discover multiple candidates;
• widen the source surface;
• record query branches, false positives, gaps, and raw signals;
• include adjacent capabilities that could become skills.

Do not:

• recommend adoption;
• score or rank final winners;
• perform source, safety, permission, maintenance, provider, browser, credential, login, live, or external-write audit;
• install, enable, configure, replace, publish, deploy, or mutate runtime config.

Do not treat third-party tool claims as aha-skills-finder conclusions. A package that claims large catalogs, token savings, fast routing, many runtime integrations, or curated quality is still only a raw candidate until a later audit or adoption stage verifies that claim.

Inputs

Ask for or infer:

• target outcome;
• why now;
• target runtime or ecosystem, if any;
• lane split, when the request mixes different action modes;
• excluded adjacent capability;
• region/platform/language constraints, if relevant;
• time budget or bounded-round count.

Start with a Day 1 Answer:

If I did no research, I would expect the strongest capabilities to come from ______ because ______.
The actual outcome is ______.
This should be searched now because ______.
Adjacent capabilities that are out of scope are ______.

If the requested outcome mixes different action lanes, split before searching. Do not force one candidate pool to cover incompatible lanes such as final publish, draft creation, formatting, conversion, monitoring, and analytics.

For each lane, record:

• lane id;
• lane-specific target outcome;
• out-of-scope adjacent lanes;
• priority source families for that lane ecosystem;
• known lane-relative false positives.

Discovery Modes

Choose the lightest mode that preserves recall and provenance.

• Quick discovery: use when the target and ecosystem are already narrow. Run one lane, R1 plus focused R2, and 2-4 priority source families. Return a compact candidate list plus source gaps, false positives, query branches, and alias/stub relationships when found; do not force a full research brief unless the requester asks for a durable artifact.
• Full discovery: use when naming is unstable, the ecosystem is fragmented, or missing candidates is costlier than extra search. Use lane decomposition when needed and return both artifacts: a research brief and candidate pool matching the reference contracts.

Candidate count is outcome-dependent:

• named skill lookup: 1-3 exact identities plus aliases, wrappers, or forwarding stubs;
• Quick discovery: 8-12 raw candidates for ordinary non-named searches;
• narrow runtime need: 5-8 candidates when the ecosystem is not tiny;
• broad category scan: 15-25 candidates;
• marketplace or source discovery: 20+ sources or candidates when available.

Fewer candidates are acceptable when the source surface is narrow, but record the source gaps instead of stretching with unrelated noise.

Workflow

R1: Source-Surface Recall

Build a heterogeneous discovery surface before judging candidates. Source coverage is outcome-bound: choose source families that match the lane ecosystem, not a generic global source list. Cover as many relevant source families as the task warrants:

• skill registries, registry public APIs, marketplace search endpoints, and search indexes;
• runtime/spec docs;
• GitHub/Gitee/GitLab repo and code search;
• package registries such as npm, PyPI, crates, and Homebrew, including package-native search for skill libraries, finders, routers, managers, installers, marketplaces, MCP loaders, and retrieval/distillation tools;
• MCP and agent-tool catalogs;
• extension, SaaS, and provider surfaces;
• native framework/runtime capabilities;
• curated/recommended skill lists, community indexes, and trackers.

Do not inspect repo-local, user-global (operator-owned), runtime-cache, or plugin-bundled skill directories unless the requester explicitly asks for local/offline availability or local packaging examples. Label any such results as local baseline signals, not public discovery coverage.

For skill-class outcomes, do not stop at repo or package search. Attempt the registry-native marketplace, public API, or search endpoint for the relevant skill ecosystem when one is available or named by the requester. A GitHub/npm miss is not evidence that a registry-native skill does not exist.

For skill-discovery outcomes, do not stop at skill bodies or curated lists. Search for adjacent skill tooling: libraries, finders, routers, managers, installers, marketplaces, MCP lazy loaders, and skill retrieval/distillation systems. These are candidate sources or adjacent tooling, not automatic replacements for aha-skills-finder and not adoption recommendations.

API, code-search, marketplace, or registry failures are source gaps, not no-hit evidence. Record the failure surface and failure type, for example unauthenticated code search, rate limit, endpoint unavailable, private registry, or unsupported search syntax.

Use the candidate-count target from Discovery Modes. Do not inflate the pool to hit a numeric target; prefer explicit source gaps over unrelated candidates.

Treat installs and downloads as first-class raw discovery signals when available. Examples include skill marketplace installs, package registry downloads, extension store installs, registry invocation counts, and package download windows. If a surface does not expose the signal, record the source gap instead of inferring adoption.

Keep telemetry split by evidence surface. Registry installs or invocations belong to the registry surface; package downloads and download windows belong to the package surface; repo stars, forks, pushed dates, and releases belong to the source-repo surface; extension or store ratings and installs belong to the extension/store surface. Do not merge these into a single quality score, ranking, or adoption verdict.

Registry-provided stats and scan labels are raw signals only. Record downloads, installs, stars, file counts, file-hash availability, and raw registry scan labels when exposed, but do not treat them as safety proof, source audit, or adoption recommendation.

Repo-level metrics need a monorepo caveat. Stars, forks, and pushed dates for a large repo are discoverability and context signals for the candidate path, not proof of subskill quality or fit. Preserve the monorepo subpath when visible and defer subskill audit to a later stage.

Curated, recommended, "best", "awesome", roundup, and leaderboard lists are discovery surfaces. Use them for cold-start recall, ecosystem vocabulary, and candidate names. Do not treat a list's recommendation language as an adoption, quality, or safety verdict.

When the lane is specifically about finding good skill recommendation sources, use source-registries/curated-skill-lists.yaml as a seed list. Treat that file as a maintained discovery-source registry, not as a list of endorsed skills.

R1a: Alias, Stub, and Wrapper Tracing

Trace alias, stub, shim, wrapper, bridge, launcher, proxy, loader, and facade terms when a candidate name may be an entrypoint rather than the real capability. Follow package, repo, registry, or command entrypoints to the actual implementation when visible. If the wrapper and implementation are different, keep one candidate with multiple cross-map signals rather than duplicate candidates. If the implementation cannot be confirmed, record a source gap instead of guessing. For multi-hop relationships, preserve chain_steps and the confirmation breakpoint.

R1b: Candidate Identity Cross-Map

Before comparing candidates, cross-map each plausible candidate identity across the surfaces that expose it:

• registry id, slug, display name, and version when available;
• source repo URL and source path;
• package name and package registry URL;
• monorepo subpath for the specific skill, adapter, plugin, or tool;
• runtime adapter path if it is visible in the repo or package;
• alias, wrapper, command shim, or forwarding-stub relationship when the visible invocation differs from the actual implementation entrypoint;
• source gap when any mapping cannot be confirmed.

Mapping failures are source gaps, not market-absence claims. Useful examples are registry query returned zero results, package download API returned not found after package search found a candidate, repository URL returned 404, code search was unauthenticated or rate-limited, or a marketplace page was readable but no public API was visible.

The cross-map output lives in the candidate pool as:

1. source.repo_url — canonical source repository.
2. source.registry_id — registry/package identifier if different from name.
3. entrypoint_url — the actual URL an agent would use to access the capability.
4. entrypoint_relationship — optional alias/wrapper/stub relationship metadata.
5. notes — any cross-map discrepancies (e.g., "npm package name differs from repo name").

If a candidate appears under multiple identities, create one candidate with all cross-map fields populated, not duplicate candidates.

R2: Query Expansion, Branching, and Correction

Challenge R1 instead of deep-auditing favorites. Do not assume the requester's first words match the ecosystem's vocabulary. Build query branches from:

• seed terms from the target outcome;
• outcome verbs and target objects;
• execution surfaces and artifact or receipt terms;
• ecosystem synonyms such as catalog, directory, registry, marketplace, library, finder, router, loader, manager, installer, retrieval, and distillation;
• registry-native names, slugs, marketplace labels, and API field names;
• package-registry terms such as npm, PyPI, package, CLI, MCP server, lazy loading, on-demand loading, skill library, skill finder, skill router, skill manager, skill installer, skill marketplace, agent skill retrieval, and skill distillation;
• runtime terms such as Codex, Claude Code, Cursor, OpenClaw, MCP, agentskills, and SKILL.md;
• claim terms discovered from candidate metadata, such as lazy loading, on-demand skill loading, dynamic skill retrieval, portable skills, catalog, context reduction, or token reduction;
• curated-list terms such as recommended, best, awesome, roundup, leaderboard, directory, and their local-language equivalents;
• local-language equivalents when the target ecosystem, region, platform, or requester language makes English-only search incomplete;
• adversarial misspellings, spacing variants, hyphenation variants, and casing variants for named skills or ecosystems;
• adjacent capability words;
• alias and stub terms such as "Run a /", "forwards to", "alias", "wrapper", "command shim", and disable-model-invocation;
• known false-positive terms.

When R2 performs non-trivial query expansion for a lane, preserve that evidence in the research brief. In Full discovery, prefer branch-tree records for high-value branches and gap-derived follow-up branches for actionable source gaps:

• seed queries;
• expanded queries;
• query branches;
• expansion triggers;
• false-positive corrections;
• new terms discovered;
• optional query_branch_tree and gap_followup_branches for Full discovery.

Do not backfill query-expansion fields into old or trivial examples merely to satisfy the schema; preserve them when they explain a real search correction.

Keep a small false-positive set as query correction evidence. Classify false positives with lightweight categories such as mismatched lane, mismatched platform, wrapper-only, locale mismatch, naming collision, wrong action, and wrong object. Convert false positives into better query terms instead of only dropping them. False positive is lane-relative: it means "not for this lane/outcome", not "bad candidate". A candidate can be false positive for a publish lane and valid for a formatting lane.

When true 7/30/90 day star velocity is unavailable, use a recent-growth proxy instead of leaving the freshness question implicit. Record the proxy basis, such as created date, current stars, forks, pushed/updated time, release cadence, or package download cadence. This remains a raw discovery signal, not a quality or maintenance verdict.

R2a: Query Recipes

Use 2-3 relevant recipe families in Quick mode; Full mode may expand the whole recipe set. Load references/query-recipes.md when concrete query templates are needed. Record recipe-derived queries in expanded_queries and why each recipe was used in expansion_triggers.

Handling R2-Discovered Candidates That Should Have Been in R1

When R2 query expansion surfaces candidates that clearly match the original R1 target outcome but were missed:

1. Add them to the candidate pool normally.
2. Set query_branch to the R2 branch that found them.
3. Add a notes entry: "R2-discovered; missed in R1 due to [reason: narrow query / missing source family / registry gap]."
4. Record the gap in source_gaps with gap_type="r1_miss", the source family, reason, and impact.

Do NOT retroactively modify R1 results.

R3: Candidate Pool

Convert recall into a candidate pool artifact using references/candidate-pool-contract.md.

Keep candidates that have traceable source and plausible outcome proximity. Hold selected partial hits if they improve discovery coverage. Drop unrelated or untraceable noise.

Do not use adoption risk, safety, or maintenance as find-stage filters.

Keep candidate typing split across three axes:

• candidate_type is the physical shape, such as skill, mcp, cli, registry-search-index, or curated-list;
• candidate_role is the find-stage semantic role, such as capability, discovery-source, adjacent-index, adjacent-tooling, or registry-index;
• candidate_surfaces are descriptive handoff tags, not rankings or roles.

These axes may combine. For example, candidate_type=mcp + candidate_role=discovery-source + candidate_surfaces=["skill-library"] is a valid way to record an MCP server that acts as a skill-library discovery source.

Useful surface tags include agent-skill, mcp-server, cli, package, web-editor, desktop-app, browser-extension, hosted-saas, official-api, native-runtime, source-repo, registry-index, curated-list, skill-library, skill-finder, skill-router, skill-manager, skill-installer, skill-marketplace, mcp-loader, skill-retrieval, skill-distillation, docs, and prompt. Surface tags are descriptive only; they are not rankings. Do not introduce new candidate axes unless they improve recall or handoff quality.

Stopping Conditions

Stop discovery only when all applicable handoff conditions are explicit, or when the runtime budget or a hard limit prevents further discovery:

1. Planned rounds are complete or the explicit budget is exhausted.
2. Outcome-bound source coverage is explicit.
3. Important source gaps are recorded.
4. Major query expansion branches have been tried or deferred.
5. False positives have been converted into query corrections where useful.
6. Candidate identities are cross-mapped where available.
7. Candidate type, role, and surfaces are clear enough for handoff.

Do not stop merely because one plausible candidate appears, because one source family produces enough candidates, or because the last query branch produced few new candidates. When stopping before all planned rounds complete, record the stop reason in the research brief rounds[last].stop_reason and mark remaining rounds as skipped with skipped_reason: "budget_exhausted" or the specific runtime limit that was hit.

Outputs

Return or write outputs by discovery mode:

• Quick discovery: return a compact candidate-pool-compatible artifact or summary with candidate records, source gaps, false positives, query branches, and deferred scope tags. Do not require a research brief unless the requester asks for a durable artifact.
• Full discovery: return both a research brief matching references/research-brief-contract.md and a candidate pool matching references/candidate-pool-contract.md.

Preserve evidence surface per signal in machine-readable fields. Prefer the existing metrics.download_signals, registry_stats, package_registry_stats, source, entrypoint_url, entrypoint_relationship, candidate_surfaces, find_signals, source_gaps, and notes fields rather than inventing a new schema for every run. When a candidate has mixed evidence, keep each signal tied to its surface, name, value, source URL, and window or timestamp where available. Do not collapse registry, package, repo, and store signals into a single score.

Use sources.yaml as a source-family prompt and selection guide, not a mandatory taxonomy. When modifying contracts or fixtures, run scripts/validate_contract_fixtures.py.

Source

Repository: https://github.com/its-How/aha-skills-finder

This section is provenance only. Do not treat it as an install, upgrade, uninstall, enablement, or runtime-mutation instruction during find-stage work.

Cannot Prove

A find-stage artifact cannot prove:

• a candidate is safe;
• a candidate is maintained well enough to adopt;
• a candidate should be installed or enabled;
• a candidate improves the downstream outcome;
• source, provider, browser, credential, or live readiness.