Capability scout

Capability Scout

Use this skill when the current project is missing a capability, blocked by an engineering problem, or would benefit from a proven open-source implementation.

The goal is not to collect links. The goal is to select the smallest, safest capability that materially improves the current task.

Capability types

Classify the need before searching:

Type	Use when	Default action
Skill	The missing value is instructions, workflow, or domain knowledge	Recommend and preview the skill
Plugin or MCP	The task needs a tool, service connection, or runtime integration	Inspect manifests and permissions
Library or dependency	The current project needs an importable implementation	Compare API, runtime, license, and migration cost
Template or complete project	A working architecture, UI, workflow, or benchmark is needed	Clone or archive in isolation

Do not choose a complete project when a focused skill or library solves the stated need.

Workflow

1. Inspect the local workspace before searching. Identify the framework, language, package manager, runtime, relevant dependencies, error or missing capability, current architecture, and constraints.
2. State the task profile in one short paragraph: required outcome, local context, compatibility limits, and what counts as success.
3. Choose the most likely capability type. Search that type first. Do not search every type merely to produce a diverse candidate list.
4. Search the narrowest useful evidence surface:
   • If local evidence points to a standard official tool, protocol, package, or project, inspect that official upstream first.
   • Skills: gh skill search "<task>" and, when useful, npx skills find "<task>".
   • Plugins or MCP: gh search repos "<task> MCP plugin" --archived=false --sort stars --order desc.
   • Libraries or projects: gh search repos "<capability> <framework/runtime>" --archived=false --sort stars --order desc.
   • Known repositories: search their issues, merged PRs, releases, examples, tests, and source code. Do not search for third-party wrappers before checking an obvious official upstream that already matches the local interface.
5. Inspect only serious candidates. Record repository, exact skill or package path, stars, forks, language, license, last activity, installation surface, dependencies, examples, tests, and security-sensitive behavior.
6. Rank candidates using these factors:
   • Problem fit: 35
   • Evidence strength: 20
   • Local compatibility: 20
   • Actionability and adaptation cost: 15
   • Project maturity and maintenance: 10 Use a numeric score only when the component scores can be shown and supported. Otherwise use high, medium, or low fit and explain the decisive evidence.
7. Reject candidates that are only popular but poorly matched, stale, archived, unlicensed, version-incompatible, speculative, or unsafe to run.
8. Present one to three viable candidates and select one recommendation. Do not fill candidate slots with weak options merely to represent different capability types.
9. Choose an action mode:
   • recommend: report the best candidate without changing files.
   • archive: copy the exact upstream skill or project to skill-library/<slug>/upstream/ and write local evaluation notes.
   • install-skill: only after explicit confirmation, install to the verified active skill directory and record the exact source revision.
   • install-plugin: only after explicit confirmation, show manifests, hooks, network access, secrets, post-install scripts, and target paths first.
   • reference-project: clone or download the complete project into an isolated archive or temporary worktree. Do not merge it into the current project by default.
   • adopt-project: treat as a separate implementation project. Require a file-level integration plan, dependency review, license review, tests, and rollback plan before changing the current workspace.
10. Verify after action. For a skill or plugin, confirm discovery and inspect the installed files. For a library, run the smallest import/build/test check. For a reference project, confirm the archive is complete and do not claim local integration.

Search budget

For a narrow task:

• Search the primary capability type first.
• If an obvious official candidate exists, inspect it first and skip generic repository discovery unless a real compatibility question remains.
• Use at most one generic query family and five raw results.
• Deep-read one primary candidate and at most one alternative that could realistically change the decision.
• Stop when one candidate clearly meets the requirement and no unresolved compatibility or safety question requires comparison.
• Expand to another capability type only when the primary type has no viable match or the user explicitly asks for cross-type comparison.
• Treat stars and install counts as optional tie-breakers. Do not fetch them when official status, license, maintenance, and local compatibility already decide the result.

For a broad architecture or platform decision, state why the larger search is justified before expanding.

Workspace drift

Capture workspace status once at the beginning of a read-only recommend task.

• Do not repeatedly poll Git state while researching.
• If an external change is observed incidentally, note it once.
• Re-inspect only when the changed file directly affects the recommendation, or immediately before a write/install action.
• Do not chase unrelated commits or working-tree changes during a recommendation-only task.

Installation gate

Never install, enable, register, execute, or merge an external capability merely because it ranked first.

Before an installation action, show:

• selected source and exact revision;
• why it fits better than the rejected candidates;
• files and directories that will be written;
• commands, hooks, services, network access, and dependencies that may run;
• license and attribution obligations;
• backup and rollback path;
• verification command.

Wait for explicit approval when the action changes the active environment, installs dependencies, starts services, executes third-party code, or merges an external project.

For recommend, do not invent a target directory, backup layout, dependency graph, implementation schema, or full test matrix. State only the next decision needed and the smallest evidence required to proceed.

Reference-project rules

Treat a complete open-source project as an action standard, reference implementation, benchmark, or capability source, not as permission to copy its whole architecture.

• Prefer its public interfaces, configuration shape, tests, examples, and workflow over verbatim code.
• Check the license before reuse.
• Keep the upstream snapshot separate from local notes and local adaptations.
• Do not copy secrets, dependency caches, generated output, private data, or repository history.
• Use a high-fit focused project over a high-star adjacent project.
• If the project is used as an action standard, name the exact behavior or test that makes it relevant.

Output contract

Return:

1. Task profile and capability type.
2. Search path and query families.
3. Short candidate table with fit, evidence, compatibility, maturity, and risks.
4. One recommendation or an explicit no-match result.
5. Reuse/adaptation boundary.
6. Action mode and approval gate.
7. For archive, install-*, reference-project, or adopt-project: target path, verification, and rollback plan. Omit these details for recommend unless the user explicitly asks.

When evidence is weak, say so. Do not treat stars, install counts, or a long README as proof that a capability fits the current workspace.

For a narrow recommend result, prefer one primary candidate and one credible alternative at most. Keep the answer focused on the decision, decisive evidence, remaining uncertainty, and next user choice.

Anti-overengineering check

Before finalizing, remove:

• capability types searched only for completeness;
• weak candidates included only to reach three options;
• precise scores without visible supporting components;
• implementation requirements not present in the user's request;
• installation paths, backup schemes, schemas, and test matrices that are not needed for the selected action mode;
• architecture copied from a complete project when a focused library or skill is sufficient.

Safety boundaries

• Search public sources by default. Do not inspect private repositories without explicit scope and authorization.
• Never persist tokens, cookies, API keys, credentials, private repository content, production data, or sensitive logs.
• Do not pass secrets or private context to subagents.
• Use subagents only when independent ecosystems or evidence surfaces can be split cleanly; keep them read-only.
• For security, authentication, payments, infrastructure, or production operations, cross-check external project evidence against current official documentation.
• If a candidate has executable hooks, post-install scripts, MCP servers, or broad filesystem access, downgrade it until those surfaces are inspected.