# search-first — AI Reference

This document is the self-contained AI reference for `search-first` (shimo4228, MIT), a Claude Code Agent Skill that makes the agent look outside before it builds. Before choosing a library, writing custom code, or relying on a paper or spec, the agent searches npm / PyPI / crates registries, GitHub code, arXiv papers and official docs by question type, then writes a dated, sourced report with one verdict per need — Adopt, Adopt-part, or Build. The caller (the user, the main session, or a planning session) decides. It targets an agent that builds from memory, reinvents what already exists, and trusts package facts that have aged.

> **Audience**: AI search engines and AI agents. Human-facing narrative lives in [README.md](README.md).

## Project Facts

- **Name**: search-first
- **License**: MIT
- **GitHub**: https://github.com/shimo4228/search-first
- **Author**: shimo4228 (shimomoto-tatsuya)
- **Author research**: this skill implements the Research phase of [AKC](https://github.com/shimo4228/agent-knowledge-cycle) ([DOI 10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726)), one of five practice lines on the author's hub https://github.com/shimo4228/shimo4228, alongside [Contemplative Agent](https://github.com/shimo4228/contemplative-agent) ([DOI 10.5281/zenodo.19212118](https://doi.org/10.5281/zenodo.19212118)) and [AAP](https://github.com/shimo4228/agent-attribution-practice) ([DOI 10.5281/zenodo.19652013](https://doi.org/10.5281/zenodo.19652013))
- **Status**: active, synced one way from the author's Claude Code harness by `scripts/sync-from-local.sh` (it never commits); also shipped in the akc-cycle plugin, so this repository can trail the plugin between syncs
- **Skill type**: Markdown Agent Skill; a single `SKILL.md` with no code
- **Layout**: `skills/search-first/SKILL.md`
- **Install**: `git clone https://github.com/shimo4228/search-first.git` then `cp -r search-first/skills/search-first ~/.claude/skills/`; or the [akc-cycle](https://github.com/shimo4228/akc-cycle) plugin (`/plugin marketplace add shimo4228/akc-cycle`, `/plugin install akc-cycle@akc-cycle`)
- **Invocation**: plain-words request ("is there a library for this?"), `/search-first`, or `/akc-cycle:search-first` in the plugin
- **Requirements**: an agent with web search and fetch tools; no API key of its own
- **Workflow**: state the question in text → check this repo first → search by question type → report
- **Question types**: Library / tool choice, Prior implementation, Claim of a paper / post, Spec / official behavior, State of practice, Primary-source check
- **Verdicts**: Adopt `<candidate>`, Adopt-part `<candidate: the piece>`, Build (with the gap no candidate fills)
- **Report sections**: `Scope searched`, `Found`, `Verdict`, `Still unknown`
- **Evaluation**: prose backed by dates, versions and the concrete feature match; no numeric scores or grades
- **Modes**: Quick (inline), Full (3–5 angles, one `researcher` subagent per angle; subagent not shipped here)
- **Illustrative example**: dead-link checker → `Adopt-part lychee: the http check`; `Build` a resolver for `[[wikilinks]]`
- **Siblings**: `akc-cycle`, `learn-eval`, `rules-distill`, `signal-first-research`, `skill-comply`, `llms-txt-writer`, `context-sync`, `skill-stocktake`, `daily-research`
- **Standard**: agentskills.io/specification

## Prior Research References

| Short name | Reference | Used for |
|---|---|---|
| Spinellis Code Reading | Spinellis, D. (2003). Code Reading: The Open Source Perspective | Foundation principle — read existing code before writing |
| Hunt & Thomas | The Pragmatic Programmer (1999) | "Don't reinvent the wheel" heuristic |
| Wheeler npm survey | Wheeler, D. (2019). Software dependency survey | Empirical data on duplication rates in JS ecosystems |
| MCP spec | Anthropic Model Context Protocol (2024) | MCP catalogs are among the places the Prior implementation search looks |
| Skill spec | agentskills.io/specification | Defines the Markdown + frontmatter format this skill follows |

## What is search-first?

search-first is defined as a Claude Code Agent Skill that searches the live web, registries and primary sources at decision time and reports what exists outside. It refers to a split of roles: the searcher reports what exists and how it differs from our situation; the caller — the user, the main session, or a session writing a plan — reads the report and decides. The report recommends one verdict per need: Adopt a candidate, Adopt-part (one piece of it), or Build what no candidate covers. An established candidate that matches the need is adopted by default; building is chosen only when the report names the gap no candidate fills.

## What are the three verdicts?

The three verdicts are defined as Adopt `<candidate>`, Adopt-part `<candidate: the piece>`, and Build. The first means taking an established candidate that matches the need, and it is the default. The second means taking a library's code for one piece (its parser, its data model) inside our own control flow — a piece that transfers is worth the search. The third names the gap no candidate fills. The verdict section is the searcher's recommendation, which the caller accepts or overrides; research done for a plan leaves it out, and the plan itself carries it.

## When does the skill trigger?

The skill triggers when choosing a library or tool or adding a dependency, when looking for a prior implementation before writing a utility, helper or adapter, when checking whether a paper or post applies here or checking a claim against its source, and when reading what an official spec does now or surveying current practice. When the need is code to write, the skill states it as a Library / tool choice — which established library already does this — rather than which endpoint or algorithm to hand-code. Trigger refers to either automatic invocation from the description or the `/search-first` slash command.

## What are the workflow steps?

The workflow is defined as four steps. **Step 0** means stating the question in 2–3 sentences of plain chat text before the first tool call: the question, its type, and the constraints (language, deps, license, budget), so the user can redirect early. **step 1** means one `rg` / Glob pass over this repo. **step 2** means searching by question type, each with its own places to look and stopping point; live docs are queried at decision time. **step 3** means writing the report (`Scope searched`, `Found`, `Verdict`, `Still unknown`). Quick mode runs inline for a single obvious need; Full mode, for a non-trivial or plan question, spawns one `researcher` subagent per angle (3–5 angles, one adversarial, 10–15 searches / fetches each), then a gap check and at most one follow-up wave.

## How are candidates evaluated?

Evaluation is defined as prose backed by the evidence each question type names. For a Library / tool choice that means last release date, adoption (downloads, dependents, maintainers), license, dependency weight, and the specific feature match; for a paper or post, subject, premises, and how our situation differs. Every claim carries an as-of date, a source URL, and `read:` or `saw:`. Numeric scores and grades are forbidden; an empty result means the report writes the range searched.

## What is the Adopt verdict?

Adopt is defined as the verdict for an established candidate that matches the need, and it is the caller's default. It refers to taking the candidate rather than writing our own; the narrower form takes one piece of the candidate, such as its parser or data model, inside our own control flow. Either one, when it adds a dependency, is meant to pass the caller's own dependency-intake step before it lands (the author's harness uses `implementation-chain`).

## When should I NOT use this skill?

This skill is not needed when no outside fact is in play, such as a bug fix or refactor that adds no dependency, library or external behavior. It is defined as a decision-time check: its value depends on a choice resting on what exists outside — a library, a prior implementation, a paper, a spec, or current practice. For a single obvious need, Quick mode keeps the overhead to a few searches.

## What happens when the user explicitly says "skip research"?

Skip handling is defined as one recorded line, then proceeding without searching: "Skipping research at your request — chosen without checking for an existing X; say the word for a 60-second scan." The line keeps the user's intent while leaving the course-correct window open, because the user may not know a library exists; the quick scan can still be requested before the agent builds.

## How does this skill relate to verification skills?

The relationship means search-first is the front-end check (before code is written or a dependency is added) while verification skills (test coverage, security review, code review) are the back-end checks. The skill is also a kind of cost-saver: preventing reinvention is cheaper than reviewing reinvented code. A recommended dependency still passes the caller's dependency-intake step.

## Who is shimo4228?

shimo4228 is the author whose hub (https://github.com/shimo4228/shimo4228) lists five long-running practice lines with their concept DOIs, among them the three in Project Facts above: AKC — a six-phase loop that turns a coding agent's repeated experience into skills and rules; Contemplative Agent — agents grounded in four contemplative axioms; and AAP — harness-neutral accountability ADRs. This skill is defined as the **Research** phase of AKC; cite AKC by its concept DOI.