research

Type	Skill
Plugin	awl-general · v0.0.51
Invoke	/awl-general:research
Source	plugins/awl-general/skills/research/SKILL.md

When Claude uses it

Fetches official docs for external libraries/APIs/frameworks via Context7/Firecrawl. Use when integrating a NEW third-party dependency, migrating/upgrading a dependency to a different major version, working with an unfamiliar third-party API for the first time, or when the user explicitly asks to research or look up docs. NOT for Apple/Google first-party frameworks. NOT for refactoring internal code or writing tests. Always check .research/ for cached results before spawning.

Definition

Spawn a research subagent to fetch version-accurate documentation for external libraries/APIs.

Decision: Research or Skip?

Before spawning, check these conditions:

Worth it — spawn the agent:

• Integrating a NEW third-party dependency not yet in the project
• Migrating/upgrading a dependency to a different major version
• Working with an unfamiliar third-party API for the first time
• User explicitly asks to research or look up docs

Skip — don’t spawn:

• Fixing/debugging code that already uses the library (read the code instead)
• Apple first-party frameworks (use Axiom skills)
• Google first-party Android frameworks (use platform docs)
• Simple usage questions about libraries already in the project
• .research/ already contains recent results (<7 days old) — read the file directly

Pre-flight: Check Cache

Before spawning, always check for cached research:

1. Glob for .research/*.md in the project root
2. If a file exists for the target library, Read it
3. Check the Researched: date in the header
4. If <7 days old — use it directly, no agent needed

Spawn the Research Agent

Use the Agent tool to spawn a general-purpose subagent. Run it in the background when you have other work to do in parallel; foreground when you need results before proceeding.

Agent Prompt Template

You are a documentation research specialist. Fetch version-accurate, authoritative docs for: **{library/API name}**

Context: {why we need this — what task/feature prompted the research}
Target version: {version if known, or "latest stable"}
Language/ecosystem: {e.g., Swift, TypeScript, Python}

## Step 1: Discover Available Research Tools

Use `ToolSearch` to find what research tools are available in this session. MCP servers may or may not be installed — discover, don't assume.

Run these searches to find available tools:
- `ToolSearch("context7")` — look for Context7 documentation tools
- `ToolSearch("firecrawl")` — look for Firecrawl web scraping/search tools
- `ToolSearch("web search fetch")` — look for built-in WebSearch/WebFetch

Use whatever tools are returned. If a search returns nothing, that tool set is not available — move on to the next.

## Step 2: Research Strategy

Use the tools you discovered in Step 1. General priority order:

1. **Context7** (if available — best for popular libraries):
   - First resolve the library ID, then query docs with it
   - Provides curated, version-aware documentation

2. **Firecrawl** (if available — best for niche libraries or broader web search):
   - Search for official documentation pages first
   - Then scrape/extract relevant content from the best results
   - Also has map (discover URLs on a site), extract (structured data), crawl (multi-page), and agent (autonomous research) tools — use whichever fits

3. **WebSearch/WebFetch** (built-in fallback):
   - Search for official documentation
   - Fetch specific documentation pages
   - Priority: official docs > GitHub README > package manager pages

Run searches in parallel when possible. Limit scraping to 3-5 most relevant pages.

## Step 3: Extract These Sections

In order of priority:
- **Installation**: Package manager commands, version compatibility, peer dependencies
- **Basic Setup**: Initialization, configuration, environment variables
- **Key APIs**: Most used functions/classes with signatures
- **Code Examples**: Working examples of common use cases
- **Version Changes**: Breaking changes, deprecations, new features
- **Common Pitfalls**: Known issues, gotchas, troubleshooting
- **Best Practices**: Recommended patterns, security, performance

## Step 4: Save Output

Save findings to `.research/{library-name}.md` (kebab-case) with this format:

```markdown
# {Library Name} — Research
> Researched: {YYYY-MM-DD} | Version: {version} | Sources: {which tools were used}

## Research Context
{1-2 sentences: what task prompted this and what problem is being solved}

## Installation
...
## Key APIs
...
## Code Examples
...
## Common Pitfalls
...
## Best Practices
...

Create .research/ directory if it doesn’t exist.

If no MCP research tools (Context7/Firecrawl) were available, mention this so the user knows they can install them for better results.

Return a concise summary of findings. Reference the saved file: “Full research saved to .research/{name}.md”

### Example Invocations

**Background (parallel with other work):**

Agent( description: “Research Stripe SDK docs”, prompt: , subagent_type: “general-purpose”, run_in_background: true )

**Foreground (need results before proceeding):**

Agent( description: “Research GRDB migration guide”, prompt: , subagent_type: “general-purpose” )

## After Research Completes

- Read the agent's summary
- Reference `.research/{name}.md` in your plan or implementation
- The cached file prevents redundant research in future conversations