find-skills

name	find-skills
description	Use when the user asks which skill, support capability, or integration should handle a task, or names a skill/support/capability such as `X skill`, `X 스킬`, `support/X`, or `X integration`. Call this before filesystem search for named capabilities; support skills are intentionally hidden from the default skill list.

Find Skills

Use this when the user is asking:

• what skill should handle a task
• whether a named skill, support skill, helper, or integration exists
• whether the current harness can do something
• whether a capability is native, support-driven, or external
• how to extend the harness for a recurring task

Do not treat ordinary design or workflow decision-shaped prompts as capability discovery only because several public skills are nearby. Questions like "what do we need to decide?", "what decision issues are still open?", "뭘 결정해야 하죠?", or "결정할 쟁점은?" usually need an ideation or spec decision frame with options, tradeoffs, a recommendation, and a next step. Use find-skills when the user explicitly asks which skill, support capability, helper, or integration should handle the task, or names one directly.

When the user names a capability directly, including phrases like X skill, X 스킬, X support, support/X, X helper, or X integration, run find-skills before find, ls, or grep filesystem discovery. Support skills are intentionally hidden from the default public skill list; this is the canonical discovery path for them.

When workflow language implies a support skill even though the user did not name it directly, query task-text recommendations before proceeding through a nearby public workflow. For example, executable-spec terms should surface support/specdown before ordinary Markdown, HITL, spec, or impl work.

find-skills is one public concept:

• discover the right capability surface
• prefer local native skills first
• expand to adapter-configured trusted skill roots before treating a gap as new
• distinguish public skills, support skills, and external integrations honestly
• surface synced support skills separately when an external integration has already materialized one locally
• show the next usable path instead of only saying "not found"

Borrow Jef Raskin-style discoverability discipline: do not turn capability search into a mode maze. Surface the smallest obvious next step, keep lifecycle boundaries visible, and make it easy for the next operator to tell what to do now.

Bootstrap

Start local-first:

python3 "$SKILL_DIR/scripts/resolve_adapter.py" --repo-root .
python3 "$SKILL_DIR/scripts/list_capabilities.py" --repo-root .
python3 "$SKILL_DIR/scripts/list_capabilities.py" --repo-root . --read-only
python3 "$SKILL_DIR/scripts/list_capabilities.py" --repo-root . --recommend-for-task "<task summary>"
python3 "$SKILL_DIR/scripts/list_capabilities.py" --repo-root . --recommend-for-skill <skill-id>
python3 "$SKILL_DIR/scripts/list_capabilities.py" --repo-root . --recommendation-role <runtime|validation> --next-skill-id <skill-id>
sed -n '1,220p' docs/external-integrations.md 2>/dev/null || true
sed -n '1,220p' docs/support-skill-policy.md 2>/dev/null || true

Pass --read-only when the caller must not mutate the workspace (read-only sandbox, routing-only eval, or any context where the durable inventory artifact refresh is not part of the contract). The payload still contains the inventory on stdout, and artifacts.mode reports read-only so the consumer can tell that no durable artifact was written.

If a host-provided installed skill path is missing, resolve the current installed path before treating the capability as absent:

python3 "$SKILL_DIR/scripts/resolve_skill_path.py" --repo-root . --skill-id find-skills --reported-path <missing-path>

For non-charness plugins whose absolute cache paths went stale after charness update rotated cache hashes, pass --marketplace/--plugin to search any other Codex plugin's cache:

python3 "$SKILL_DIR/scripts/resolve_skill_path.py" --skill-id <id> --marketplace <m> --plugin <p> --reported-path <missing-path>

If the user's need sounds like a public workflow, inspect skills/public/ first. If it sounds like a tool-use capability, inspect support skills and integration manifests before proposing a new public skill. If the adapter advertises trusted skill roots, search those before proposing a new local skill.

Default durable artifact:

• <repo-root>/charness-artifacts/find-skills/latest.md
• latest.* is the canonical local-first capability inventory only; ad hoc recommendation queries stay in the current command output and do not rewrite query-shaped state into the durable artifact

What you get after one run:

• a local-first capability inventory
• public/support skill descriptions, canonical paths, trigger phrases, and directly referenced skill files
• the smallest next usable path across public skills, support seams, and integrations
• refreshed capability inventory artifacts at charness-artifacts/find-skills/latest.*
• a closeout signal under artifacts
• recommendation-query payloads in command output for task, skill, or route queries

What this does not do:

• arbitrary external skill marketplace search unless the adapter explicitly allows it

Workflow

1. Restate the capability need.
   • what task the user wants
   • whether they need a workflow, a tool-use seam, or a new extension point
2. Search local native capabilities first.
   • public skills for user-facing workflow concepts
   • support skills and synced support skills for tool-usage helpers
   • integration manifests for external binaries or upstream support skills
   • use task-text recommendation payloads when file shapes, syntax, reports, or runtime commands imply an unmentioned support skill
3. Expand to trusted skill roots when the adapter provides them.
   • host-trusted or repo-trusted skill packs the current harness may consult
4. Classify the best match honestly.
   • public skill
   • trusted skill
   • support skill
   • synced support skill
   • external integration
   • missing capability
5. Recommend the smallest usable next step.
   • invoke an existing public skill
   • point to an adapter-configured trusted skill if the current host uses one
   • use a support capability through the right workflow
   • install or wire an external integration if the policy already supports it, and surface the supported access modes when that changes the next step
   • use structured recommendation payloads for external-tool, runtime, validation, or support routes
   • when the user asks about stronger validation, prompt-affecting or behavior-affecting changes, validation-shaped review/closeout, issue closeout, or operator reading test wording, query --recommendation-role validation --next-skill-id <skill-id> instead of routing to HITL or manual review only
   • if the capability is genuinely missing, say whether it belongs in a new public skill, support skill, or integration manifest
6. Explain why.
   • why this is the right layer
   • what is already shipped
   • what is not yet shipped
   • whether an external skill ecosystem search is allowed by the current host

Output Shape

The result should usually include:

• Need
• Best Match
• Layer
• Search Surface
• What Exists
• Next Step

Guardrails

• Do not recommend a new public skill when an existing public concept already covers the task.
• Do not skip adapter-configured trusted skill roots if the host has declared them as part of its supported discovery surface.
• Do not recommend a support skill when the task is really a user-facing workflow concept.
• Do not pretend an external capability is native to the repo if it only exists as a future integration.
• Do not recommend installing from a generic external skill ecosystem unless the host policy or adapter explicitly allows that path.
• Do not answer ordinary decision-shaped prompts with routing alone when the user needs a decision frame; keep explicit skill/capability discovery on this skill.
• If nothing suitable exists yet, say so directly and classify the missing capability instead of hand-waving.
• If the artifacts payload reports requires_repo_closeout: true, apply the host repo's commit or closeout policy for meaningful durable artifact changes before final response.

References

• adapter.example.yaml
• references/adapter-contract.md
• references/discovery-order.md
• references/support-consumption.md
• ../ideation/references/decision-question-response.md
• scripts/list_capabilities.py
• scripts/list_capabilities_lib.py
• <repo-root>/scripts/resolve_adapter.py
• <repo-root>/scripts/init_adapter.py
• <repo-root>/scripts/list_capabilities.py