search-first

# search-first

> A Claude Code Agent Skill (MIT) that makes the agent look outside before it builds. When choosing a library, looking for a prior implementation, checking what a paper or official spec actually says, or about to write custom code, the agent searches registries, code, papers and official docs, then writes a dated, sourced report. The caller (the user, the main session, or a planning session) picks from it: Adopt a candidate, Adopt-part (one piece of a candidate), or Build what no candidate covers. The searcher reports and recommends; the caller decides.

Status: active, synced one way from the author's Claude Code harness by `scripts/sync-from-local.sh`, and also shipped in the [akc-cycle](https://github.com/shimo4228/akc-cycle) plugin as `/akc-cycle:search-first`; this repository can trail the plugin between syncs.

## Core documentation

- [llms-full.txt](llms-full.txt): self-contained Q&A reference for AI agents (Project Facts, Prior Research, 9 question-form H2 sections)
- [README.md](README.md): human-facing narrative (install, example report, how it works, triggers)
- [SKILL.md](skills/search-first/SKILL.md): full skill specification — state the question in text → check this repo first → search by question type → report with a Verdict per need; Quick vs Full mode; "skip research" handling

## Architecture

- Look outside, adopt by default, make building prove itself:
  - **0 — State the question in text**: 2–3 sentences of plain chat text before the first tool call (the question, its type, the constraints: language, existing deps, license, budget) so the user can redirect before effort is spent
  - **1 — Check this repo first** with one `rg` / Glob pass
  - **2 — Search by question type**, each with its own places to look and stopping point: Library / tool choice, Prior implementation, Claim of a paper / post, Spec / official behavior, State of practice, Primary-source check; query live docs at decision time
  - **3 — Report**: every claim carries an as-of date and source URL and says whether the full text was read or a snippet seen (`read:` / `saw:`); when nothing turned up, the report writes the range searched. Sections: `Scope searched`, `Found`, `Verdict`, `Still unknown`
- Verdict per need: **Adopt** `<candidate>` (the default when an established candidate matches), **Adopt-part** `<candidate: the piece>` (one piece of a library inside our own control flow), or **Build**, which names for each candidate the stop condition that rules it out (needs forking or patching its internals, glue code as large as building the part, fails the dependency intake, would carry the plan's purpose itself) plus what building takes on; a Build line missing either reads as Adopt. For a plan, the tool question is asked once per part that is a means rather than the purpose. For research done for a plan, the research report leaves the Verdict out and the plan carries it
- Judgement is prose backed by facts — **no numeric scores or grades**
- Modes: **Quick** (inline) for a single obvious need; **Full** for a non-trivial question or any question asked for a plan — 3–5 angles, one adversarial, one `researcher` subagent per angle with a budget of 10–15 searches / fetches. The `researcher` subagent is not shipped here; the author's is [`agents/researcher.md`](https://github.com/shimo4228/claude-harness/blob/main/agents/researcher.md) in claude-harness
- "Skip research": the agent records the skip in one line, offering a quick scan, and proceeds
- Requirements: an agent with web search and fetch tools; no API key of its own (search terms leave the machine through the agent's web tools)

## Standard reference

- [Agent Skill specification](https://agentskills.io/specification): the Claude Code skill format used by this repo

## Sibling skills

- [akc-cycle](https://github.com/shimo4228/akc-cycle): installs this skill together with the rest of the Agent Knowledge Cycle as one Claude Code plugin
- [Agent Knowledge Cycle](https://github.com/shimo4228/agent-knowledge-cycle): the reasoning behind each phase of the cycle, Research among them, recorded as dated design decisions
- [learn-eval](https://github.com/shimo4228/learn-eval): extracts reusable patterns from a session, checks them against what happened, and saves each one where a future session will find it
- [rules-distill](https://github.com/shimo4228/rules-distill): finds principles that recur across 2+ skills and drafts them as rules
- [signal-first-research](https://github.com/shimo4228/signal-first-research): frozen design note on research intake filters that admit only information likely to change your next action
- [skill-comply](https://github.com/shimo4228/skill-comply): runs generated scenarios and reports how often agents actually follow a skill, rule or agent definition
- [llms-txt-writer](https://github.com/shimo4228/llms-txt-writer): writes AI-facing docs (llms.txt, llms-full.txt, FAQ, glossary)
- [context-sync](https://github.com/shimo4228/context-sync): finds overlapping and stale project docs and moves each fact to one home
- [skill-stocktake](https://github.com/shimo4228/skill-stocktake): audits installed skills for staleness, conflicts and redundancy, with a verdict per skill
- [daily-research](https://github.com/shimo4228/daily-research): research feedback engine for your own repos — `claude -p` + macOS launchd writes daily reports per line
- [shimo4228](https://github.com/shimo4228/shimo4228): the author's hub, with AKC next to the other practice lines and their DOIs