@hasna/skills 0.0.2

package/skills/skill-deep-research/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "declaration": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*", "bin/**/*"]
+}

package/skills/skill-deepresearch/.env.example

@@ -0,0 +1,9 @@
+# Required for search
+EXA_API_KEY=your_exa_api_key
+
+# Required for synthesis (at least one)
+ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key
+
+# Optional for deep scraping
+FIRECRAWL_API_KEY=your_firecrawl_api_key

package/skills/skill-deepresearch/CLAUDE.md

@@ -0,0 +1,44 @@
+# skill-deepresearch
+
+Agentic deep research skill using Exa.ai and LLM synthesis.
+
+## Quick Reference
+
+```bash
+# Run the skill
+bun run src/index.ts "<topic>" [options]
+
+# Options
+--depth <quick|normal|deep>   # Research depth (default: normal)
+--model <claude|openai>       # LLM provider (default: claude)
+--output <path>               # Custom output path
+--json                        # Also output sources JSON
+--no-firecrawl               # Skip deep scraping
+```
+
+## Project Structure
+
+- `src/index.ts` - CLI entry point
+- `src/research.ts` - Main research orchestration
+- `src/agents/` - LLM agents for query generation and synthesis
+- `src/services/` - API clients (Exa, Anthropic, OpenAI, Firecrawl)
+- `src/utils/` - Logger and file helpers
+- `src/types.ts` - TypeScript types
+
+## API Keys
+
+Required in `~/.secrets`:
+- `EXA_API_KEY` - For search
+- `ANTHROPIC_API_KEY` - For Claude synthesis
+- `OPENAI_API_KEY` - For OpenAI synthesis (alternative)
+- `FIRECRAWL_API_KEY` - Optional, for deep scraping
+
+## Output Location
+
+`~/.skills/skill-deepresearch/exports/`
+
+## Depth Levels
+
+- **quick**: 6 queries, 1 iteration
+- **normal**: 15 queries, 1 iteration
+- **deep**: 30 queries, 2 iterations (with follow-up based on gaps)

package/skills/skill-deepresearch/README.md

@@ -0,0 +1,170 @@
+# skill-deepresearch
+
+Agentic deep research skill that uses Exa.ai for parallel semantic search and Claude/OpenAI for report synthesis. Inspired by how Perplexity, OpenAI, and Anthropic implement deep research.
+
+## How It Works
+
+1. **Query Generation** - LLM analyzes your topic and generates diverse search queries
+2. **Parallel Search** - Executes searches in parallel via Exa.ai (5 concurrent limit)
+3. **Content Retrieval** - Gets clean content from search results
+4. **Optional Deep Scrape** - Uses Firecrawl for JS-rendered pages
+5. **Synthesis** - LLM compiles findings into a structured report with citations
+
+## Installation
+
+```bash
+# Install from npm
+bun add @hasnaxyz/skill-deepresearch
+
+# Or clone and install
+cd ~/Workspace/dev/hasnaxyz/skill/skilldev/skill-deepresearch
+bun install
+```
+
+### Claude Code Skill
+
+Link to Claude Code skills directory:
+```bash
+ln -s ~/Workspace/dev/hasnaxyz/skill/skilldev/skill-deepresearch ~/.claude/skills/deepresearch
+```
+
+Then invoke with `/deepresearch "your topic"` in Claude Code.
+
+### OpenAI Codex Skill
+
+Link to Codex skills directory:
+```bash
+ln -s ~/Workspace/dev/hasnaxyz/skill/skilldev/skill-deepresearch ~/.codex/skills/deepresearch
+```
+
+Then invoke with `/deepresearch "your topic"` in Codex.
+
+## Configuration
+
+Set API keys in `~/.secrets`:
+
+```bash
+# Required
+export EXA_API_KEY="your_exa_key"
+
+# At least one required for synthesis
+export ANTHROPIC_API_KEY="your_anthropic_key"
+export OPENAI_API_KEY="your_openai_key"
+
+# Optional
+export FIRECRAWL_API_KEY="your_firecrawl_key"
+```
+
+## Usage
+
+```bash
+# Basic usage
+bun run src/index.ts "What are the best practices for building RAG systems?"
+
+# Quick research (6 queries)
+bun run src/index.ts "What is vector search?" --depth quick
+
+# Deep research (30 queries, 2 iterations)
+bun run src/index.ts "Compare React Server Components vs traditional SSR" --depth deep
+
+# Use OpenAI instead of Claude
+bun run src/index.ts "State of AI in 2024" --model openai
+
+# Custom output location
+bun run src/index.ts "Kubernetes best practices" --output ./k8s-research.md
+
+# Include raw sources JSON
+bun run src/index.ts "GraphQL vs REST APIs" --json
+
+# Skip Firecrawl deep scraping
+bun run src/index.ts "Machine learning ops" --no-firecrawl
+```
+
+## Depth Levels
+
+| Level | Queries | Iterations | Use Case |
+|-------|---------|------------|----------|
+| quick | 6 | 1 | Fast overview |
+| normal | 15 | 1 | Standard research |
+| deep | 30 | 2 | Thorough analysis with follow-up queries |
+
+## Output
+
+Reports are saved to `~/.skills/skill-deepresearch/exports/`:
+
+```
+~/.skills/skill-deepresearch/
+├── exports/
+│   ├── report-what-is-rag-2024-01-15T10-30-00.md
+│   └── sources-what-is-rag-2024-01-15T10-30-00.json
+└── logs/
+```
+
+### Report Format
+
+```markdown
+# Research Report: [Topic]
+
+**Generated:** 2024-01-15T10:30:00Z
+**Depth:** normal
+**Queries:** 15
+**Sources:** 42
+
+---
+
+## Executive Summary
+[2-3 paragraph overview]
+
+## Key Findings
+- Finding 1 [1]
+- Finding 2 [2]
+...
+
+## Detailed Analysis
+### Subtopic 1
+...
+
+## Conclusions
+...
+
+---
+
+## Sources
+1. [Title](url) - Published Date
+2. [Title](url)
+...
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # CLI entry point
+├── research.ts           # Main orchestration
+├── types.ts              # TypeScript types
+├── agents/
+│   ├── query-generator.ts    # LLM query generation
+│   └── synthesizer.ts        # LLM report synthesis
+├── services/
+│   ├── exa.ts                # Exa.ai search
+│   ├── anthropic.ts          # Claude API
+│   ├── openai.ts             # OpenAI API
+│   └── firecrawl.ts          # Firecrawl scraping
+└── utils/
+    ├── logger.ts             # Console output
+    └── file.ts               # File operations
+```
+
+## Claude Code Integration
+
+This skill can be invoked from Claude Code using:
+
+```
+/deepresearch "your research topic"
+```
+
+See `SKILL.md` for skill metadata.
+
+## License
+
+MIT

package/skills/skill-deepresearch/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: skill-deepresearch
+description: Perform deep research on any topic using Exa.ai for parallel semantic search and Claude/OpenAI for synthesis. Use when you need comprehensive research reports with citations, analysis of topics from multiple angles, or thorough investigation of technical subjects.
+---
+
+# Deep Research
+
+Agentic deep research skill using Exa.ai for search and Claude/OpenAI for synthesis.
+
+## Invocation
+
+```
+/deepresearch <topic>
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--depth <level>` | Research depth: quick (6 queries), normal (15), deep (30) | normal |
+| `--model <provider>` | LLM: claude or openai | claude |
+| `--output <path>` | Custom output path | ~/.skills/skill-deepresearch/exports/ |
+| `--json` | Also save sources as JSON | false |
+| `--no-firecrawl` | Skip deep scraping | false |
+
+## Examples
+
+```bash
+# Quick overview of a topic
+/deepresearch "What is RAG?" --depth quick
+
+# Standard research with Claude
+/deepresearch "Best practices for building production ML systems"
+
+# Deep research with OpenAI, custom output
+/deepresearch "Compare Next.js vs Remix" --depth deep --model openai --output ./research.md
+```
+
+## Requirements
+
+- `EXA_API_KEY` - Required for search
+- `ANTHROPIC_API_KEY` - Required for Claude synthesis
+- `OPENAI_API_KEY` - Required for OpenAI synthesis
+- `FIRECRAWL_API_KEY` - Optional for deep scraping
+
+## Output
+
+Reports are saved to `~/.skills/skill-deepresearch/exports/` with format:
+- `report-{topic-slug}-{timestamp}.md` - Full research report
+- `sources-{topic-slug}-{timestamp}.json` - Raw sources (if --json)

package/skills/skill-deepresearch/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hasnaxyz/skill-deepresearch",
+  "version": "0.1.3",
+  "description": "Agentic deep research skill using Exa.ai for search and Claude/OpenAI for synthesis",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "skill-deepresearch": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/skill-deepresearch.git"
+  },
+  "keywords": [
+    "research",
+    "ai",
+    "exa",
+    "claude",
+    "openai",
+    "rag",
+    "deep-research"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "exa-js": "^1.0.12",
+    "openai": "^4.0.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/skill-deepresearch/src/agents/query-generator.ts

@@ -0,0 +1,91 @@
+import type { ModelProvider, QueryGenerationResult } from "../types";
+import * as anthropic from "../services/anthropic";
+import * as openai from "../services/openai";
+
+const SYSTEM_PROMPT = `You are a research query generation expert. Your task is to generate diverse, effective search queries that will help gather comprehensive information on a given topic.
+
+Generate queries that cover different aspects:
+- Definitions and fundamentals
+- How it works / technical implementation
+- Best practices and recommendations
+- Common problems, challenges, and solutions
+- Comparisons with alternatives
+- Recent developments and trends
+- Expert opinions and case studies
+- Real-world applications and examples
+
+Make each query specific and searchable. Avoid overly generic queries.`;
+
+function buildUserPrompt(topic: string, queryCount: number): string {
+  return `Research Topic: "${topic}"
+
+Generate exactly ${queryCount} diverse search queries that will help gather comprehensive information on this topic. The queries should cover different angles and aspects to ensure thorough research.
+
+Respond with a JSON object in this exact format:
+{
+  "queries": ["query1", "query2", ...],
+  "reasoning": "Brief explanation of the query strategy"
+}`;
+}
+
+export async function generateQueries(
+  topic: string,
+  queryCount: number,
+  model: ModelProvider
+): Promise<QueryGenerationResult> {
+  const userPrompt = buildUserPrompt(topic, queryCount);
+
+  if (model === "claude") {
+    return anthropic.generateJson<QueryGenerationResult>(
+      SYSTEM_PROMPT,
+      userPrompt,
+      { temperature: 0.5 }
+    );
+  } else {
+    return openai.generateJson<QueryGenerationResult>(
+      SYSTEM_PROMPT,
+      userPrompt,
+      { temperature: 0.5 }
+    );
+  }
+}
+
+export async function generateFollowUpQueries(
+  topic: string,
+  existingFindings: string,
+  queryCount: number,
+  model: ModelProvider
+): Promise<QueryGenerationResult> {
+  const followUpPrompt = `Research Topic: "${topic}"
+
+Based on initial research findings, generate ${queryCount} follow-up queries to fill gaps and explore deeper.
+
+Initial Findings Summary:
+${existingFindings}
+
+Generate queries that:
+1. Explore areas not covered in initial findings
+2. Go deeper into important subtopics
+3. Find contradicting viewpoints or alternative perspectives
+4. Discover more recent information
+
+Respond with a JSON object in this exact format:
+{
+  "queries": ["query1", "query2", ...],
+  "reasoning": "Brief explanation of what gaps these queries address"
+}`;
+
+  if (model === "claude") {
+    return anthropic.generateJson<QueryGenerationResult>(
+      SYSTEM_PROMPT,
+      followUpPrompt,
+      { temperature: 0.6 }
+    );
+  } else {
+    return openai.generateJson<QueryGenerationResult>(
+      SYSTEM_PROMPT,
+      followUpPrompt,
+      { temperature: 0.6 }
+    );
+  }
+}

package/skills/skill-deepresearch/src/agents/synthesizer.ts

@@ -0,0 +1,111 @@
+import type { ModelProvider, Source, SynthesisResult } from "../types";
+import * as anthropic from "../services/anthropic";
+import * as openai from "../services/openai";
+
+const SYSTEM_PROMPT = `You are an expert research analyst who synthesizes information from multiple sources into comprehensive, well-structured reports.
+
+Your reports should:
+- Be factual and objective
+- Cite sources using [1], [2], etc. notation
+- Present multiple perspectives when they exist
+- Highlight areas of consensus and disagreement
+- Use clear markdown formatting
+- Be thorough but concise`;
+
+function formatSources(sources: Source[]): string {
+  return sources
+    .map(
+      (s) => `
+[Source ${s.id}] ${s.title}
+URL: ${s.url}
+${s.publishedDate ? `Published: ${s.publishedDate}` : ""}
+${s.author ? `Author: ${s.author}` : ""}
+
+Content:
+${s.content.slice(0, 2500)}${s.content.length > 2500 ? "..." : ""}
+`
+    )
+    .join("\n---\n");
+}
+
+function buildSynthesisPrompt(topic: string, sources: Source[]): string {
+  return `Create a comprehensive research report on: "${topic}"
+
+Based on the following ${sources.length} sources:
+
+${formatSources(sources)}
+
+Write a research report with these sections:
+
+## Executive Summary
+A 2-3 paragraph overview of the key findings.
+
+## Key Findings
+Bullet points of the most important discoveries.
+
+## Detailed Analysis
+Organized by subtopic, with in-depth coverage. Use headers for each major subtopic.
+
+## Conclusions
+Summary of insights and any recommendations.
+
+Requirements:
+- Cite sources inline using [1], [2], etc.
+- Be objective and factual
+- Present conflicting viewpoints if they exist
+- Use markdown formatting
+- Aim for thoroughness while staying focused`;
+}
+
+export async function synthesizeReport(
+  topic: string,
+  sources: Source[],
+  model: ModelProvider
+): Promise<SynthesisResult> {
+  if (sources.length === 0) {
+    return {
+      report:
+        "## No Sources Found\n\nNo relevant sources were found for this research topic. Please try refining your query or using different search terms.",
+    };
+  }
+
+  const userPrompt = buildSynthesisPrompt(topic, sources);
+
+  const report =
+    model === "claude"
+      ? await anthropic.generateText(SYSTEM_PROMPT, userPrompt, {
+          maxTokens: 16384,
+          temperature: 0.4,
+        })
+      : await openai.generateText(SYSTEM_PROMPT, userPrompt, {
+          maxTokens: 16384,
+          temperature: 0.4,
+        });
+
+  return { report };
+}
+
+export async function generateFindingsSummary(
+  sources: Source[],
+  model: ModelProvider
+): Promise<string> {
+  if (sources.length === 0) {
+    return "No findings yet.";
+  }
+
+  const prompt = `Summarize the key themes and findings from these sources in 2-3 paragraphs:
+
+${sources.slice(0, 15).map((s) => `- ${s.title}: ${s.content.slice(0, 500)}`).join("\n")}
+
+Focus on:
+1. Main themes covered
+2. Key facts and findings
+3. Any gaps or areas needing more research`;
+
+  const systemPrompt =
+    "You are a research assistant. Provide concise summaries of research findings.";
+
+  return model === "claude"
+    ? anthropic.generateText(systemPrompt, prompt, { maxTokens: 1000 })
+    : openai.generateText(systemPrompt, prompt, { maxTokens: 1000 });
+}