Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
new file mode 100644
index 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