AI agent skill · by @coleam00

Opportunity Scan

Scan how you actually work with your coding agent and surface what to encode next. Point it at ONE run's artifacts to find what would have prevented a specific failure (the reactive loop — 'that went wrong, what should change in the AI layer?'), or at a window of session logs to find recurring patterns worth building (the proactive scan). Agent-agnostic. Outputs a shape-only HTML report. Use to evolve your system from real usage.

Archived 2026-10-23 · Source updated 2026-10-07 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# Opportunity Scan — find what to change, from what actually happened

Reads your agent's own capabilities plus **one target you choose**, and recommends which primitive each finding
should become. **Agent-agnostic** (Claude Code, Codex, PI, …). It maps what it finds to the **full primitive
palette** (rules · skill · hook · subagent · MCP · automation/workflow), and it works for **any** agent because it
learns that agent's capabilities first.

**Two targets, one skill — this is the whole design:**
- **A run → the REACTIVE loop.** Something just went sideways in a loop you ran. Point the scan at that run's
  artifacts and ask *"what in the AI layer would have prevented this?"* You fix the system, not the code.
- **A window of logs → the PROACTIVE scan.** Nothing is broken. Point it at weeks of sessions and ask *"what do I
  keep doing by hand that should be encoded?"*

Same skill, same output shape — you're just changing what it reads.

This is a **discovery** tool — *what to change* — NOT a quality **eval** (*whether a built thing is good*). Keep
the two separate.

## Inputs — required first, then optional

Read `$ARGUMENTS` as **prose**, not as positional slots. Only input 1 is required. Input 2 is free-form and will
contain spaces, so never split arguments on whitespace and never bind them by position — a steer typed without
quotes is still one steer. If something is missing, ask for it **once, in a single message**, not one question
at a time.

1. **What to scan** *(required)* — exactly one of:
   - **A RUN (reactive)** — the artifacts one loop left behind: the plan, the implementation report, an RCA, the PR
     body, the review output, the commits/diff. Add that run's session log too if you can point at it. *These are
     already scoped to the run, so there's no session-hunting to do.*
   - **A WINDOW OF LOGS (proactive)** — where your agent keeps session logs, plus how far back. Examples: Claude
     Code → `~/.claude/projects/` + `~/.claude/history.jsonl`; Codex → `~/.codex/sessions/`; PI → your extension's
     log dir. Default window: the last 2 weeks.

   This choice is what makes the scan reactive or proactive. Nothing else changes.
2. **Your steer** *(optional — ask once, accept "nothing specific")* — one input, whose meaning follows the
   target:
   - **Scanning a RUN:** the **symptom you noticed**, in your words — what the agent got wrong, what you had to
     correct, what annoyed you. You were there; don't make the scan re-derive from the artifacts what you can
     just say. *(This is the "you just did X" of the one-sentence outer loop — the tooled version accepts the
     same X.)* Keep it to the observation; working out **why** it happened is the scan's job, not yours.
   - **Scanning LOGS:** the **theme you care about** — the kind of work you want to stop doing by hand, a
     quality bar you keep enforcing, a part of the loop that keeps costing you. Without it the scan just ranks
     by frequency, which is not the same as ranking by what matters to you.

   Either way: **you supply the steer, the target supplies the evidence.**
3. **The agent's own capability docs** *(optional — normally resolve this yourself)* — so the scan knows what your
   agent *can become* (its real extension points). **Work it out; do not ask first.** Identify which agent you are
   running as and find its own extensibility docs (for Claude Code that is `code.claude.com/docs`). Only ask if you
   genuinely cannot determine it, or if the user wants you pointed somewhere specific. Never assume a fixed set of
   extension points: read them from whatever docs you actually find.

## Steps — keep them literal; this is the fragile part (meta-prompting)

1. **Learn your own capabilities.** Determine which agent you are running as and read its capability docs (input
   3, which you normally resolve yourself). Write a short internal list of *this* agent's
   extension points (rules, skill, hook, subagent, MCP/tool, automation/workflow, whatever the docs describe). Use
   what the docs say — do not assume a fixed set.
2. **Read the target** — branch on what input 1 was:
   - **A RUN:** read the artifacts **in full** — they're small, and the detail is the point. If input 2 named a
     symptom, **start there**: find it in the artifacts and verify it against what actually happened, rather than
     re-deriving from scratch what the user already told you. Then reconstruct the rest of the run: what was
     asked, what the agent did, where it went wrong, where it had to be corrected, what it assumed, what it
     skipped — the named symptom is the entry point, not a blinder. Read the diff last, as evidence rather than
     as the subject.
   - **A WINDOW OF LOGS:** pull out what you actually did — recurring commands, repeated multi-step sequences,
     repeated instructions/corrections, tools reached for, friction/retries. **Aggregate, don't ingest:** logs can
     be huge — prefer the prompt/command-history file over raw transcripts, and reduce with shell tools
     (`jq`/`grep`/`sort | uniq -c`) so only frequencies and representative samples enter your context, never whole
     log files.

   Either way: if you can't locate or parse the target, **ask the user rather than invent.**
3. **Find what to change** — the question differs by target:
   - **RUN (reactive):** for each thing that went wrong or needed correcting, ask **"what in the AI layer would
     have prevented this?"** Name the **smallest durable change** that would have caught it — a line in a rule, a
     step added to a skill, a hook, a tighter tool scope — specific enough to apply today. **Fix the system, not
     the code:** do not propose the code fix, propose the thing that would have made the code fix unnecessary or
     automatic. ⚠️ **Not every failure is a system gap** — if something went wrong that no durable change would
     have prevented, say so plainly instead of inventing a rule for a one-off. One honest "nothing to change here"
     is worth more than five speculative rules.
   - **LOGS (proactive):** for each recurring pattern, ask **"what should this become?"** Rank by roughly (how
     often it occurs × how much encoding it would save).

   **Both targets:** pick the **best-fit primitive** (from step 1's list) and say *why*. If input 2 was given,
   **weight it** — on a run, the named symptom's prevention leads the report (and if the evidence says the symptom
   was actually something else, say so plainly); on logs, surface what the user said they care about even when it
   isn't the most frequent pattern, and say plainly when a high-frequency pattern is *not* worth encoding. And propose each change **in the house style of
   the artifacts that already exist**: skim a couple of the project's current rules/skills/agents first and shape
   the recommendation to look like them, so what it suggests is something the user would actually build. Examples
   of the mapping:
   - a rule you keep restating → **rules** (CLAUDE.md / AGENTS.md)
   - a repeated multi-step workflow → a **skill**
   - a must-never / must-always you keep enforcing by hand → a **hook**
   - a specialized recurring delegation → a **subagent**
   - a clean end-to-end hand-off you do often → an **automation** (later: an Archon workflow)
4. **Write the report** as a single self-contained HTML file (see the contract below), then tell the user where it
   is.

## Report contract — prescribe HOW to render, never WHAT to include

**Let the analysis drive the report.** Which sections exist, what goes in them, how deep each goes, how many
opportunities, which quotes or numbers are worth pulling out — all of that comes from what you actually found, NOT
from this skill. Do **not** box the report into a fixed set of sections, do **not** seed findings, do **not** tell
it what to conclude. If the data is rich, the report is rich; if a single finding deserves its own deep section,
give it one; if something surprising turns up, surface it.

Only the **rendering** is prescribed:
- One **self-contained `.html`** file (inline CSS), opens in any browser.
- **Visually clean, scannable, and generous** — let the findings breathe; use whatever layout, sections, real
  quotes, stats, or visuals best fit what was actually found.

The rule: this skill governs *how to put it on the page*, never *what goes on the page*.

## Keep it light
Do exactly these four steps, clearly. Don't add scoring frameworks, config, or extra passes it doesn't need. If a
step can't complete (docs or the target not found), stop and ask — never fabricate the analysis.
**Scan one target per run.** If someone wants both the reactive and the proactive view, that's two runs and two
reports — mixing "what broke in this loop" with "what I keep repeating across a month" produces a report that
answers neither question well.