Agent Skills: Parallel Search

Parallel Search

Web research using Parallel's Search API with extended excerpts (up to 30K chars per result).

When to Use

Use for comprehensive research on:

• Technical topics requiring multiple perspectives
• New frameworks, libraries, technologies
• Comparative analysis
• Current events
• Documentation synthesis

Prerequisites

Required:

• PARALLEL_API_KEY environment variable
• Get key: https://platform.parallel.ai/

Dependencies: Auto-installed via pnpm

Workflow

When user requests research:

1. Analyze question to identify main objective
2. Generate 3-5 targeted query angles for multi-perspective coverage
3. Execute single bash command with --objective and --queries parameters
4. API returns deduplicated results from parallel execution
5. Analyze extended excerpts and synthesize findings
6. Save report to docs/research/parallel/TIMESTAMP-topic.md

Usage

Comprehensive Research (Recommended)

cd plugins/knowledge-work/skills/parallel-search
pnpm tsx scripts/search.ts \
  --objective "Production RAG system architecture" \
  --queries \
    "RAG chunking strategies" \
    "RAG evaluation metrics" \
    "RAG deployment challenges" \
    "RAG vector database selection"

The API executes all queries in parallel and returns deduplicated results automatically.

Quick Single Query

pnpm tsx scripts/search.ts --objective "When was the UN founded?"

Processor Levels

# Default: pro (balanced quality/speed)
pnpm tsx scripts/search.ts --objective "..."

# Ultra: maximum quality for critical research
pnpm tsx scripts/search.ts --objective "..." --processor ultra

Parameters

• --objective (required): Main search objective (natural language, be specific)
• --queries: Additional query angles (max 5, 200 chars each)
• --processor: lite/base/pro/ultra (default: pro)
• --max-results: Results per search (default: 15)
• --max-chars: Excerpt length per result (default: 5000, max: 30000)

Output Format

Returns markdown with:

• Search metadata (objective, result count, execution time)
• Top domains distribution
• Ranked results:
  • Title and URL
  • Domain
  • Extended excerpts (joined with double newlines)
  • Rank

Query Generation Strategy

For broad topics: Generate queries covering different aspects

Example: "RAG systems"

• Objective: "Production RAG system architecture overview"
• Queries: "chunking strategies", "evaluation metrics", "deployment patterns", "vector databases"

For comparisons: Generate queries for each option plus general comparison

Example: "PostgreSQL vs MongoDB"

• Objective: "PostgreSQL vs MongoDB comparison"
• Queries: "PostgreSQL use cases", "MongoDB use cases", "relational vs document databases"

For current events: Use temporal and source diversity

Example: "Latest AI developments"

• Objective: "Recent AI model releases and benchmarks"
• Queries: "GPT-4 updates", "open source LLMs", "AI safety research", "industry adoption"

Research Persistence

After synthesis, save report:

1. Get timestamp: Use timestamp skill for YYYYMMDDHHMMSS format
2. Sanitize topic: Use sanitizeForFilename from formatter.ts (kebab-case, 50 char limit)
3. Save to: docs/research/parallel/TIMESTAMP-topic.md
4. Include: Findings, sources with URLs, analysis

Error Handling

Missing API key:

export PARALLEL_API_KEY="your-key-here"

Rate limit exceeded: Wait for reset time (shown in error message)

Network errors: Retry with --processor lite for faster response

Validation errors: Check constraints (max 5 queries, 200 chars each)

Constraints

• Max 5 queries per request
• Max 200 chars per query
• Max 30K chars per excerpt (not guaranteed above 30K)
• Rate limits depend on API plan tier
• Requires internet connection

Best Practices

• Use specific objectives: "Production RAG architecture" > "RAG systems"
• Leverage all 5 query slots for comprehensive coverage
• Use --max-chars up to 30000 for deep content analysis
• Adapt processor level to urgency: pro for most, ultra for critical
• Save multi-query research for future reference

Implementation

Files:

• types.ts - Interfaces and error types
• parallel-client.ts - API client with validation
• formatter.ts - Markdown output formatting
• log.ts - CLI logging
• search.ts - CLI entry point

Testing:

pnpm test