Documentation Research Skill

Research coding documentation efficiently using Perplexity AI and persist findings in a structured, AI-optimized format.

Core Principles

Check Existing Research First - Always read research/CLAUDE.md (memory index) to see if topic was researched before
Structured Persistence - Save all research to research/<topic>.md with consistent formatting
AI-Optimized Output - Use clear sections, code examples, and structured data
Documentation Focus - Prioritize official docs, GitHub repos, and authoritative sources
Memory-Based Index - research/CLAUDE.md is a Claude Code memory file that auto-loads to provide research context

research/CLAUDE.md Format

The research/CLAUDE.md file is a Claude Code memory file that follows these best practices:

Memory Best Practices (from Claude Code documentation):

✓ Be specific: "Use 2-space indentation" not "Format code properly"
✓ Use structure: Format as bullet points under descriptive headings
✓ Stay scannable: Clear sections, consistent formatting
✓ Review periodically: Update as research evolves

Index Entry Format:

### <Topic Name> (`<topic>.md`)

**Researched:** YYYY-MM-DD
**Status:** Active | Deprecated | Updated
**When to Use:** Specific concrete scenarios (be detailed)
**Summary:**
- Specific actionable point 1
- Specific actionable point 2
- Specific actionable point 3

This format ensures:

Claude can quickly scan for relevant research
Entries are specific and actionable
Research context loads automatically in every session
Index serves as a memory aid across sessions

Workflow

Step 1: Check Existing Research

ALWAYS start by checking if we've researched this topic before:

# Read the research index
cat research/CLAUDE.md

Look for the topic in the research index. If found, read the existing research file:

cat research/<topic>.md

If the research exists and is recent (< 3 months old), use it. Otherwise, proceed to Step 2.

Step 2: Identify Research Topic

Determine the specific topic to research. Create a clean topic name:

Use lowercase with hyphens
Be specific but concise
Examples: python-asyncio, react-hooks, typescript-generics, docker-best-practices

Step 3: Execute Perplexity Search

Use the optimized research script with appropriate parameters:

# Basic documentation research
.claude/skills/research-docs/scripts/perplexity-research.sh "python asyncio best practices"

# Target specific domains
.claude/skills/research-docs/scripts/perplexity-research.sh -d "docs.python.org,realpython.com" "python async await"

# Recent documentation only
.claude/skills/research-docs/scripts/perplexity-research.sh -r month "react 19 new features"

# More comprehensive results
.claude/skills/research-docs/scripts/perplexity-research.sh -n 20 "rust ownership patterns"

Script Options:

-n, --max-results NUM: Number of results (1-20, default: 15)
-r, --recency FILTER: day, week, month, year (default: year)
-d, --domains LIST: Comma-separated domain list
-f, --format FORMAT: structured (default), json, plain

Step 4: Create Structured Documentation

Save the research output to research/<topic>.md using this format:

# <Topic Name>

**Research Date:** YYYY-MM-DD
**Status:** Active | Deprecated | Updated
**Related Topics:** topic1, topic2, topic3

## Overview

Brief 2-3 sentence overview of the topic.

## Key Concepts

- **Concept 1**: Explanation
- **Concept 2**: Explanation
- **Concept 3**: Explanation

## Official Documentation

- [Primary Docs](<url>) - Description
- [API Reference](<url>) - Description

## Best Practices

### Do's

- ✓ Practice 1 with brief explanation
- ✓ Practice 2 with brief explanation

### Don'ts

- ✗ Anti-pattern 1 with brief explanation
- ✗ Anti-pattern 2 with brief explanation

## Common Patterns

### Pattern 1: <Name>

**Use Case:** When to use this pattern

**Example:**
```language
// Code example

Explanation: Why this works

Pattern 2: <Name>

Use Case: When to use this pattern

Example:

// Code example

Explanation: Why this works

Common Pitfalls

Pitfall 1: <Name>

Problem: Description of the issue

Solution:

// Correct approach

Pitfall 2: <Name>

Problem: Description of the issue

Solution:

// Correct approach

Integration Examples

Basic Setup

// Installation or basic setup

Advanced Usage

// More complex example

Version Information

Current Stable: Version number
Minimum Required: Version number
Deprecated Features: List any deprecated features

Related Resources

Resource 1 - Description
Resource 2 - Description

Research Sources

Last Updated: YYYY-MM-DD Next Review: YYYY-MM-DD (3 months from research date)


### Step 5: Update research/CLAUDE.md Index

**ALWAYS update research/CLAUDE.md** with an entry for the research.

The `research/CLAUDE.md` file is a **memory file** that Claude Code automatically loads. It serves as an index of all researched topics.

**Format Guidelines** (following Claude Code memory best practices):
- ✓ **Be specific**: Include concrete details, not vague descriptions
- ✓ **Use structure**: Format as bullet points under descriptive headings
- ✓ **Stay scannable**: Use clear sections and consistent formatting
- ✓ **Update regularly**: Keep status and dates current

Add a new entry under the "Research Index" heading:

```markdown
### <Topic Name> (`<topic>.md`)

**Researched:** YYYY-MM-DD
**Status:** Active
**When to Use:** Specific scenarios where this applies (be concrete)
**Summary:**
- Key point 1 with specific detail
- Key point 2 with specific detail
- Key point 3 with specific detail

Example entry:

### Python Asyncio (`python-asyncio.md`)

**Researched:** 2025-11-18
**Status:** Active
**When to Use:** Building concurrent I/O-bound applications, async web servers, or async database operations
**Summary:**
- Use `asyncio.create_task()` for fire-and-forget, `asyncio.gather()` for concurrent execution with results
- Always use `async with` for async context managers to ensure proper cleanup
- Avoid blocking calls in async functions - use `asyncio.to_thread()` for CPU-bound work

Step 6: Create TODO List

Use the TodoWrite tool to track research progress:

[
  {"content": "Check existing research in research/CLAUDE.md", "status": "completed", "activeForm": "Checking existing research"},
  {"content": "Execute Perplexity search for <topic>", "status": "completed", "activeForm": "Executing Perplexity search"},
  {"content": "Structure documentation in research/<topic>.md", "status": "in_progress", "activeForm": "Structuring documentation"},
  {"content": "Update research/CLAUDE.md research index", "status": "pending", "activeForm": "Updating research/CLAUDE.md research index"}
]

Documentation Categories

Framework Documentation

React, Vue, Angular, Svelte
Next.js, Nuxt, SvelteKit
Express, FastAPI, Django

Language Documentation

Python, JavaScript/TypeScript, Rust, Go
Java, Kotlin, Swift
Ruby, PHP, C#

Tool Documentation

Docker, Kubernetes
Git, GitHub Actions
Webpack, Vite, esbuild

API Documentation

REST API design
GraphQL
WebSockets

Best Practices

Code patterns
Architecture patterns
Security practices
Performance optimization

Output Quality Standards

Must Include

✓ Clear, scannable structure
✓ Code examples for key concepts
✓ Links to official documentation
✓ Best practices and anti-patterns
✓ Version information
✓ Common pitfalls and solutions

Avoid

✗ Large blocks of unformatted text
✗ Outdated information without version context
✗ Examples without explanation
✗ Missing links to sources
✗ Vague or generic advice

Example Queries That Trigger This Skill

"Research Python asyncio documentation"
"Find best practices for React hooks"
"Look up TypeScript generics documentation"
"What are the latest Docker best practices?"
"Research how to implement WebSockets in Node.js"
"Find documentation on Rust error handling"
"Look up GraphQL schema design patterns"

Maintenance

Updating Existing Research

When updating research:

Read the existing file
Add a note at the top: **Updated:** YYYY-MM-DD - Reason for update
Update the "Last Updated" date
Update the "Next Review" date
Update the research/CLAUDE.md entry with new date

Deprecation

If documentation becomes outdated:

Update status to "Deprecated"
Add deprecation notice with replacement topic
Update research/CLAUDE.md status

Troubleshooting

Perplexity API Errors

Error: API key invalid

Check PERPLEXITY_API_KEY environment variable
Ensure you have a new API key that supports Search API

Error: Rate limit exceeded

Wait before making additional requests
Consider reducing result count with -n flag

Research Quality Issues

Too many irrelevant results

Use domain filtering: -d "official-docs.com,github.com"
Make query more specific
Adjust recency filter: -r month

Missing official documentation

Explicitly include official domain in search query
Use -d flag to target specific authoritative sources

Best Practices

Always check existing research first - Avoid duplicate work
Use specific queries - "Python 3.12 asyncio patterns" vs "Python async"
Target authoritative sources - Use domain filtering for official docs
Structure consistently - Follow the documentation template
Include examples - Code examples make documentation actionable
Update research/CLAUDE.md - Keep the research index current
Set review dates - Mark when research should be refreshed
Track with TODOs - Use TodoWrite to show progress

Script Reference

The perplexity-research.sh script is located at:

.claude/skills/research-docs/scripts/perplexity-research.sh

Key Features:

Pre-configured for documentation domains
AI-optimized structured output
Flexible filtering options
Error handling and validation
Multiple output formats

Default Documentation Domains:

stackoverflow.com
github.com
docs.python.org
developer.mozilla.org
nodejs.org
reactjs.org
vuejs.org
angular.io
rust-lang.org
go.dev
kotlinlang.org
dev.to
medium.com

Override with -d flag for specific research needs.