@hasna/skills 0.0.2

package/skills/skill-deepresearch/src/index.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env bun
+
+import { program } from "commander";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { runResearch } from "./research";
+import type { DepthLevel, ModelProvider, ResearchConfig } from "./types";
+import logger from "./utils/logger";
+
+type Platform = "claude" | "codex";
+
+// ============================================================================
+// Install Command
+// ============================================================================
+
+const SKILL_MD_CONTENT = `---
+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.
+
+## CLI Usage
+
+Run the CLI directly:
+
+\`\`\`bash
+# Basic usage
+skill-deepresearch "What are the best practices for building RAG systems?"
+
+# Quick research (6 queries)
+skill-deepresearch "What is vector search?" --depth quick
+
+# Normal research (15 queries, default)
+skill-deepresearch "Best practices for ML systems" --depth normal
+
+# Deep research (30 queries, 2 iterations)
+skill-deepresearch "Compare React vs Vue" --depth deep
+
+# Use OpenAI instead of Claude
+skill-deepresearch "State of AI in 2024" --model openai
+
+# Custom output location
+skill-deepresearch "Kubernetes best practices" --output ./k8s-research.md
+
+# Include raw sources JSON
+skill-deepresearch "GraphQL vs REST APIs" --json
+\`\`\`
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| \`-d, --depth <level>\` | Research depth: quick, normal, deep | normal |
+| \`-m, --model <provider>\` | LLM: claude or openai | claude |
+| \`-o, --output <path>\` | Custom output path | exports/ |
+| \`-j, --json\` | Also save sources as JSON | false |
+| \`--no-firecrawl\` | Skip deep scraping | false |
+
+## Depth Levels
+
+| Level | Queries | Iterations | Use Case |
+|-------|---------|------------|----------|
+| quick | 6 | 1 | Fast overview |
+| normal | 15 | 1 | Standard research |
+| deep | 30 | 2 | Thorough analysis |
+
+## Data Directories
+
+- **exports/** - Generated research reports
+- **uploads/** - User-provided files for context
+- **logs/** - Execution logs
+
+## Requirements
+
+- \`EXA_API_KEY\` in \`~/.secrets\` - Required for search
+- \`ANTHROPIC_API_KEY\` in \`~/.secrets\` - Required for Claude synthesis
+- \`OPENAI_API_KEY\` in \`~/.secrets\` - Required for OpenAI synthesis
+- \`FIRECRAWL_API_KEY\` in \`~/.secrets\` - Optional for deep scraping
+- Bun runtime with \`skill-deepresearch\` installed globally
+
+## Install CLI
+
+\`\`\`bash
+bun add -g @hasnaxyz/skill-deepresearch
+\`\`\`
+`;
+
+async function ensureDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+function getSkillsDir(platform: Platform, local: boolean): string {
+  if (local) {
+    return platform === "claude" ? ".claude/skills" : ".codex/skills";
+  }
+  const home = homedir();
+  return platform === "claude"
+    ? join(home, ".claude", "skills")
+    : join(home, ".codex", "skills");
+}
+
+async function installSkill(options: {
+  platform: Platform;
+  local: boolean;
+}): Promise<void> {
+  const skillName = "skill-deepresearch";
+  const baseDir = getSkillsDir(options.platform, options.local);
+  const skillDir = join(baseDir, skillName);
+
+  try {
+    logger.startSpinner(`Installing skill to ${options.platform === "claude" ? "Claude Code" : "Codex"}...`);
+
+    // Create skill directory structure
+    await ensureDir(skillDir);
+    await ensureDir(join(skillDir, "exports"));
+    await ensureDir(join(skillDir, "uploads"));
+    await ensureDir(join(skillDir, "logs"));
+
+    // Write SKILL.md
+    const skillMdPath = join(skillDir, "SKILL.md");
+    await writeFile(skillMdPath, SKILL_MD_CONTENT, "utf-8");
+
+    logger.succeedSpinner(`Installed to ${skillDir}`);
+
+    console.log();
+    logger.success(`Skill ${skillName} installed successfully`);
+    console.log();
+    console.log("Created structure:");
+    console.log(`  ${skillDir}/`);
+    console.log(`  ├── SKILL.md`);
+    console.log(`  ├── exports/`);
+    console.log(`  ├── uploads/`);
+    console.log(`  └── logs/`);
+    console.log();
+    console.log(`Invoke with: /${skillName}`);
+
+  } catch (error) {
+    logger.failSpinner("Install failed");
+    if (error instanceof Error) {
+      logger.error(error.message);
+    }
+    process.exit(1);
+  }
+}
+
+// ============================================================================
+// CLI Setup
+// ============================================================================
+
+program
+  .name("skill-deepresearch")
+  .description("Agentic deep research using Exa.ai search and LLM synthesis")
+  .version("0.1.1");
+
+// Install subcommand
+program
+  .command("install")
+  .description("Install this skill to Claude Code or Codex")
+  .option("--claude", "Install to Claude Code (~/.claude/skills/)")
+  .option("--codex", "Install to OpenAI Codex (~/.codex/skills/)")
+  .option("--local", "Install to local repo (.claude/skills/ or .codex/skills/)")
+  .action(async (options) => {
+    if (!options.claude && !options.codex) {
+      logger.error("Please specify --claude or --codex");
+      process.exit(1);
+    }
+
+    const platforms: Platform[] = [];
+    if (options.claude) platforms.push("claude");
+    if (options.codex) platforms.push("codex");
+
+    for (const platform of platforms) {
+      await installSkill({
+        platform,
+        local: options.local || false,
+      });
+    }
+  });
+
+// Research command (default)
+program
+  .argument("<topic>", "Research topic or question")
+  .option("-d, --depth <level>", "Research depth: quick, normal, deep", "normal")
+  .option("-m, --model <provider>", "LLM for synthesis: claude, openai", "claude")
+  .option("-o, --output <path>", "Custom output path for report")
+  .option("-j, --json", "Also output sources as JSON")
+  .option("--no-firecrawl", "Skip Firecrawl deep scraping")
+  .action(async (topic: string, options) => {
+    const validDepths: DepthLevel[] = ["quick", "normal", "deep"];
+    const validModels: ModelProvider[] = ["claude", "openai"];
+
+    if (!validDepths.includes(options.depth as DepthLevel)) {
+      logger.error(`Invalid depth: ${options.depth}. Use: ${validDepths.join(", ")}`);
+      process.exit(1);
+    }
+
+    if (!validModels.includes(options.model as ModelProvider)) {
+      logger.error(`Invalid model: ${options.model}. Use: ${validModels.join(", ")}`);
+      process.exit(1);
+    }
+
+    const config: ResearchConfig = {
+      topic,
+      depth: options.depth as DepthLevel,
+      model: options.model as ModelProvider,
+      output: options.output,
+      json: options.json,
+      firecrawl: options.firecrawl,
+    };
+
+    try {
+      await runResearch(config);
+    } catch (error) {
+      logger.stopSpinner();
+      logger.error(error instanceof Error ? error.message : "Unknown error");
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/skills/skill-deepresearch/src/research.ts

@@ -0,0 +1,166 @@
+import type { ResearchConfig, ResearchReport, Source, DepthLevel } from "./types";
+import { DEPTH_CONFIG } from "./types";
+import { generateQueries, generateFollowUpQueries } from "./agents/query-generator";
+import { synthesizeReport, generateFindingsSummary } from "./agents/synthesizer";
+import { searchInBatches, isExaConfigured } from "./services/exa";
+import { scrapeUrls, isFirecrawlConfigured } from "./services/firecrawl";
+import { isAnthropicConfigured } from "./services/anthropic";
+import { isOpenAIConfigured } from "./services/openai";
+import { saveReport, saveSourcesJson } from "./utils/file";
+import logger from "./utils/logger";
+
+export function validateConfig(config: ResearchConfig): void {
+  if (!isExaConfigured()) {
+    throw new Error("EXA_API_KEY is required for search. Set it in ~/.secrets");
+  }
+
+  if (config.model === "claude" && !isAnthropicConfigured()) {
+    throw new Error("ANTHROPIC_API_KEY is required for Claude synthesis. Set it in ~/.secrets");
+  }
+
+  if (config.model === "openai" && !isOpenAIConfigured()) {
+    throw new Error("OPENAI_API_KEY is required for OpenAI synthesis. Set it in ~/.secrets");
+  }
+
+  if (config.firecrawl && !isFirecrawlConfigured()) {
+    logger.warn("FIRECRAWL_API_KEY not set. Skipping deep scraping.");
+  }
+}
+
+async function runSearchIteration(
+  topic: string,
+  depth: DepthLevel,
+  model: ResearchConfig["model"],
+  existingSources: Source[],
+  iterationNum: number
+): Promise<Source[]> {
+  const settings = DEPTH_CONFIG[depth];
+  const queryCount = iterationNum === 1
+    ? settings.queryCount
+    : Math.floor(settings.queryCount / 2);
+
+  logger.startSpinner(`Generating ${queryCount} search queries (iteration ${iterationNum})...`);
+
+  let queries: string[];
+  if (iterationNum === 1) {
+    const result = await generateQueries(topic, queryCount, model);
+    queries = result.queries;
+  } else {
+    const summary = await generateFindingsSummary(existingSources, model);
+    const result = await generateFollowUpQueries(topic, summary, queryCount, model);
+    queries = result.queries;
+  }
+
+  logger.succeedSpinner(`Generated ${queries.length} queries`);
+
+  logger.startSpinner("Searching...");
+  const newSources = await searchInBatches(queries, settings.resultsPerQuery);
+  logger.succeedSpinner(`Found ${newSources.length} unique sources`);
+
+  return newSources;
+}
+
+async function deepScrapeTopSources(
+  sources: Source[],
+  maxScrape: number = 5
+): Promise<Source[]> {
+  if (!isFirecrawlConfigured()) {
+    return sources;
+  }
+
+  const topSources = sources
+    .sort((a, b) => (b.relevanceScore || 0) - (a.relevanceScore || 0))
+    .slice(0, maxScrape);
+
+  logger.startSpinner(`Deep scraping top ${topSources.length} sources with Firecrawl...`);
+
+  const scrapeResults = await scrapeUrls(topSources.map((s) => s.url));
+
+  let enhancedCount = 0;
+  for (const result of scrapeResults) {
+    if (result.success && result.markdown) {
+      const source = sources.find((s) => s.url === result.url);
+      if (source && result.markdown.length > source.content.length) {
+        source.content = result.markdown.slice(0, 8000);
+        enhancedCount++;
+      }
+    }
+  }
+
+  logger.succeedSpinner(`Enhanced ${enhancedCount} sources with deeper content`);
+
+  return sources;
+}
+
+export async function runResearch(config: ResearchConfig): Promise<ResearchReport> {
+  const { topic, depth, model, firecrawl, output, json } = config;
+  const settings = DEPTH_CONFIG[depth];
+
+  logger.header("Deep Research");
+  logger.stats("Topic", topic);
+  logger.stats("Depth", `${depth} (${settings.queryCount} queries, ${settings.iterations} iteration${settings.iterations > 1 ? "s" : ""})`);
+  logger.stats("Model", model);
+  logger.divider();
+
+  validateConfig(config);
+
+  let allSources: Source[] = [];
+
+  for (let iteration = 1; iteration <= settings.iterations; iteration++) {
+    if (settings.iterations > 1) {
+      logger.info(`Starting iteration ${iteration} of ${settings.iterations}`);
+    }
+
+    const newSources = await runSearchIteration(
+      topic,
+      depth,
+      model,
+      allSources,
+      iteration
+    );
+
+    const existingUrls = new Set(allSources.map((s) => s.url));
+    const uniqueNewSources = newSources.filter((s) => !existingUrls.has(s.url));
+
+    let nextId = allSources.length + 1;
+    for (const source of uniqueNewSources) {
+      source.id = nextId++;
+    }
+
+    allSources = [...allSources, ...uniqueNewSources];
+    logger.info(`Total unique sources: ${allSources.length}`);
+  }
+
+  if (firecrawl !== false && isFirecrawlConfigured()) {
+    allSources = await deepScrapeTopSources(allSources);
+  }
+
+  logger.startSpinner("Synthesizing report...");
+  const synthesis = await synthesizeReport(topic, allSources, model);
+  logger.succeedSpinner("Report synthesized");
+
+  const report: ResearchReport = {
+    topic,
+    depth,
+    generatedAt: new Date().toISOString(),
+    queryCount: settings.queryCount * settings.iterations,
+    sourceCount: allSources.length,
+    report: synthesis.report,
+    sources: allSources,
+  };
+
+  const reportPath = await saveReport(report, output);
+  logger.success(`Report saved: ${reportPath}`);
+
+  if (json) {
+    const sourcesPath = await saveSourcesJson(allSources, topic, output);
+    logger.success(`Sources JSON saved: ${sourcesPath}`);
+  }
+
+  logger.divider();
+  logger.header("Research Complete");
+  logger.stats("Sources analyzed", allSources.length);
+  logger.stats("Output", reportPath);
+
+  return report;
+}

package/skills/skill-deepresearch/src/services/anthropic.ts

@@ -0,0 +1,69 @@
+import Anthropic from "@anthropic-ai/sdk";
+
+let client: Anthropic | null = null;
+
+function getClient(): Anthropic {
+  if (!client) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "ANTHROPIC_API_KEY not found. Please set it in ~/.secrets or environment."
+      );
+    }
+    client = new Anthropic({ apiKey });
+  }
+  return client;
+}
+
+export async function generateText(
+  systemPrompt: string,
+  userPrompt: string,
+  options?: {
+    maxTokens?: number;
+    temperature?: number;
+  }
+): Promise<string> {
+  const anthropic = getClient();
+
+  const response = await anthropic.messages.create({
+    model: "claude-sonnet-4-20250514",
+    max_tokens: options?.maxTokens || 8192,
+    temperature: options?.temperature ?? 0.7,
+    system: systemPrompt,
+    messages: [{ role: "user", content: userPrompt }],
+  });
+
+  const textBlock = response.content.find((block) => block.type === "text");
+  if (!textBlock || textBlock.type !== "text") {
+    throw new Error("No text response from Claude");
+  }
+
+  return textBlock.text;
+}
+
+export async function generateJson<T>(
+  systemPrompt: string,
+  userPrompt: string,
+  options?: {
+    maxTokens?: number;
+    temperature?: number;
+  }
+): Promise<T> {
+  const text = await generateText(systemPrompt, userPrompt, {
+    ...options,
+    temperature: options?.temperature ?? 0.3,
+  });
+
+  const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const jsonStr = jsonMatch ? jsonMatch[1].trim() : text.trim();
+
+  try {
+    return JSON.parse(jsonStr) as T;
+  } catch {
+    throw new Error(`Failed to parse JSON from Claude response: ${text.slice(0, 200)}`);
+  }
+}
+
+export function isAnthropicConfigured(): boolean {
+  return !!process.env.ANTHROPIC_API_KEY;
+}

package/skills/skill-deepresearch/src/services/exa.ts

@@ -0,0 +1,108 @@
+import Exa from "exa-js";
+import type { ExaSearchResponse, Source } from "../types";
+import logger from "../utils/logger";
+
+const EXA_CONCURRENT_LIMIT = 5;
+
+let client: Exa | null = null;
+
+function getClient(): Exa {
+  if (!client) {
+    const apiKey = process.env.EXA_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "EXA_API_KEY not found. Please set it in ~/.secrets or environment."
+      );
+    }
+    client = new Exa(apiKey);
+  }
+  return client;
+}
+
+export async function searchWithContent(
+  query: string,
+  numResults: number = 5
+): Promise<ExaSearchResponse> {
+  const exa = getClient();
+
+  const response = await exa.searchAndContents(query, {
+    type: "neural",
+    useAutoprompt: true,
+    numResults,
+    text: {
+      maxCharacters: 3000,
+      includeHtmlTags: false,
+    },
+    highlights: {
+      numSentences: 3,
+      highlightsPerUrl: 3,
+    },
+  });
+
+  return {
+    results: response.results.map((r) => ({
+      title: r.title || "Untitled",
+      url: r.url,
+      publishedDate: r.publishedDate,
+      author: r.author,
+      score: r.score,
+      text: r.text,
+      highlights: r.highlights,
+      highlightScores: r.highlightScores,
+    })),
+    autopromptString: response.autopromptString,
+  };
+}
+
+export async function searchInBatches(
+  queries: string[],
+  resultsPerQuery: number = 5
+): Promise<Source[]> {
+  const allSources: Source[] = [];
+  const seenUrls = new Set<string>();
+  let sourceId = 1;
+
+  for (let i = 0; i < queries.length; i += EXA_CONCURRENT_LIMIT) {
+    const batch = queries.slice(i, i + EXA_CONCURRENT_LIMIT);
+    const batchNum = Math.floor(i / EXA_CONCURRENT_LIMIT) + 1;
+    const totalBatches = Math.ceil(queries.length / EXA_CONCURRENT_LIMIT);
+
+    logger.updateSpinner(
+      `Searching batch ${batchNum}/${totalBatches} (${batch.length} queries)...`
+    );
+
+    const batchResults = await Promise.all(
+      batch.map(async (query) => {
+        try {
+          return await searchWithContent(query, resultsPerQuery);
+        } catch (error) {
+          logger.warn(`Search failed for query: "${query.slice(0, 50)}..."`);
+          return { results: [] };
+        }
+      })
+    );
+
+    for (const response of batchResults) {
+      for (const result of response.results) {
+        if (!seenUrls.has(result.url) && result.text) {
+          seenUrls.add(result.url);
+          allSources.push({
+            id: sourceId++,
+            title: result.title,
+            url: result.url,
+            content: result.text,
+            publishedDate: result.publishedDate,
+            author: result.author,
+            relevanceScore: result.score,
+          });
+        }
+      }
+    }
+  }
+
+  return allSources;
+}
+
+export function isExaConfigured(): boolean {
+  return !!process.env.EXA_API_KEY;
+}

package/skills/skill-deepresearch/src/services/firecrawl.ts

@@ -0,0 +1,88 @@
+import type { FirecrawlResult } from "../types";
+
+const FIRECRAWL_API_URL = "https://api.firecrawl.dev/v1/scrape";
+
+export async function scrapeUrl(url: string): Promise<FirecrawlResult> {
+  const apiKey = process.env.FIRECRAWL_API_KEY;
+  if (!apiKey) {
+    return {
+      url,
+      markdown: "",
+      success: false,
+      error: "FIRECRAWL_API_KEY not configured",
+    };
+  }
+
+  try {
+    const response = await fetch(FIRECRAWL_API_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        url,
+        formats: ["markdown"],
+        onlyMainContent: true,
+        waitFor: 2000,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      return {
+        url,
+        markdown: "",
+        success: false,
+        error: `HTTP ${response.status}: ${error}`,
+      };
+    }
+
+    const data = (await response.json()) as {
+      success: boolean;
+      data?: { markdown?: string };
+      error?: string;
+    };
+
+    if (!data.success) {
+      return {
+        url,
+        markdown: "",
+        success: false,
+        error: data.error || "Unknown error",
+      };
+    }
+
+    return {
+      url,
+      markdown: data.data?.markdown || "",
+      success: true,
+    };
+  } catch (error) {
+    return {
+      url,
+      markdown: "",
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+export async function scrapeUrls(
+  urls: string[],
+  concurrentLimit: number = 3
+): Promise<FirecrawlResult[]> {
+  const results: FirecrawlResult[] = [];
+
+  for (let i = 0; i < urls.length; i += concurrentLimit) {
+    const batch = urls.slice(i, i + concurrentLimit);
+    const batchResults = await Promise.all(batch.map((url) => scrapeUrl(url)));
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
+export function isFirecrawlConfigured(): boolean {
+  return !!process.env.FIRECRAWL_API_KEY;
+}