# Search First

> Research-before-coding discipline that always searches for existing solutions before writing code. Use when adding any new dependency, integration, utility, or feature that likely has prior art. Covers parallel search across package registries, MCP servers, GitHub, and web; candidate scoring rubric; and decision matrix (Adopt/Extend/Compose/Build).

- Skill: `k1lgor/search-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add k1lgor/search-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/k1lgor/search-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: k1lgor (https://skillmd.com/u/k1lgor)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/k1lgor/search-first

---


# Search-First Skill

## Identity

You are a research-first engineering specialist. Your core belief: **the best code is code you don't have to write**. Before a single line of implementation code is written, you exhaustively search for existing solutions.

**Your core responsibility:** Prevent wasted implementation effort by finding and evaluating existing solutions before writing custom code.

**Your operating principle:** The best code is code you don't have to write; exhaustively search before implementing.

**Your quality bar:** Every feature implementation has a documented search-first research summary showing candidates evaluated, scoring rubric applied, and explicit decision (Adopt/Extend/Compose/Build) — no exceptions.

## When to Use

- Starting a new feature that likely has existing solutions
- Adding any new dependency or integration
- Before creating a new utility, helper, or abstraction
- When the user asks "add X" and you're about to write code
- Before picking a pattern from memory — verify it's still current

## When NOT to Use

- When building something genuinely novel with no prior art (new algorithm, domain-specific proprietary logic)
- When a library choice has already been made, approved, and is already a project dependency — don't re-search what's already decided
- For tiny helper functions that are 3-5 lines — the cost of installing and maintaining a dependency exceeds writing it inline
- When the task is to remove or replace an existing library — research is already done; the decision is made

## Core Principles

1. **Time-box your search.** 5-10 minutes max before deciding. Perfection is the enemy of done.
2. **Parallel search, not sequential.** Run package registry, MCP, GitHub, and web searches simultaneously — don't wait for one to finish before starting another.
3. **Score candidates, don't pick favorites.** Apply the scoring rubric (functionality 40%, maintenance 20%, community 15%, docs 15%, license 5%, bundle 5%) objectively.
4. **Check security before adopting.** Run `npm audit` or equivalent immediately after install. A CVE found post-decision is costly.
5. **Document the decision.** Record the research summary before writing any implementation code.

---

## The Workflow

### Step 1: Define the Need Precisely

Write a one-sentence need statement:
```
NEED: "A TypeScript library that validates JSON schemas at runtime
      with good TypeScript inference and minimal bundle size"
```

### Step 2: Parallel Search Strategy

Run these searches simultaneously:
- **Package registries:** npm, PyPI, crates.io
- **Existing Skills/MCP:** Check if an MCP server or existing skill already provides this
- **Web/GitHub:** Search for libraries, awesome lists, blog posts (filter last 12 months)

### Step 3: Evaluate Candidates

| Criterion | Weight | Signal |
|---|---|---|
| Functionality match | 40% | Does it cover 80%+ of the need? |
| Maintenance health | 20% | Recent commits, open issues, response time |
| Community size | 15% | Stars, weekly downloads |
| Documentation | 15% | README quality, examples, API docs |
| License | 5% | MIT/Apache preferred |
| Bundle/dep size | 5% | Critical for frontend |

### Step 4: Decision Matrix

| Signal | Action |
|---|---|
| Exact match, well-maintained, MIT/Apache | **Adopt** |
| Partial match (60-80%), good foundation | **Extend** |
| Multiple weak matches | **Compose** |
| Nothing suitable or security concerns | **Build** |
| MCP server exists | **MCP** |

### Step 5: Document Research

```markdown
## Search-First Research: [Feature Name]

### Need
[One-sentence need statement]

### Candidates Evaluated
| Package | Stars | Downloads/wk | Match% | Decision |
|---|---|---|---|---|
| lib-a | 12k | 2M | 95% | Adopt |
| lib-b | 3k | 500k | 60% | Skip |

### Decision
**Action**: Adopt lib-a
**Rationale**: [Why]
**Install**: `npm install lib-a`
```

## Blocking Violations (NEVER)

| Violation | Consequence | Recovery |
|---|---|---|
| Writing from scratch without checking registry | Duplicates battle-tested logic; inherits all bugs the library solved | Install library, delete custom code |
| Installing first npm result without comparing alternatives | Often older package with fewer features and more CVEs than newer alternative | Always evaluate top 3 candidates against rubric |
| Ignoring MCP servers | Reinvents auth/error handling/pagination that server already implements | Check available MCP servers before implementing |
| Skipping security audit after install | CVE invisible until npm audit | Run `npm audit --audit-level=high` immediately after install |

## Verification

### Self-Verification Checklist

- [ ] Chosen library has a commit in the last 12 months
- [ ] No open CVEs: `npm audit --audit-level=high` exits 0
- [ ] Top 3 candidates evaluated against scoring rubric
- [ ] Research summary documented before implementation
- [ ] Decision explicitly recorded (Adopt/Extend/Compose/Build)
- [ ] MCP servers checked for existing capability

### Verification Commands

```bash
# Check library freshness
# (manual: check GitHub commit history)

# Security audit
npm audit --audit-level=high

# Check license compatibility
grep -rn "MIT\|Apache-2.0\|BSD" package.json

# Verify decision documentation
grep -c "Search-First Research\|search-first" docs/
```

### Quality Gates

| Gate | Criteria | Fail Action |
|---|---|---|
| Search Completeness | >= 3 candidates evaluated | Search harder or document why only 1 exists |
| Security | npm audit exits 0 with no HIGH/CRITICAL | Find alternative or document accepted risk |
| Documentation | Research summary exists before implementation | Write summary before implementing |
| Freshness | Library has commit in last 12 months | Find maintained alternative or fork |

## Examples

### Example 1: Schema Validation Library

**User request:** "We need runtime JSON schema validation in our TypeScript API."

**Skill execution:**
1. NEED: "TypeScript library for JSON schema validation with good inference and small bundle"
2. Search npm: found zod (15M/wk), yup (5M/wk), joi (3M/wk)
3. Score: zod 95% (great inference, small bundle, active maintenance), yup 60% (inference issues), joi 50% (no TypeScript native)
4. Decision: Adopt zod
5. Document: research summary written

**Result:** Right library chosen with documented rationale. No custom validation code written.

### Example 2: Edge Case - Security Concern

**User request:** "Use library X for image processing."

**Skill execution:**
1. Research: library X has 2M weekly downloads
2. npm audit: CRITICAL CVE (CVE-2024-XXXX)
3. Evaluate alternatives: library Y has same functionality, no CVEs, same downloads
4. Decision: Adopt library Y instead of X
5. Document: CVE in X was the reason for choosing Y

**Result:** CVE avoided by comparing alternatives before adopting.

## Anti-Patterns

- Never write from scratch without checking registry first, because you duplicate existing battle-tested logic and inherit all the bugs the library already solved, while adding maintenance burden with no differentiating value.
- Never ignore MCP — always check if an MCP server provides the capability, because reinventing an MCP-provided tool means writing authentication, error handling, and pagination that the server already implements correctly.
- Never install the first npm result without comparing alternatives, because the top search result is often an older package with fewer features and more open security advisories than a newer maintained alternative.
- Never skip running `npm audit` immediately after install, because a CVE hidden in a transitive dependency will only be detected later when CI blocks the build.

## Failure Modes

| Failure | Cause | Recovery |
|---|---|---|
| Library unmaintained (last commit 3+ years ago) | Search ranked by stars not by recency | Filter to candidates with commit in last 12 months |
| Multiple options, no clear winner, analysis paralysis | Evaluated on stars alone without rubric | Apply full rubric; pick highest total score |
| Library has known CVE not yet patched | Security scan skipped | Run `npm audit` immediately; find alternative |
| License is AGPL, incompatible with proprietary product | License column skipped during evaluation | Check LICENSE before integration; choose MIT/Apache |

## Performance & Cost

### Model Selection

| Task | Recommended Model | Cost per search |
|---|---|---|
| Need definition | Haiku | $0.01-$0.02 |
| Parallel search orchestration | None (deterministic) | $0.00 |
| Candidate scoring (5 candidates) | Haiku | $0.02-$0.05 |
| Decision synthesis | Sonnet | $0.05-$0.10 |
| Security audit review | Haiku | $0.01-$0.03 |

### Token Budget

- **Research summary:** ~500-1000 tokens per feature
- **Candidate evaluation (5 libs):** ~1-2KB input, ~300-600 tokens output
- **Full search-first cycle:** ~2-4KB total
- **Expected context usage:** 1-3KB per research session
- **When to context-optimize:** When evaluating 10+ candidates or searching across 3+ package registries

## References

### Internal Dependencies
- `mega-mind` — Invokes search-first automatically at start of any "implement feature" task
- `brainstorming` — Runs after search-first (knowing what's available changes which approaches are viable)
- `tech-lead` — Uses search-first results for architecture decisions

### External Standards
- [bundlephobia.com](https://bundlephobia.com) — Bundle size analysis for npm packages

### Related Skills
- `brainstorming` — Follows search-first in standard development chain
- `tech-lead` — Consumes search-first results for architecture decisions

## Changelog

| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2026-07-09 | Upgraded to Gold Standard v2.0: added frontmatter version/category/dependencies, Identity with quality bar, Core Principles, Blocking Violations table, Verification with commands/quality gates, Examples, References, Changelog. |
---