How to use the search-first agent skill: research before you code

What the search-first skill makes the agent do

The skill tells the agent to research before it writes new code. Its workflow runs in five stages: define what functionality is needed and any language or framework constraints, search npm, PyPI, MCP servers, skills, and GitHub, evaluate candidates on factors such as functionality, maintenance, community, docs, license, and dependencies, decide between adopt, extend, compose, or build, and then wait for approval before implementing.

By default the skill is read-only research. It inspects the repo, package metadata, docs, and public examples. It does not install packages, configure MCP servers, publish artifacts, open PRs, or make external write actions unless you explicitly approve that action in the current task.

• Adopt: an exact, well-maintained match with an MIT or Apache license. The agent recommends the package and asks before installing it.
• Extend: a partial match with a good foundation. The agent recommends the package plus a thin wrapper.
• Compose: several weak matches. The agent proposes 2-3 small packages and an integration plan.
• Build: nothing suitable. The agent explains why custom code is warranted and implements only within the approved scope.

Install the search-first skill

Download the ZIP from the skill's page on this site. The skill's file is SKILL.md, so the ZIP should contain that file in a folder named for the skill.

To install for all your projects, unzip it into ~/.claude/skills/. To install for one project only, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

How to trigger the skill with natural requests

You do not need a special command for everyday use. The skill is meant to activate when you are starting a new feature that likely has existing solutions, adding a dependency or integration, asking the agent to add functionality, or about to create a new utility, helper, or abstraction.

The skill's own documentation also names a slash-style entry, /search-first, and a quick mode where the agent checks the repo, npm/PyPI, MCP configuration, available skills, and GitHub before writing code. For larger work it describes a full mode that hands the research to a research-focused subagent.

• Before you add date formatting, look for an existing library and recommend one before writing code.
• Add retry and timeout handling to our HTTP calls. Search for existing clients first and wait for my approval.
• I need to validate our JSON config files against a schema. Check for existing tools before you write any validator.
• Before we build a markdown parser, research what already exists and compare the options.

Examples of what the agent returns

In the source's examples, the agent searches for a need, finds candidates, and reports an action. For a dead link checker, it found textlint-rule-no-dead-link with a score of 9/10 and recommended adopting it, asking before installation. For an HTTP client with retries, it pointed to got for Node or httpx for Python and asked before changing dependencies. For a config file validator, it recommended ajv-cli plus a project-specific schema and waited for approval before any install or write.

These examples show the pattern to expect: a short list of candidates, a recommendation, and a pause for your decision.

What the skill needs and what it touches

The listing states no special requirements, does not run scripts, and uses the network. Searching npm, PyPI, GitHub, and the web is the network activity. The skill's guidance is to request approval before package installs, credential use, paid services, network writes, or project-wide configuration changes. When a candidate needs any of those, the agent returns a recommendation and an approval checkpoint instead of applying it.

The skill ships as a single file, SKILL.md.

• Requires: nothing listed.
• Runs scripts: no.
• Uses network: yes, for research. Writes need your approval.

Tips for getting useful results

Give the agent your language or framework and any constraints, such as no third-party dependencies or a required license type. The skill's own process asks for these inputs during need analysis.

For simple, well-defined changes, skip the skill. The skill itself notes that searching adds delay when there is no benefit. Watch for dependency bloat: the skill's anti-patterns list warns against installing a massive package for one small feature and against wrapping a library so heavily that it loses its benefits.

• State your constraints up front, including whether third-party dependencies are allowed.
• Ask for a comparison table if you want to weigh options yourself.
• Reject a recommendation and ask the agent to build custom code if none of the candidates fit.