feat(skills): add search-first skill#262
Merged
affaan-m merged 1 commit intoaffaan-m:mainfrom Feb 21, 2026
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughA new Markdown documentation file is added at Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/search-first/SKILL.md`:
- Around line 1-3: The frontmatter "description" value in SKILL.md must begin
with the exact phrase "Use when…"; update the existing description field (the
YAML key "description") so it starts with "Use when…" followed by the existing
content (e.g., "Use when researching before coding: Research-before-coding
workflow. Search for existing tools, libraries, and patterns before writing
custom code. Invokes the researcher agent.") ensuring you preserve the original
intent and punctuation.
- Around line 9-15: Rename the section heading "## Trigger" to "## When to Use"
and rename the existing "## Workflow" (or any "## How to Use") heading to "##
How It Works" in SKILL.md so the file contains the required top-level sections:
"When to Use", "How It Works", and "Examples"; ensure content under each heading
remains unchanged except for the heading text so the guidance maps correctly to
the new section names.
- Around line 1-158: The file name SKILL.md violates the lowercase-with-hyphens
rule; rename it to a compliant name (e.g., search-first.md or skill.md) and
update any internal references to SKILL.md (look for occurrences of "SKILL.md"
or the "/search-first" skill title in documentation/config) so links and imports
still resolve; ensure repository metadata or any index that listed SKILL.md is
updated accordingly.
- Around line 36-54: The DECIDE workflow diagram is missing the "Compose"
outcome, causing inconsistency with the Decision Matrix; update the DECIDE box
in SKILL.md so it lists all four outcomes — "Adopt", "Extend / Wrap", "Compose"
(or "Compose / Combine"), and "Build Custom" — matching the Decision Matrix
wording, and ensure spacing/connector lines in the ASCII diagram remain aligned
and the label "DECIDE" (the DECIDE box) and the Decision Matrix table use
identical terminology.
Comment on lines
+1
to
+3
| --- | ||
| description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent. | ||
| --- |
Contributor
There was a problem hiding this comment.
description must start with "Use when…" per the PR's own test plan.
The current description (Research-before-coding workflow. Search for...) doesn't satisfy the unchecked test-plan criterion.
🛠️ Proposed fix
-description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.
+description: Use when starting new functionality to enforce a research-before-coding workflow — searches for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.📝 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
| --- | |
| description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent. | |
| --- | |
| --- | |
| description: Use when starting new functionality to enforce a research-before-coding workflow — searches for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent. | |
| --- |
🤖 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 1 - 3, The frontmatter
"description" value in SKILL.md must begin with the exact phrase "Use when…";
update the existing description field (the YAML key "description") so it starts
with "Use when…" followed by the existing content (e.g., "Use when researching
before coding: Research-before-coding workflow. Search for existing tools,
libraries, and patterns before writing custom code. Invokes the researcher
agent.") ensuring you preserve the original intent and punctuation.
Comment on lines
+1
to
+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 |
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Rename file to comply with lowercase-with-hyphens naming convention.
The filename SKILL.md is all-uppercase. The guideline requires lowercase with hyphens (e.g., skill.md or search-first.md).
♻️ Suggested rename
-skills/search-first/SKILL.md
+skills/search-first/skill.mdAs per coding guidelines: "Use lowercase with hyphens for file naming (e.g., python-reviewer.md, tdd-workflow.md)".
🤖 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 1 - 158, The file name SKILL.md
violates the lowercase-with-hyphens rule; rename it to a compliant name (e.g.,
search-first.md or skill.md) and update any internal references to SKILL.md
(look for occurrences of "SKILL.md" or the "/search-first" skill title in
documentation/config) so links and imports still resolve; ensure repository
metadata or any index that listed SKILL.md is updated accordingly.
Comment on lines
+9
to
+15
| ## 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 |
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Rename "Trigger" to "When to Use" and add/rename a "How It Works" section.
The skill guidelines require clear sections named When to Use, How It Works, and Examples:
- Line 9:
## Trigger→ should be## When to Use - Neither
## Workflownor## How to Usematches the required## How It Worksheading; the## Workflowsection is the natural fit.
♻️ Proposed rename
-## Trigger
+## When to Use-## Workflow
+## How It WorksBased on learnings: "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
🤖 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 section heading
"## Trigger" to "## When to Use" and rename the existing "## Workflow" (or any
"## How to Use") heading to "## How It Works" in SKILL.md so the file contains
the required top-level sections: "When to Use", "How It Works", and "Examples";
ensure content under each heading remains unchanged except for the heading text
so the guidance maps correctly to the new section names.
Comment on lines
+36
to
+54
| │ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ | ||
| │ │ 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 | |
Contributor
There was a problem hiding this comment.
"Compose" decision is missing from the workflow diagram's DECIDE step.
The Decision Matrix (lines 49–54) defines four outcomes — Adopt, Extend, Compose, Build — but the DECIDE box in the workflow diagram (lines 36–39) only shows three: Adopt, Extend/Wrap, Build Custom. The "Compose" option is silently dropped, making the diagram inconsistent with the matrix.
🛠️ Proposed fix
-│ 4. DECIDE │
-│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
-│ │ Adopt │ │ Extend │ │ Build │ │
-│ │ as-is │ │ /Wrap │ │ Custom │ │
-│ └─────────┘ └──────────┘ └─────────┘ │
+│ 4. DECIDE │
+│ ┌────────┐ ┌────────┐ ┌─────────┐ ┌──────┐ │
+│ │ Adopt │ │ Extend │ │ Compose │ │Build │ │
+│ │ as-is │ │ /Wrap │ │ 2-3 pkg │ │Custom│ │
+│ └────────┘ └────────┘ └─────────┘ └──────┘ │📝 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
| │ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ | |
| │ │ 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 | | |
| │ 4. DECIDE │ | |
| │ ┌────────┐ ┌────────┐ ┌─────────┐ ┌──────┐ │ | |
| │ │ Adopt │ │ Extend │ │ Compose │ │Build │ │ | |
| │ │ as-is │ │ /Wrap │ │ 2-3 pkg │ │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 | |
🤖 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 workflow
diagram is missing the "Compose" outcome, causing inconsistency with the
Decision Matrix; update the DECIDE box in SKILL.md so it lists all four outcomes
— "Adopt", "Extend / Wrap", "Compose" (or "Compose / Combine"), and "Build
Custom" — matching the Decision Matrix wording, and ensure spacing/connector
lines in the ASCII diagram remain aligned and the label "DECIDE" (the DECIDE
box) and the Decision Matrix table use identical terminology.
affaan-m
approved these changes
Feb 21, 2026
Owner
affaan-m
left a comment
affaan-m
left a comment
There was a problem hiding this comment.
Automated review: doc-only changes look good. Approving.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
search-firstskill that enforces a research-before-coding workflow: search for existing tools, libraries, and patterns before writing custom code.Test plan
descriptionstarts with "Use when..."🤖 Generated with Claude Code