Map relevant code quickly with ak:scout

Use ak:scout for fast, bounded reconnaissance of a project. The Skill turns a specific search target into a concise map of relevant files and patterns, using local search first and optional delegated or external probes only when allowed.

Choose ak:scout when you need a codebase map

Use ak:scout when

• You need to find where a feature, interface, configuration, or behavior lives.
• A task spans several directories and you need its file and test boundaries.
• A debugging or review workflow needs entry points and relationships first.
• You need evidence about project structure without changing implementation.

Choose another workflow when

• You need root-cause diagnosis after locating the affected path. Use the Engineer debugging or fix workflow.
• You need to compare solution approaches. Use ak:brainstorm.
• You need a phased implementation roadmap. Use ak:plan.
• You already know the files and want changes made. Use ak:cook.

Prepare the project and runtime

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Open the project or directory tree to inspect.
• Give one bounded search target, plus directories or file types to include or exclude when they matter.
• Explicitly authorize subagents, delegation, or parallel agent work if you want Explore agents. The Skill does not infer that permission.
• Explicitly permit the external path before using ext.

Run the Skill

/ak:scout "Find the editor draft persistence entry points, storage adapter, recovery UI, and focused tests. Search src/ and tests/ only."

/ak:scout "Find the editor draft persistence entry points, storage adapter, recovery UI, and focused tests. Search src/ and tests/ only."

$ak:scout "Find the editor draft persistence entry points, storage adapter, recovery UI, and focused tests. Search src/ and tests/ only."

The default mode uses local search and scoped file reads. Add ext only when native search is insufficient and you permit a bounded OpenCode probe:

/ak:scout "Find payment webhook ownership across api/ and lib/; read-only" ext

Describe the search clearly

A useful scout request names:

• Target: the behavior, symbol, feature, configuration, or relationship to locate.
• Scope: directories, packages, file types, or repositories to include.
• Exclusions: generated files, vendor trees, fixtures, or unrelated subsystems.
• Expected evidence: entry points, callers, tests, configuration, data flow, or file counts.
• Authority boundary: whether delegation or an external provider is allowed.

For the draft-recovery example, asking for persistence entry points, the storage adapter, recovery UI, and focused tests produces a more useful map than “search the editor.”

Understand what happens during a run

1. The Skill parses the target. It identifies search terms, likely directories, file types, and the evidence needed for the next workflow.
2. The Skill estimates the search surface. It uses broad local patterns to learn project scale before reading content.
3. The Skill searches locally. It prefers native file search and bounded reads. Large files are read in manageable chunks rather than copied whole.
4. The Skill decides whether delegation is allowed. Without explicit user permission or runtime capability, scouting stays in the main agent. With permission, distinct directories may be assigned to non-overlapping Explore scopes.
5. The Skill may use the external path. With ext, user permission, and available OpenCode tooling, it runs bounded read-only probes. Failure falls back to local search and remains visible.
6. The Skill aggregates evidence. It deduplicates paths, records important relationships and patterns, notes timeouts or uncovered scopes, and lists unresolved questions last.

Keep approval and safety with you

Default scouting is read-only for project content. It should not edit product code, install tools, or turn reconnaissance into implementation. A runtime may record transient task progress or write a concise scout report in the project's configured report location; that organizational artifact does not authorize other workspace changes.

Explore agents run only when you explicitly requested or permitted delegation and each has a distinct useful scope. External probes can depend on provider authentication, network access, model availability, and cost. A failed external probe is not retried indefinitely and does not justify broadening the data shared.

Verify the result

A complete scout result should give you:

• Relevant file paths with one-line explanations.
• Key symbols, entry points, tests, configuration, and relationships requested.
• Important existing patterns the next workflow should preserve.
• Coverage boundaries, including excluded or timed-out scopes.
• A concise statement of what was not confirmed.
• Unresolved questions listed last.

Treat the result as reconnaissance, not proof of runtime behavior or root cause. When a claim needs behavioral certainty, trace or test it in the owning workflow.

Troubleshoot or continue

Pass the scout report to debugging, ak:brainstorm, ak:plan, or ak:cook depending on whether the next need is diagnosis, decision, planning, or implementation.

Know the current limits

• The Skill reports only files and relationships visible in the current checkout and authorized external scopes.
• Parallel coverage is unavailable when the user has not requested delegation or the runtime does not expose it.
• External results depend on OpenCode and its configured provider; local evidence should verify claims that matter to delivery.
• Cursor invocation is user-verified at the Engineer Skill level and does not establish tool parity.
• Stable and beta package the same ak:scout modes and references. Beta runtime changes do not alter this workflow.