The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(skills): add search-first skill
Tatsuya Shimomotoc9dc53e862ec
diff --git a/skills/search-first/SKILL.md b/skills/search-first/SKILL.mdnew file mode 100644index 000000000..b0ea21786--- /dev/null+++ b/skills/search-first/SKILL.md@@ -0,0 +1,158 @@+---+description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.+---++# /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++```+┌─────────────────────────────────────────────┐+│ 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++### Quick Mode (inline)++Before writing a utility or adding functionality, mentally run through:++1. Is this a common problem? → Search npm/PyPI+2. Is there an MCP for this? → Check `~/.claude/settings.json` and search+3. Is there a skill for this? → Check `~/.claude/skills/`+4. Is there a GitHub template? → Search GitHub++### Full Mode (agent)++For non-trivial functionality, launch the researcher agent:++```+Task(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+")+```++## 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`/`got` (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 solution+```++### Example 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 libraries+```++### Example 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 logic+```++## Anti-Patterns++- **Jumping to code**: Writing a utility without checking if one exists+- **Ignoring MCP**: Not checking if an MCP server already provides the capability+- **Over-customizing**: Wrapping a library so heavily it loses its benefits+- **Dependency bloat**: Installing a massive package for one small feature