llms-full.txt git:20260608.54a1c6dA

Immutable. This exact content never changes and is served at /api/v1/blob/4f235ff45d6b2ddc.

# 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 searches npm, PyPI, MCP registries, GitHub, and existing skills in parallel, scores candidates against a six-dimension rubric, then makes a four-way decision: Adopt, Extend, Compose, or Build. The skill is a kind of duplication-prevention tool that 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, invokes the researcher agent
- **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**: 6 steps — Step 0 Articulate (mandatory text output), Need, Parallel Search, Evaluate, Decide, Implement
- **Decision verdicts**: Adopt, Extend, Compose, Build (4-way matrix)
- **Search targets**: npm, PyPI, MCP, GitHub, existing skills
- **Scoring rubric**: 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 (researcher agent)
- **Real example**: dead-link checker → adopted `textlint-rule-no-dead-link` (score 9/10), 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 has six steps. **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. **Steps 1-5** then follow: Need Analysis (define functionality, identify language and framework constraints), Parallel Search (npm, PyPI, MCP, GitHub, existing skills — all in parallel), Evaluate (score against six dimensions), Decide (apply the four-way matrix), and Implement (install the chosen solution with minimal custom code). The Parallel Search step is the load-bearing one — it refers to spawning a researcher agent that fans out across registries. The skill also defines a "skip-research" handling rule for competing prompts — see the dedicated Q&A below.

## What is the six-dimension scoring rubric?

The six dimensions are defined as 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). Each dimension contributes to a candidate's score. The rubric is a kind of structured shortcut — it forces the agent to examine factors that would otherwise be skipped under time pressure.

## 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. Instead the agent emits a one-paragraph acknowledgement that names the tentative library/approach, states the reason in one line, and offers a 60-second scan if the user wants to course-correct. The pattern is "Implementing directly as requested. I haven't checked if there's an existing library for X — let me know if you want a 60-second scan first. Going with [choice] because [1-line reason]." This single paragraph preserves the user's intent while keeping the course-correct window open, because the user may not know an existing library exists. If the user replies "go ahead," the agent proceeds without searching. The articulation paragraph is the only mandated step in this branch; 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.