researching-perplexity

name: researching-perplexity description: Use when researching with AI-powered search - Perplexity MCP for fast synthesis with citations, alternative to traditional WebSearch+WebFetch. Requires API key setup. allowed-tools: Bash, Read, Write, TodoWrite

Researching with Perplexity AI

AI-powered web research using Perplexity MCP wrappers for faster synthesis with built-in citations.

When to Use

Use this skill when:

• AI-powered search with built-in citations needed
• Quick synthesis more important than exhaustive search
• Deep research with academic-style references required
• Complex multi-source research benefits from AI aggregation
• Logical reasoning or analysis needed alongside research

DO NOT use when:

• API key not configured → use researching-web
• npm/library docs available → use researching-context7
• Academic papers needed → use researching-arxiv
• Codebase pattern discovery → use researching-codebase
• GitHub-specific resources → use researching-github

You MUST use TodoWrite before starting to track all workflow steps (API validation, query formulation, tool selection, execution, formatting).

Quick Reference

Workflow Phases

Phase 1: API Key Validation

MANDATORY: Verify API key before attempting research.

Check Credentials

Perplexity API key is retrieved from 1Password vault "Claude Code Tools", item "Perplexity API Key".

The first API call will prompt for biometric authentication. Credentials are cached for 15 minutes.

Setup instructions:

1. Get API key: https://www.perplexity.ai/account/api/group
2. Store in 1Password:
   - Vault: "Claude Code Tools"
   - Item: "Perplexity API Key"
   - Field: password (set to your pplx-... key)
3. See .claude/tools/perplexity/README.md for details

Legacy (deprecated): credentials.json is no longer supported. Migrate to 1Password.

Phase 2: Query Formulation

Extract research topic from user's request and formulate query.

Query patterns:

See: references/query-templates.md for complete patterns.

Phase 3: Tool Selection

Map research intent to Perplexity command:

See: references/tool-selection.md for decision matrix.

Default recommendation: Use research for most cases (citations + depth).

Phase 4: Execution

Execute via Perplexity CLI with directory-independent path:

ROOT="$(git rev-parse --show-superproject-working-tree --show-toplevel | head -1)"
$ROOT/.claude/bin/perplexity.ts {command} "{query}"

Commands:

# Deep research with citations (most common)
$ROOT/.claude/bin/perplexity.ts research "your topic here"

# Quick search
$ROOT/.claude/bin/perplexity.ts search "your query here"

# Ask follow-up question
$ROOT/.claude/bin/perplexity.ts ask "your question here"

# Reasoning and analysis
$ROOT/.claude/bin/perplexity.ts reason "your problem here"

Capture output: Store in variable for formatting.

Timeouts:

• search, ask: 30 seconds
• research, reason: 60 seconds (complex queries take time)

Phase 5: Output Formatting

Structure output to match research orchestration synthesis requirements.

See: references/output-format.md for complete template.

Required sections:

1. Tool Used - Which Perplexity command (search/ask/research/reason)
2. Query - Exact query sent to Perplexity
3. Key Findings - Structured summary with numbered citations [1], [2], [3]
4. Sources - Extracted URLs from Perplexity response
5. AI Synthesis Note - Clarify content is AI-aggregated (not raw search results)
6. Date - Research timestamp for staleness tracking

Output format:

## Perplexity Research: {topic}

**Tool**: {search|ask|research|reason}
**Query**: "{query string}"
**Date**: {YYYY-MM-DD}

### Key Findings

1. **{Finding 1 Title}**
   - {Details with specifics}
   - {Additional context}

2. **{Finding 2 Title}**
   - {Details with specifics}

3. **{Finding 3 Title}**
   - {Details with specifics}

### Sources

[1] https://example.com/source1
[2] https://example.com/source2
[3] https://example.com/source3

### Research Notes

- **Method**: AI-powered synthesis via Perplexity {command}
- **Content**: Aggregated from multiple sources and synthesized by AI
- **Verification**: Cross-check critical facts with primary sources
- **Staleness**: Research as of {date} - may become outdated

Output location depends on invocation mode:

Mode 1: Standalone (invoked directly)

ROOT="$(git rev-parse --show-superproject-working-tree --show-toplevel | head -1)"
TIMESTAMP=$(date +"%Y-%m-%d-%H%M%S")
TOPIC="{semantic-topic-name}"
mkdir -p "$ROOT/.claude/.output/research/${TIMESTAMP}-${TOPIC}-perplexity"
# Write synthesis to: $ROOT/.claude/.output/research/${TIMESTAMP}-${TOPIC}-perplexity/SYNTHESIS.md

Mode 2: Orchestrated (invoked by orchestrating-research)

When parent skill provides OUTPUT_DIR:

• Write synthesis to: ${OUTPUT_DIR}/perplexity.md
• Do NOT create directory (parent already created it)

Detection logic: If parent skill passed an output directory path, use Mode 2. Otherwise use Mode 1.

Key Principles

1. API Key Required - Always validate before execution
2. Smart Tool Selection - Match intent to command (research > search > ask > reason)
3. Citation Tracking - Extract URLs from Perplexity response
4. AI Synthesis Note - Always clarify content is AI-aggregated
5. Date Everything - Research timestamps enable staleness tracking
6. Structured Output - Compatible with research orchestration synthesis

Common Scenarios

API Key Not Configured

Show setup instructions (see Phase 1 failure message) and suggest fallback:

Consider using 'researching-web' skill as alternative (no API key required).

Perplexity Returns Error

Common errors:

• "Authentication failed" - API key invalid or expired
• "Rate limit exceeded" - Too many requests, wait and retry
• "Request timed out" - Complex query, try simpler version or split into parts

Empty or Poor Results

If Perplexity returns sparse results:

1. Reformulate query (try different keywords)
2. Switch to different command (e.g., search instead of research)
3. Fall back to researching-web for traditional search

Combining with Traditional Web Research

User may select both "Perplexity" and "Web" from research orchestration:

• Perplexity: Fast AI synthesis with citations
• Web: Exhaustive manual search+fetch with validation

Router synthesizes both outputs. Each provides different perspective.

Comparison to Sibling Skills

Related Skills