Skip to content

feat(skills): add search-first skill #258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shimo4228 wants to merge 1 commit into from
Closed

feat(skills): add search-first skill #258

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions skills/search-first/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Comment on lines +9 to +15
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

## Trigger should be renamed ## When to Use

The coding guideline (and repo learning) requires skills to have explicit ## When to Use, ## How It Works, and ## Examples sections. ## Trigger maps to "When to Use" but uses a non-standard heading. Additionally, neither ## Workflow nor ## How to Use is named ## How It Works, so that required section is absent entirely.

✏️ Proposed section renames 
-## Trigger
+## When to Use
-## Workflow
+## How It Works

Then the separate ## How to Use block (lines 56–80) can be retained as a sub-section or merged under ## How It Works.

As per coding guidelines: "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 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
## When to Use
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
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/search-first/SKILL.md` around lines 9 - 15, Rename the non-standard
"## Trigger" heading to "## When to Use" and ensure there is an explicit "## How
It Works" section (you can move or merge the existing "## How to Use" content
under this new "## How It Works" heading); update any subheading names
accordingly so the file contains the three required top-level sections exactly:
"## When to Use", "## How It Works", and "## Examples" (leave the examples block
as-is or create it if missing) and keep existing content under the new headings
to preserve intent.


## 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 |
Comment on lines +36 to +54
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Compose is missing from the DECIDE step in the workflow diagram but present in the Decision Matrix

The ASCII art at step 4 (lines 36–39) shows only three paths — Adopt, Extend/Wrap, and Build Custom — while the Decision Matrix directly below (line 53) introduces a fourth distinct action: Compose. A reader following the diagram alone would never see the compose option.

✏️ Proposed fix — add Compose to the DECIDE box 
-│  4. DECIDE                                  │
-│     ┌─────────┐  ┌──────────┐  ┌─────────┐  │
-│     │  Adopt  │  │  Extend  │  │  Build   │  │
-│     │ as-is   │  │  /Wrap   │  │  Custom  │  │
-│     └─────────┘  └──────────┘  └─────────┘  │
+│  4. DECIDE                                        │
+│  ┌────────┐ ┌────────┐ ┌─────────┐ ┌────────┐    │
+│  │ Adopt  │ │ Extend │ │ Compose │ │ Build  │    │
+│  │ as-is  │ │ /Wrap  │ │ 2-3 pkg │ │ Custom │    │
+│  └────────┘ └────────┘ └─────────┘ └────────┘    │
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/search-first/SKILL.md` around lines 36 - 54, The DECIDE diagram (the
ASCII art block showing "Adopt", "Extend / Wrap", and "Build Custom") is missing
the "Compose" option that appears in the Decision Matrix; update the ASCII-art
DECIDE box to include a fourth box labeled "Compose" (matching wording used in
the Decision Matrix) so the visual workflow and the table are consistent—edit
the ASCII diagram near the existing "Adopt", "Extend / Wrap", and "Build Custom"
boxes to add a "Compose" box and adjust spacing/alignment accordingly.


## 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
```
Comment on lines +126 to +133
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Example 1's score for textlint-rule-no-dead-link contradicts the skill's own evaluation criteria

The skill's evaluate step lists maintenance as a scoring dimension (line 33), but the example rates textlint-rule-no-dead-link at 9/10 despite the package being flagged as inactive by Snyk — Snyk's maintenance analysis determined its status is Inactive, noting it hasn't seen any new versions released to npm in the past 12 months. Using a poorly-maintained package as the flagship "ADOPT" example in a skill intended to teach quality evaluation undermines the lesson. Consider swapping for a well-maintained alternative (e.g., markdown-link-check) or adjusting the score to reflect maintenance accurately.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/search-first/SKILL.md` around lines 126 - 133, Example 1 contradicts
the skill's evaluation criteria: the maintenance dimension (mentioned in the
evaluate step) rates textlint-rule-no-dead-link at 9/10 even though Snyk flags
it as Inactive; update the Example 1 block by either replacing
textlint-rule-no-dead-link with a well-maintained alternative like
markdown-link-check (and update the Search/Found/Action/Result lines to reflect
that adoption) or adjust the score and add a short maintenance rationale for
textlint-rule-no-dead-link (e.g., lower the maintenance score and note Snyk's
inactive status) so the ADOPT recommendation and scoring are consistent with the
evaluate criteria.


### 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
Loading