@hasna/skills 0.1.27 → 0.1.29

package/skills/create-blog-article/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist"
-  },
-  "include": [
-    "src/**/*",
-    "bin/**/*"
-  ]
-}

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

@@ -1,91 +0,0 @@
-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/deepresearch/src/agents/synthesizer.ts

@@ -1,111 +0,0 @@
-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 });
-}

package/skills/deepresearch/src/index.ts

@@ -1,224 +0,0 @@
-#!/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: 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
-deepresearch "What are the best practices for building RAG systems?"
-
-# Quick research (6 queries)
-deepresearch "What is vector search?" --depth quick
-
-# Normal research (15 queries, default)
-deepresearch "Best practices for ML systems" --depth normal
-
-# Deep research (30 queries, 2 iterations)
-deepresearch "Compare React vs Vue" --depth deep
-
-# Use OpenAI instead of Claude
-deepresearch "State of AI in 2024" --model openai
-
-# Custom output location
-deepresearch "Kubernetes best practices" --output ./k8s-research.md
-
-# Include raw sources JSON
-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 \`deepresearch\` installed globally
-
-## Install CLI
-
-\`\`\`bash
-bun add -g @hasnaxyz/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 = "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("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/deepresearch/src/research.ts

@@ -1,166 +0,0 @@
-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/deepresearch/src/services/anthropic.ts

@@ -1,69 +0,0 @@
-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;
-}