Search Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Search Skill provides AI agents with the capability to search the web, library documentation, and GitHub code repositories. Unlike script-based skills, it is an MCP-based skill, meaning it relies on external MCP (Multi-tool Control Protocol) servers to perform its functions. It is designed for tasks like looking up documentation, finding code examples, troubleshooting errors, and researching best practices.
This skill is distinct from the Research Skill, which is used for more in-depth academic research and evidence synthesis. The Search Skill is intended for quicker, more direct information retrieval during development tasks.
Sources: skills/search/SKILL.md:1-4, skills/README.md:14, 48-50, skills/research/SKILL.md:10
Architecture
The Search Skill's architecture is based on the agent's ability to invoke pre-configured MCP tools. The agent discovers the skill's capabilities by reading skills/search/SKILL.md, which guides it on when and how to use the available search tools. The actual search operations are performed by dedicated MCP servers defined in mcp.json.
Sources: skills/README.md:48-50, AGENTS.md:55-74
This diagram illustrates the interaction between the AI Agent, the Search Skill definition, and the backend MCP servers.
Sources: skills/search/SKILL.md, mcp.json, AGENTS.md:55-74
Core Components
The Search Skill is composed of a skill definition file and several MCP server configurations.
Skill Definition (SKILL.md)
This file provides the primary instructions for the AI agent. It includes:
- A description of the skill's purpose.
- Trigger keywords such as "search for", "look up", "find docs", and "how to".
- A workflow that guides the agent to first consult the
query-guide.mdbefore formulating and executing a search.
Sources: skills/search/SKILL.md:1-12
MCP Tools
The skill leverages multiple MCP servers for different search domains. These are configured in mcp.json and automatically set up by the install.sh script for OpenCode agents.
| MCP Server | Purpose | Configuration Details |
|---|---|---|
tavily-remote-mcp | General web search for tutorials, best practices, and troubleshooting. | Requires a TAVILY_API_KEY. Used by both Search and Research skills. |
context7 | Search library and framework documentation for API references and installation instructions. | API key is optional. |
grep | Search across millions of public GitHub repositories for real-world code examples and patterns. | No API key required. |
zai-zread | Semantic search over GitHub repository issues, PRs, and documentation. | Requires a Z_AI_API_KEY. |
Sources: mcp.json, AGENTS.md:57-74, INSTALL.md:204-245, skills/README.md:73-81
Below is a snippet from mcp.json showing the configuration for the Tavily and Grep MCPs.
{
"mcp_servers": [
{
"name": "tavily-remote-mcp",
"url": "http://localhost:3001",
"description": "Tavily web search and research API",
"tools": ["tavily_search"],
"api_key_env": "TAVILY_API_KEY"
},
{
"name": "grep",
"url": "http://localhost:3006",
"description": "Search across a million public GitHub repositories",
"tools": ["search"]
}
]
}
Sources: mcp.json:2-16
Workflow
The typical workflow involves the agent identifying a need for information, formulating a query according to the query guide, selecting the appropriate MCP tool, and executing the search.
This sequence diagram shows the agent's process for using the Search Skill.
Query Formulation Guide
A critical part of the skill is the references/query-guide.md, which provides best practices for constructing effective search queries. The agent is instructed to always read this guide before performing a search.
Key recommendations from the guide include:
| Strategy | Description | Example |
|---|---|---|
| Be Specific | Use exact function names, error messages, or library versions. | Instead of "react error", use "react 18" "cannot read properties of undefined". |
| Use Keywords | Add keywords like tutorial, example, best practices, or docs. | fastapi dependency injection example |
| Filter by Source | Use site: to limit searches to specific domains. | site:developer.mozilla.org css grid |
| Iterate | Start with a broad query and refine it based on initial results. | 1. python async -> 2. python asyncio tutorial -> 3. python asyncio gather vs wait |
| Select the Right Tool | Choose the MCP tool that best matches the information need (e.g., Context7 for docs, Tavily for tutorials). | For API syntax, use Context7. For a conceptual overview, use Tavily. |
Sources: skills/search/references/query-guide.md:3-44, skills/search/SKILL.md:15-16
Integration with Other Skills
The Search Skill's components, particularly the Tavily MCP, are also utilized by other skills.
- Research Skill: The
researchskill uses Tavily in parallel with academic search tools (like OpenAlex) to gather non-academic sources such as blog posts, documentation, and case studies. This provides a comprehensive view by combining formal research with real-world implementations.
Sources: skills/research/SKILL.md:49-53, skills/research/references/guides/guide-workflow.md:73-80
Summary
The Search Skill is a foundational, MCP-driven capability that enables AI agents to retrieve information from the web, documentation, and code repositories. It operates not through a single script but by leveraging a set of specialized external search tools. Its effectiveness is enhanced by a structured workflow that emphasizes proper query formulation, ensuring the agent can efficiently find the precise information needed to complete its development tasks.
Sources: skills/search/SKILL.md, skills/README.md:48-50