AI_template/.claude/skills/search-first/SKILL.md

name, description, disable-model-invocation, argument-hint

name	description	disable-model-invocation	argument-hint
search-first	Research existing solutions before writing custom code. Checks npm/PyPI/MCP/GitHub for packages, then decides between Adopt, Extend, Compose, or Build.	true	[feature or problem to research]

Search Before Building

Research existing solutions for: $ARGUMENTS

Context

Project dependencies: !cat package.json 2>/dev/null | jq '.dependencies // {} | keys' 2>/dev/null || echo "No package.json"

Project tech stack: !cat RECOMMENDATIONS.md 2>/dev/null | head -30 || echo "No RECOMMENDATIONS.md"

Steps

1. Define the need

Clarify what exactly is needed:

• Problem statement: What problem does this solve?
• Requirements: Must-haves vs nice-to-haves
• Constraints: License, bundle size, browser support, security

2. Search for existing solutions

Search in order of preference:

1. Already in project — Check if a dependency already solves this:
   • Read package.json / requirements.txt / go.mod
   • Search codebase for similar implementations
2. Package registries — Search npm, PyPI, crates.io, pkg.go.dev
3. MCP servers — Check if an MCP server provides this capability
4. GitHub — Search for well-maintained repos with the needed functionality
5. Framework built-ins — Check if the framework already provides this (e.g., Next.js Image, React Server Actions)

For each candidate, evaluate:

Criterion	Check
Maintenance	Last commit < 6 months, active issues
Popularity	Downloads/stars relative to category
Bundle size	Check via bundlephobia or equivalent
License	Compatible with project license
Security	No known CVEs, dependency tree reasonable
Types	TypeScript types included or available
API quality	Clean API, good docs, follows conventions

3. Decision matrix

Apply this decision framework:

┌─────────────────────────────────────────────────────┐
│ Does an existing solution meet ≥80% of requirements? │
└─────────────────────────┬───────────────────────────┘
                          │
              YES ────────┼──────── NO
              │           │         │
              ▼           │         ▼
     Is it well-maintained?       Can you compose
     Is the API acceptable?       2-3 packages to
              │                   cover 100%?
         YES  │  NO                │
          │   │   │           YES  │  NO
          ▼   │   ▼            │   │   │
       ADOPT  │  EXTEND        ▼   │   ▼
              │  (fork/wrap)  COMPOSE  BUILD
              │                        (custom)

Strategy	When	Risk Level
Adopt	Solution fits ≥80%, well-maintained, good API	Low
Extend	Good base but needs customization (wrapper/plugin)	Medium
Compose	No single solution, but 2-3 packages combine well	Medium
Build	No viable existing solution, or critical security/performance need	High

4. Report

## Research: [Feature]

### Candidates Found
| Package | Downloads | Size | License | Last Updated | Fit |
|---------|-----------|------|---------|-------------|-----|
| ...     | ...       | ...  | ...     | ...         | ... |

### Recommendation: [ADOPT / EXTEND / COMPOSE / BUILD]

**Selected**: [package name or "custom implementation"]
**Reason**: [why this is the best choice]
**Trade-offs**: [what you give up]

### Implementation Notes
- [How to integrate]
- [Estimated effort]

5. Anti-patterns to avoid

• NIH syndrome — Building custom when a mature solution exists
• Dependency hoarding — Adding a package for a 5-line function
• Popularity bias — Choosing the most popular, not the best fit
• Stale research — Not checking if a previously rejected package has improved
• Ignoring composition — Not considering that 2 small libraries > 1 bloated one