Agent-Skills.md

Agent Skills: Web Research Skill

Researches the web thoroughly, e.g., how to use an API, library, or reference architecture. Can also be used as fallback when the WebSearch tool fails. Use when the user asks to research a complex topic.

UncategorizedID: geggo98/dotfiles/web-research

Repository

geggo98/dotfiles
geggo98License: CC0-1.0
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/geggo98/dotfiles/tree/HEAD/modules/ai/_files/skills/web-research

Skill Files

Browse the full folder contents for web-research.

Download Skill

Loading file tree…

modules/ai/_files/skills/web-research/SKILL.md

Skill Metadata

Name
web-research
Description
"Researches the web thoroughly, e.g., how to use an API, library, or reference architecture. Can also be used as fallback when the WebSearch tool fails. Use when the user asks to research a complex topic."

Web Research Skill

Usage

Run the scripts:

zsh ${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh $ARGUMENTS
zsh ${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh $ARGUMENTS

1. Purpose

Use this skill to research the web, e.g, for APIs, libraries, or design patterns before implementation. It produces concise best-practice summaries, including alternatives, and tradeoffs. It produces a Markdown-formatted doocument containing the research results, including references as URLs.

Important: Run scripts directly (${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh, ${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh). Do not prefix with bash — the scripts require zsh and will fail under bash.

2. Usage Scenarios

Run before:

  • Using a new API or library.
  • Designing an unfamiliar feature or architecture.
  • Evaluating alternative implementations.

3. Helper Scripts

| Script | Purpose | Quick Mode | Deep Mode | | -------------------------------------------- | -------------------------------- | ---------- | --------- | | ${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh | General-purpose quick research. | Default | --deep | | ${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh | Deep research via Google Gemini. | --flash | Default |

Arguments

  • Provide the research topic as a natural-language sentence.
  • Do not include year numbers; the agent fetches up-to-date data.
  • More context ⇒ better results.

4. Examples

Always start with --flash. If the result doesn't work or if important parts are missing, use --deep to get more information.

Quick Search

${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh --flash "Which Python HTTP client libraries support caching headers, and with which backends?"

API Research

${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh "Research Python best-practices for using the Atlassian Confluence API."
${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh "Write a Python best-practice manual for using the Atlassian Confluence API."
${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh --deep "Give a second opinion on the Atlassian API usage. Alternatives and tradeoffs?"

Library Research

${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh "Best practices for using the os-lib library in Scala."
${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh "Create a manual for using os-lib in Scala with up-to-date best-practices."
${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh --deep "Second opinion on using os-lib in Scala. Alternatives and tradeoffs?"

Implementation Planning

${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh "How to parse cron expressions in Rust, using stdlib or third-party crates?"
${CLAUDE_SKILL_DIR}/scripts/gemini_research.sh "Manual for parsing cron expressions in Rust with the cron crate."
${CLAUDE_SKILL_DIR}/scripts/perplexity_open_router_research.sh --deep "Evaluate the cron crate. Alternatives and tradeoffs?"

5. Tool Modes

| Option | Description | | ------------------------ | ------------------------------------------------- | | --flash | Fast, shallow lookup for immediate results. | | --deep | Multi-step synthesis with broader exploration. | | --timeout DURATION | Global execution timeout (default: 5m). Format follows GNU coreutils (e.g. 30s, 5m, 1h). | | perplexity_open_router | Breadth-first research across multiple sources. | | gemini_research | Depth-first synthesis for comprehensive analysis. |

6. Fallbacks and Error Handling

If one agent fails, retry with the alternate tool. Ensure network access and required API keys are configured.

7. Output Format

  • Markdown-formatted structured output
  • Sections for: Overview, Best Practices, Alternatives, Tradeoffs
  • Links to primary references where available

8. Comparison Table

| Tool | Scope | Depth | Response Speed | | ---------- | ------- | ------ | -------------- | | Perplexity | Broad | Medium | Fast | | Gemini | Focused | Deep | Moderate |

9. Exit Codes

| Code | Meaning | | ---- | ------------------------- | | 0 | Success | | 1 | Invalid arguments | | 2 | Network or API failure | | 3 | Unexpected agent response |

10. Environment Variables

| Variable | Description | | -------------------- | ------------------------------ | | OPENROUTER_API_KEY | Required for Perplexity agent. | | GOOGLE_API_KEY | Required for Gemini agent. |

11. Troubleshooting

| Problem | Possible Cause | Fix | | ----------------------------- | --------------------------------- | ----------------------------- | | Error: No response from API | Connectivity issue or invalid key | Check internet or credentials | | Error: Model not found | Backend API changed | Use different script | | Output incomplete | Timeout or token limit | Retry with --deep | | Invalid topic format | Missing sentence structure | Use full sentences |