SKILL.md
/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:
- Does this already exist in the repo? →
rgthrough relevant modules/tests first
- Is this a common problem? → Search npm/PyPI
- Is there an MCP for this? → Check
~/.claude/settings.jsonand search
- Is there a skill for this? → Check
~/.claude/skills/
- 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 identifies available tools
- Planner incorporates them into the implementation plan
- Avoids "reinventing the wheel" in the plan
With architect agent
The architect should consult researcher for:
- Technology stack decisions
- Integration pattern discovery
- Existing reference architectures
With iterative-retrieval skill
Combine for progressive discovery:
- Cycle 1: Broad search (npm, PyPI, MCP)
- Cycle 2: Evaluate top candidates in detail
- Cycle 3: Test compatibility with project constraints
Examples
Example 1: "Add dead link checking"
Need: Check markdown files for broken links
Search: npm "markdown dead link checker"
Found: textlint-rule-no-dead-link (score: 9/10)
Action: ADOPT — npm install textlint-rule-no-dead-link
Result: Zero custom code, battle-tested solutionExample 2: "Add HTTP client wrapper"
Need: Resilient HTTP client with retries and timeout handling
Search: npm "http client retry", PyPI "httpx retry"
Found: got (Node) with retry plugin, httpx (Python) with built-in retry
Action: ADOPT — use got/httpx directly with retry config
Result: Zero custom code, production-proven librariesExample 3: "Add config file linter"
Need: Validate project config files against a schema
Search: npm "config linter schema", "json schema validator cli"
Found: ajv-cli (score: 8/10)
Action: ADOPT + EXTEND — install ajv-cli, write project-specific schema
Result: 1 package + 1 schema file, no custom validation logicAnti-Patterns
- Jumping to code: Writing a utility without checking if one exists
- Ignoring MCP: Not checking if an MCP server already provides the capability
- Silent skipping: Reporting "nothing found" when a search channel was unavailable
- Over-customizing: Wrapping a library so heavily it loses its benefits
- Dependency bloat: Installing a massive package for one small feature