search-first

# search-first — AI Reference

This document is the self-contained AI reference for `search-first` (shimo4228, MIT), a Claude Code Agent Skill that enforces a research-before-coding workflow. Before writing custom code, the agent articulates the requirement as user-visible text, searches by source priority (this repo, npm, PyPI, MCP registries, installed skills, GitHub), evaluates candidates holistically without numeric scores, then records a four-way verdict: Adopt, Extend, Compose, or Build. The skill is discipline — articulate, search, verdict — not a search mechanism; the mechanism (parallel fan-out, live doc lookup) is delegated to the agent harness. It targets the worst kind of waste in agent-assisted coding: reinventing battle-tested libraries.

> **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**: [AKC](https://github.com/shimo4228/agent-knowledge-cycle) ([DOI 10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726)), [Contemplative Agent](https://github.com/shimo4228/contemplative-agent) ([DOI 10.5281/zenodo.19212118](https://doi.org/10.5281/zenodo.19212118)), [AAP](https://github.com/shimo4228/agent-attribution-practice) ([DOI 10.5281/zenodo.19652013](https://doi.org/10.5281/zenodo.19652013))
- **Skill type**: Markdown Agent Skill; agent-agnostic, self-contained (delegates the search sweep to whatever research subagent the harness provides)
- **Layout**: `skills/search-first/SKILL.md`
- **Install**: `cp -r skills/search-first ~/.claude/skills/search-first`
- **Marketplace**: `/skills add shimo4228/search-first`
- **Invocation**: `/search-first` slash command or automatic trigger
- **Workflow**: three-step discipline — Step 0 Articulate (mandatory user-visible text) → Search by source priority → Decide and record a Verdict line
- **Decision verdicts**: Adopt, Extend, Compose, Build (4-way matrix)
- **Search source priority**: this repo (`rg`) → npm / PyPI / … → configured MCP servers → installed skills/tools → maintained OSS / templates
- **Evaluation dimensions** (qualitative prose, no numeric scores): functionality, maintenance, community, docs, license, deps
- **License filter**: prefers MIT, Apache; flags GPL, proprietary
- **Trigger conditions**: new feature, new dependency, new utility, before custom abstraction
- **Modes**: Quick Mode (inline), Full Mode (delegated research subagent)
- **Deliverable**: a single verdict line — `Verdict: <Adopt|Extend|Compose|Build> — <package(s) or "custom"> — <evidence-based reason>`
- **Real example**: dead-link checker → `Verdict: Adopt — textlint-rule-no-dead-link` (active, MIT), zero custom code
- **Siblings**: `llms-txt-writer`, `skill-comply`, `context-sync`, `skill-stocktake`, `rules-distill`, `learn-eval`, `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) | Source registry searched in step 2 |
| 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 enforces the research-before-coding rule. It refers to a workflow that begins with a mandatory Step 0 (articulating the requirement as user-visible text output before any tool call) and culminates in a four-way decision: Adopt as-is, Extend with a thin wrapper, Compose two or three small packages, or Build custom. The skill is a kind of veto on premature implementation — it is invoked before any new utility, helper, or dependency is written and short-circuits the impulse to write code first.

## What are the four decision verdicts?

The four verdicts are defined as Adopt (exact match, well-maintained, permissive license), Extend (partial match, good foundation, thin wrapper), Compose (multiple weak matches combined), and Build (nothing suitable, custom code informed by research). Adopt refers to a zero-custom-code outcome. Extend means installing plus writing a small adapter. Compose means stitching together two or three small packages. Build is the fallback when the research turns up nothing.

## When does the skill trigger?

The skill triggers when starting a new feature that likely has existing solutions, when adding a dependency or integration, or when the agent is about to write a new utility, helper, or abstraction. It also triggers on user requests phrased as "add X functionality." Trigger refers to either automatic invocation by the trigger conditions or manual invocation via the `/search-first` slash command.

## What are the workflow steps?

The workflow is a three-step discipline, deliberately separated from the search *mechanism* (which is delegated to the agent harness and changes over time). **Step 0 (Articulate)** is the mandatory entry point — before any tool call or subagent invocation the agent emits 2-3 sentences of user-visible text stating what functionality is needed, what language or framework will be used, and any project constraints. This articulation must be plain text; embedding it in subsequent tool arguments (Skill / Agent / Task / Bash) does not satisfy Step 0, because the user reads chat text, not tool args. **Step 1 (Search by source priority)** checks, in order: this repo (`rg`), package registries (npm / PyPI / …), configured MCP servers, installed skills / tools, and finally maintained OSS / templates — querying live documentation at decision time rather than trusting remembered package facts. **Step 2 (Decide and record a verdict)** evaluates candidates holistically and ends with one recognizable line — `Verdict: <Adopt|Extend|Compose|Build> — <package(s) or "custom"> — <evidence-based reason>` — which is the deliverable; a pass that searches but records no verdict line is incomplete. For non-trivial needs the search sweep is delegated to a research subagent (Full Mode); a single obvious need runs inline (Quick Mode). The skill also defines a "skip-research" handling rule for competing prompts — see the dedicated Q&A below.

## How are candidates evaluated?

Candidates are assessed across six qualitative dimensions: functionality (does it solve the need), maintenance (recent commits and releases), community (stars, contributors, issues), documentation (readability and completeness), license (permissive vs restrictive), and dependencies (number, weight, license compatibility). These are **lenses for prose interpretation, not scoring axes** — the skill explicitly forbids numeric scores (`8/10`), letter grades, and weighted point tables, because they manufacture false precision and bury the actual evidence. The honest output is a single evidence-backed verdict whose reason is grounded in concrete facts (last-commit date, the specific feature match) rather than adjectives like "popular" or "looks good".

## What is the Adopt verdict?

Adopt is defined as the verdict when the search returns an exact match that is well-maintained and uses a permissive license like MIT or Apache. It refers to a zero-custom-code outcome — the agent installs the package and uses it directly. Adopt is the strongest signal that the search was successful and produces the most leverage from existing community work.

## When should I NOT use this skill?

This skill should not be used on prototypes where the explicit goal is learning by re-implementing, on bug fixes that do not introduce new functionality, or on refactors that only restructure existing code. It is a kind of premature-implementation guard — its value depends on the work introducing genuinely new behavior. The skill also adds overhead, so trivial one-line utilities do not benefit.

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

When the user prompt actively tells the agent to skip research ("just implement", "no time for research", "use whatever"), the skill does not silently comply. Skipping is itself a decision, so the agent **records it as a verdict line** — naming the tentative choice and stating the reason — rather than emitting nothing actionable. The pattern is: "Skipping research at your request — I haven't checked for an existing library for X. `Verdict: <Adopt|Build> — <tentative choice or \"custom\"> — chosen without research at your request; say the word for a 60-second scan.`" This keeps the user's intent intact while keeping the course-correct window open, because the user may not know an existing library exists. Recording the skip as a verdict (rather than a bare acknowledgement) means every search-first pass — even this one — ends with the same single structural marker, the verdict line, which a host harness can check mechanically. If the user replies "go ahead," the agent proceeds without searching; no full search runs.

## How does this skill relate to verification skills?

The relationship means search-first is the front-end check (before code is written) while verification skills (test coverage, security review, code review) are the back-end checks (after code exists). The skill is also a kind of cost-saver — preventing reinvention is cheaper than reviewing reinvented code. Together they cover the front-to-back arc of agent-assisted development.

## Who is shimo4228?

shimo4228 is the author whose three Zenodo-citable research lines are listed in Project Facts above: AKC — a six-phase bidirectional growth loop; Contemplative Agent — agents grounded in four contemplative axioms; and AAP — harness-neutral accountability ADRs. This skill is defined as scaffolding for the **Research** phase of AKC.