/web-research

name: web-research
description: Research web content, documentation, and best practices using the gemini-search agent for token-efficient searches with caching. Use when you need to fetch documentation, research best practices, or gather information from the web.
allowed-tools: Task, Read, Write

Web Research with Gemini Search

This skill enables efficient web research using the gemini-search agent, which provides context isolation for 30-40% token savings and includes built-in caching to avoid redundant searches.

When to Use This Skill

Invoke this skill when you need to:

• Research documentation from official sources
• Gather best practices and examples
• Find current information about tools, libraries, or frameworks
• Research GitHub workflows, CI/CD patterns
• Look up API documentation
• Find examples of code patterns
• Research security best practices
• Gather information about error messages or issues

How It Works

This skill uses the **gemini-search agent** (available in this plugin) which:

• Performs web searches in an isolated context (saves 30-40% tokens)
• Caches results for 1 hour (configurable via `GEMINI_SEARCH_CACHE_TTL`)
• Tracks analytics (cache hits, query patterns, token savings)
• Provides structured, relevant results

Research Patterns

1. Documentation Research

When you need to research official documentation:

Use the Task tool with subagent_type="gemini-search:gemini-search" to search for:
- "Claude Code skills documentation"
- "GitHub Actions workflow syntax"
- "ShellCheck best practices 2025"
- "Semantic versioning specification"

**Example prompt for agent:**

Search the web for comprehensive documentation about [topic]. Focus on:
1. Official documentation sources
2. Best practices and recommendations
3. Current (2025) standards and patterns
4. Practical examples and use cases

Please provide a structured summary with key points and source URLs.

2. Best Practices Research

When researching best practices:

Use the Task tool with subagent_type="gemini-search:gemini-search" to search for:
- "bash script best practices 2025"
- "GitHub Actions CI/CD best practices"
- "Claude Code plugin development patterns"
- "Release management workflow"

**Example prompt for agent:**

Research current best practices for [topic]. Include:
1. Industry-standard approaches
2. Common patterns and conventions
3. Security considerations
4. Performance optimization tips
5. Tools and frameworks commonly used

Provide actionable recommendations with examples.

3. Troubleshooting and Error Research

When investigating errors or issues:

Use the Task tool with subagent_type="gemini-search:gemini-search" to search for:
- "ShellCheck SC2086 fix examples"
- "GitHub Actions workflow not triggering"
- "BATS test framework setup"
- "git tag push not triggering workflow"

**Example prompt for agent:**

Research solutions for [specific error or issue]. Find:
1. Common causes of this issue
2. Recommended solutions and workarounds
3. Related documentation
4. Working examples

Focus on verified solutions from official docs and reputable sources.

4. Tool and Framework Research

When learning about tools or frameworks:

Use the Task tool with subagent_type="gemini-search:gemini-search" to search for:
- "Gemini CLI features and capabilities"
- "jq JSON processing examples"
- "GitHub CLI pr commands"
- "Trivy security scanner configuration"

**Example prompt for agent:**

Research [tool/framework name]. Provide:
1. Overview and key features
2. Installation methods
3. Common use cases and examples
4. Configuration options
5. Integration with other tools

Include practical examples and current version info.

5. Comparative Research

When comparing approaches or tools:

Use the Task tool with subagent_type="gemini-search:gemini-search" to search for:
- "GitHub Actions vs GitLab CI comparison"
- "bash vs python for shell scripts"
- "different JSON validation tools"
- "release automation strategies"

**Example prompt for agent:**

Compare [option A] vs [option B] for [use case]. Include:
1. Key differences and trade-offs
2. Performance considerations
3. Use case recommendations
4. Community adoption and support
5. Integration capabilities

Provide objective comparison with use case recommendations.

Usage Instructions

Basic Research Pattern

**Step 1:** Invoke the gemini-search agent via Task tool

Use the Task tool with:
- subagent_type: "gemini-search:gemini-search"
- description: "Research [topic]"
- prompt: "[Detailed research request as shown in patterns above]"

**Step 2:** Process the results

The agent will return structured results including:

• Summary of findings
• Key points and recommendations
• Source URLs for reference
• Relevant examples or code snippets

**Step 3:** Apply the research

Use the research findings to:

• Answer user questions with current information
• Implement features based on best practices
• Troubleshoot issues with verified solutions
• Make informed technical decisions

Advanced Usage

**Multi-query research:**

When you need to research multiple related topics, invoke the agent multiple times with different queries:

1. Search for general overview/documentation
2. Search for specific best practices
3. Search for examples and use cases
4. Search for troubleshooting and common issues

**Targeted documentation search:**

For official documentation, include source constraints in your query:

"Claude Code skills documentation site:docs.claude.com"
"GitHub Actions workflow syntax site:docs.github.com"
"ShellCheck documentation site:shellcheck.net"

Token Efficiency

Why This Saves Tokens

**Context isolation:**

• Agent runs in isolated context
• Only returns final results to main conversation
• Doesn't include intermediate search results in main context
• Saves 30-40% tokens on research-heavy tasks

**Caching:**

• Result