search-first

name	search-first
description	Search npm / PyPI / MCP / GitHub / existing skills before writing code for any new feature, integration, library selection, or utility. Use whenever the user says 'add X functionality', 'implement Y', 'set up Z', 'integrate W', asks 'what library should I use for...', 'is there a package/client/MCP for...', proposes a specific tool while open to alternatives, or invokes planning.md Phase 0 External Research. Especially when the task adds a dependency, picks between tools, or builds a utility that likely already exists (parser, checker, converter, linter, CI step, E2E framework, payment / auth / API client). DO NOT use for bug fixes, refactoring, config value edits, file summarization, or throwaway scripts whose approach the user already fully specified.
compatibility	Developed and tested on Claude Code; portable to other Agent Skills-compatible agents.
user-invocable	true
origin	shimo4228

/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:

0. 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.
3. Installed skills / agents / tools — your harness may already carry it.
4. 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: <Adopt|Extend|Compose|Build> — <package(s) or "custom"> — <evidence-based reason>

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: <Adopt|Build> — <tentative choice or "custom"> — 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