# 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, report, let the caller pick:
  - **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** with the gap no candidate fills. 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