Search First

/search-first — Research Before You Code

Before writing a new feature, utility, integration, or picking a library, search for an existing solution first. The best code is code you don't have to write.

This skill is discipline, not mechanism. The how of searching — parallel subagents, live documentation lookup, registry queries — belongs to your agent harness and keeps changing. What this skill pins down is the part that survives those changes: articulate before you search, search by source priority, and end with a recorded verdict. Lead with the discipline; delegate the mechanism.

Step 0 — Articulate the requirement (mandatory, user-visible text)

Before any tool call or subagent, write 2–3 sentences of plain assistant text (not buried inside tool arguments) stating:

• What functionality is needed — concretely, not "X support"
• Language / framework the implementation will use
• Constraints — existing deps, performance limits, license requirements

Why: this externalizes the search query so the user can redirect before you spend effort, and it leaves an auditable record. A subagent call whose args carry the requirement does not satisfy this step — the user reads chat text, not tool arguments. Emit the articulation as text first, then call tools whose arguments may mirror it.

Step 1 — Search by source priority

Check these in order; stop early when you find a strong match:

1. This repo — rg / grep through the relevant modules and tests. The thing

may already exist here.

1. Package registries — npm / PyPI / crates / Go modules for the language in play.
2. MCP servers — already-configured servers first, then the registry. The

capability may already be wired in.

1. Installed skills / agents / tools — your harness may already carry it.
2. Maintained OSS / templates — code-search GitHub before writing net-new code.

Query live documentation at decision time (e.g. context7, or the registry itself) rather than trusting remembered package facts — recommendations age.

Step 2 — Decide, and record a Verdict

Assess candidates holistically: functional fit, maintenance (last commit, issue-response speed), community, docs, license, dependency footprint. Describe strengths and weaknesses in prose. Do not assign numeric scores (8/10), letter grades, or weighted point tables — they manufacture false precision; one evidence-backed verdict is the honest output.

| Verdict | When | Action | |---------|------|--------| | Adopt | Exact match, well-maintained, permissive license | Install and use directly | | Extend | Good foundation, partial fit | Install + thin wrapper / config | | Compose | Several weak matches | Combine 2–3 small packages | | Build | Nothing suitable | Write custom — but informed by what you found |

End every pass with one recognizable verdict line — this line is the deliverable:

Verdict:  —  — 

A search with no verdict line is an incomplete pass: you did the work but left no decision the user (or the next step) can act on — the single most common failure of this workflow. Back the reason with evidence (stars, last-commit date, the specific feature match), never adjectives ("looks good", "popular").

Quick Mode vs Full Mode

• Quick Mode (inline) — for a single obvious need: run Steps 0–2 yourself with

a few searches and state the verdict.

• Full Mode (delegate) — for non-trivial needs: after Step 0, hand the sweep to

a research subagent (whatever your harness provides for solution discovery). Mirror the articulation into its prompt and have it return candidates plus a verdict in the format above. Reserve heavyweight multi-source research for genuinely hard questions — finding a library is lighter than a research report.

When the user says "skip research"

If the user tells you to skip research ("just implement", "no time", "use whatever"), still record the decision as a verdict line before implementing — skipping research is itself a decision, so it gets a verdict like any other pass (this keeps the choice auditable and the course-correct window open):

> Skipping research at your request — I haven't checked for an existing library for X. > Verdict: — — chosen without research at your request; say the word for a 60-second scan.

Why: the user may not know a solution already exists; a silent skip removes their chance to course-correct. After the verdict line, proceed without searching — don't use this as a backdoor to do full research anyway.

Anti-Patterns

• Jumping to code — writing a utility without checking whether one exists.
• Ignoring MCP / installed capability — rebuilding what is already wired in.
• Over-customizing — wrapping a library so heavily its benefit is lost.
• Dependency bloat — installing a massive package for one small feature.
• Search without verdict — doing the legwork but never recording a decision.

Examples (illustrative — verify packages live)

These show how a verdict reads; they are not current package endorsements. Re-search before relying on any specific package.

• Dead-link checking → a maintained, permissively-licensed link-check rule

covering all link types → Verdict: Adopt — textlint-rule-no-dead-link — active maintenance, MIT, full coverage

• Qiita cross-posting → only unmaintained partial wrappers exist →

Verdict: Build — custom — no maintained complete solution; reuse the platform API via an HTTP client

• JP terminology consistency → a dictionary-based checker needing a project config →

Verdict: Extend — textlint-rule-prh — install + a project dictionary

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shimo4228
• Source: shimo4228/search-first
• License: MIT

Install and usage instructions live in the source repository linked above.