---

name: search-first description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent. origin: ECC

/search-first — Research Before You Code

Systematizes the "search for existing solutions before implementing" workflow.

Trigger

Use this skill when:

• Starting a new feature that likely has existing solutions
• Adding a dependency or integration
• The user asks "add X functionality" and you're about to write code
• Before creating a new utility, helper, or abstraction

Workflow

┌─────────────────────────────────────────────┐
│  0. TOOL AVAILABILITY PREFLIGHT             │
│     Check search channels before relying on │
│     them; report skipped channels honestly   │
├─────────────────────────────────────────────┤
│  1. NEED ANALYSIS                           │
│     Define what functionality is needed      │
│     Identify language/framework constraints  │
├─────────────────────────────────────────────┤
│  2. PARALLEL SEARCH (researcher agent)      │
│     ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│     │  npm /   │ │  MCP /   │ │  GitHub / │  │
│     │  PyPI    │ │  Skills  │ │  Web      │  │
│     └──────────┘ └──────────┘ └──────────┘  │
├─────────────────────────────────────────────┤
│  3. EVALUATE                                │
│     Score candidates (functionality, maint, │
│     community, docs, license, deps)         │
├─────────────────────────────────────────────┤
│  4. DECIDE                                  │
│     ┌─────────┐  ┌──────────┐  ┌─────────┐  │
│     │  Adopt  │  │  Extend  │  │  Build   │  │
│     │ as-is   │  │  /Wrap   │  │  Custom  │  │
│     └─────────┘  └──────────┘  └─────────┘  │
├─────────────────────────────────────────────┤
│  5. IMPLEMENT                               │
│     Install package / Configure MCP /       │
│     Write minimal custom code               │
└─────────────────────────────────────────────┘

Decision Matrix

| Signal | Action | |--------|--------| | Exact match, well-maintained, MIT/Apache | Adopt — install and use directly | | Partial match, good foundation | Extend — install + write thin wrapper | | Multiple weak matches | Compose — combine 2-3 small packages | | Nothing suitable found | Build — write custom, but informed by research |

How to Use

Step 0: Tool Availability Preflight

This is agent guidance, not an executable setup script. Check only the channels that are relevant to the task and project in front of you.

| Channel | Check | If missing | |---------|-------|------------| | Repository search | rg --files and targeted rg queries | State that only visible files were inspected | | Package registry | npm --version, python -m pip --version, or project package manager | Use web/docs search and avoid claiming registry coverage | | GitHub CLI | gh auth status | Use public web or local git history only | | MCP/docs tools | Available tool list or local MCP config | Fall back to official docs/web search | | Skills directory | ls ~/.claude/skills ~/.codex/skills where applicable | Say no local skill catalog was available |

Quick Mode (inline)

Before writing a utility or adding functionality, mentally run through:

1. Does this already exist in the repo? → rg through relevant modules/tests first
2. Is this a common problem? → Search npm/PyPI
3. Is there an MCP for this? → Check ~/.claude/settings.json and search
4. Is there a skill for this? → Check ~/.claude/skills/
5. Is there a GitHub implementation/template? → Run GitHub code search for maintained OSS before writing net-new code

Full Mode (agent)

For non-trivial functionality, launch the researcher agent:

Agent(subagent_type="general-purpose", prompt="
  Research existing tools for: [DESCRIPTION]
  Language/framework: [LANG]
  Constraints: [ANY]

  Search: npm/PyPI, MCP servers, Claude Code skills, GitHub
  Return: Structured comparison with recommendation
")

Older Claude Code docs may call this Task(...); use the current agent/subagent tool name exposed by the active harness.

Search Shortcuts by Category

Development Tooling

• Linting → eslint, ruff, textlint, markdownlint
• Formatting → prettier, black, gofmt
• Testing → jest, pytest, go test
• Pre-commit → husky, lint-staged, pre-commit

AI/LLM Integration

• Claude SDK → Context7 for latest docs
• Prompt management → Check MCP servers
• Document processing → unstructured, pdfplumber, mammoth

Data & APIs

• HTTP clients → httpx (Python), ky/undici (Node)
• Validation → zod (TS), pydantic (Python)
• Database → Check for MCP servers first

Content & Publishing

• Markdown processing → remark, unified, markdown-it
• Image optimization → sharp, imagemin

Integration Points

With planner agent

The planner should invoke researcher before Phase 1 (Architecture Review):

• Researcher identifie