search-first

/search-first — Research Before You Code

Systematize the workflow of "searching for existing solutions before implementing."

Trigger

Use this Skill in the following scenarios:

• Starting to develop a new feature that very likely already has an existing solution
• Adding a dependency or integration
• The user asks to "add X feature" and you are about to write code
• Before creating a new utility class, helper function, or abstraction layer

Workflow

┌─────────────────────────────────────────────┐
│  1. 需求分析 (NEED ANALYSIS)                 │
│     定义所需功能                             │
│     识别语言/框架约束                        │
├─────────────────────────────────────────────┤
│  2. 并行搜索 (调研智能体 researcher agent)    │
│     ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│     │  npm /   │ │  MCP /   │ │  GitHub / │  │
│     │  PyPI    │ │  技能    │ │  Web      │  │
│     └──────────┘ └──────────┘ └──────────┘  │
├─────────────────────────────────────────────┤
│  3. 评估 (EVALUATE)                         │
│     为候选方案打分（功能、维护、             │
│     社区、文档、许可证、依赖）               │
├─────────────────────────────────────────────┤
│  4. 决策 (DECIDE)                           │
│     ┌─────────┐  ┌──────────┐  ┌─────────┐  │
│     │  采用   │  │   扩展   │  │   自研  │  │
│     │ (Adopt) │  │  (Extend)│  │ (Build) │  │
│     └─────────┘  └──────────┘  └─────────┘  │
├─────────────────────────────────────────────┤
│  5. 实施 (IMPLEMENT)                        │
│     安装包 / 配置 MCP /                     │
│     编写最少量的自定义代码                   │
└─────────────────────────────────────────────┘

Decision Matrix

Signal	Action
Exact match, well maintained, MIT/Apache license	Adopt — Install and use directly
Partial match, good foundation	Extend — Install + write a lightweight wrapper layer
Multiple weak matches	Compose — Combine 2-3 small packages
No suitable solution found	Build — Write custom code, but based on research findings

How to Use

Quick Mode (inline use)

Before writing a utility class or adding a feature, run through this in your head:

1. Does it already exist in the repository? → First use rg to search related modules/tests
2. Is this a common problem? → Search npm/PyPI
3. Is there a related MCP? → Check ~/.claude/settings.json and search
4. Is there a related Skill? → Check ~/.claude/skills/
5. Is there a GitHub implementation/template? → Before writing entirely new code, run GitHub code search for well-maintained open source software (OSS)

Full Mode (Agent Delegation)

For non-trivial features, launch a Researcher Agent:

Task(subagent_type="general-purpose", prompt="
  调研现有的工具，针对：[功能描述]
  语言/框架：[LANG]
  约束条件：[ANY]

  搜索范围：npm/PyPI, MCP 服务器, Claude Code 技能, GitHub
  返回结果：带建议的结构化对比报告
")

Category Search Shortcuts

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 → Refer to Context7 for the latest documentation
• Prompt management → Check the MCP server
• Document processing → unstructured, pdfplumber, mammoth

Data and API

• HTTP client → httpx (Python), ky/got (Node)
• Validation → zod (TS), pydantic (Python)
• Database → Prioritize checking the MCP server

Content and Publishing

• Markdown processing → remark, unified, markdown-it
• Image optimization → sharp, imagemin

Integration Points

Integration with Planner Agent

The planner should call the researcher before Phase 1 (Architecture Review):

• The researcher identifies available tools
• The planner incorporates them into the implementation plan
• Avoid "reinventing the wheel" in the plan

Integration with Architect Agent

The architect should consult the researcher regarding:

• Technology stack decisions
• Integration pattern discovery
• Existing reference architectures

Integrate with the Iterative-retrieval Skill

Use in combination for progressive discovery:

• Round 1: Broad search (npm, PyPI, MCP)
• Round 2: Detailed evaluation of preferred candidates
• Round 3: Test compatibility with project constraints

Examples

Example 1: "Add dead link checking"

需求：检查 markdown 文件中的损坏链接
搜索：npm "markdown dead link checker"
发现：textlint-rule-no-dead-link (得分: 9/10)
行动：采用 (ADOPT) — npm install textlint-rule-no-dead-link
结果：零自定义代码，经受过实战检验的解决方案

Example 2: "Add an HTTP client wrapper layer"

需求：具备重试和超时处理能力的弹性 HTTP 客户端
搜索：npm "http client retry", PyPI "httpx retry"
发现：带重试插件的 got (Node), 内置重试的 httpx (Python)
行动：采用 (ADOPT) — 直接使用带重试配置的 got/httpx
结果：零自定义代码，生产环境验证过的库

Example 3: "Add a configuration file Linter"

需求：根据 Schema 验证项目配置文件
搜索：npm "config linter schema", "json schema validator cli"
发现：ajv-cli (得分: 8/10)
行动：采用 + 扩展 (ADOPT + EXTEND) — 安装 ajv-cli，编写项目特定的 schema
结果：1 个包 + 1 个 schema 文件，无需自定义验证逻辑

Anti-Patterns

• Direct coding: Writing a utility class without checking whether an existing tool is available
• Ignoring MCP: Not checking whether an MCP server already provides the functionality
• Over-customization: Wrapping a library too heavily, causing it to lose its original advantages
• Dependency bloat: Installing a huge package for a very small feature