@hasna/skills 0.1.23 → 0.1.25

package/skills/read-excel/src/index.ts

@@ -0,0 +1,266 @@
+#!/usr/bin/env bun
+
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+
+type XlsxModule = typeof import("xlsx");
+type WorkBook = import("xlsx").WorkBook;
+type WorkSheet = import("xlsx").WorkSheet;
+type CellObject = import("xlsx").CellObject;
+
+const VERSION = "0.1.0";
+
+interface CliOptions {
+  input?: string;
+  sheets?: string[];
+  limit?: number;
+  output?: string;
+}
+
+interface NamedRange {
+  name: string;
+  ref: string;
+  sheet?: string;
+}
+
+interface SheetResult {
+  name: string;
+  index: number;
+  range: string | null;
+  rowCount: number;
+  columnCount: number;
+  columns: string[];
+  rows: Array<Record<string, unknown>>;
+  formattedCells: Array<{ cell: string; raw?: unknown; formatted?: string; format?: string }>;
+}
+
+interface WorkbookResult {
+  input: string;
+  workbook: {
+    sheetNames: string[];
+    namedRanges: NamedRange[];
+  };
+  sheets: SheetResult[];
+}
+
+async function loadXlsx(): Promise<XlsxModule> {
+  try {
+    return await import("xlsx");
+  } catch {
+    throw new Error("Missing dependency 'xlsx'. Run bun install in this skill directory.");
+  }
+}
+
+function printHelp(): void {
+  console.log(`read-excel v${VERSION}
+
+USAGE:
+  read-excel --input <path> [options]
+
+OPTIONS:
+  -i, --input <path>      Excel workbook to parse (.xls or .xlsx)
+  -s, --sheets <list>     Comma-separated sheet names to include
+  -l, --limit <n>         Limit rows returned per sheet
+  -o, --output <path>     Save JSON result to a file
+      --help              Show this help message
+      --version           Show the current version
+`);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      case "--version":
+      case "-v":
+        console.log(VERSION);
+        process.exit(0);
+      case "--input":
+      case "-i":
+        options.input = argv[++i];
+        break;
+      case "--sheets":
+      case "-s":
+        options.sheets = (argv[++i] ?? "")
+          .split(",")
+          .map((value) => value.trim())
+          .filter(Boolean);
+        break;
+      case "--limit":
+      case "-l": {
+        const value = Number.parseInt(argv[++i] ?? "", 10);
+        if (!Number.isFinite(value) || value <= 0) {
+          throw new Error(`Invalid --limit value: ${argv[i]}`);
+        }
+        options.limit = value;
+        break;
+      }
+      case "--output":
+      case "-o":
+        options.output = argv[++i];
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        if (!options.input) {
+          options.input = arg;
+          break;
+        }
+        throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  if (!options.input) {
+    throw new Error("Missing required --input <path> argument");
+  }
+
+  return options;
+}
+
+function normalizeColumnName(value: unknown, index: number, seen: Set<string>): string {
+  const text = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || `column_${index + 1}`;
+
+  let next = text;
+  let suffix = 2;
+  while (seen.has(next)) {
+    next = `${text}_${suffix}`;
+    suffix += 1;
+  }
+  seen.add(next);
+  return next;
+}
+
+function inferHeader(rows: unknown[][]): boolean {
+  if (rows.length < 2) {
+    return false;
+  }
+  const first = rows[0];
+  const second = rows[1];
+  const unique = new Set(first.map((value) => String(value ?? "").trim().toLowerCase()).filter(Boolean));
+  const mostlyText = first.filter((value) => String(value ?? "").trim() !== "" && Number.isNaN(Number(value))).length >= Math.ceil(first.length / 2);
+  const secondHasNumeric = second.some((value) => String(value ?? "").trim() !== "" && !Number.isNaN(Number(value)));
+  return unique.size === first.length && mostlyText && secondHasNumeric;
+}
+
+function collectFormattedCells(sheet: WorkSheet, maxCells = 50): Array<{ cell: string; raw?: unknown; formatted?: string; format?: string }> {
+  const result: Array<{ cell: string; raw?: unknown; formatted?: string; format?: string }> = [];
+  const entries = Object.entries(sheet).filter(([key]) => !key.startsWith("!"));
+
+  for (const [cell, value] of entries) {
+    if (result.length >= maxCells) {
+      break;
+    }
+    const cellValue = value as CellObject;
+    if (cellValue.z || cellValue.w) {
+      result.push({
+        cell,
+        raw: cellValue.v,
+        formatted: cellValue.w,
+        format: typeof cellValue.z === "string" ? cellValue.z : undefined,
+      });
+    }
+  }
+
+  return result;
+}
+
+function parseSheet(xlsx: XlsxModule, name: string, index: number, sheet: WorkSheet, limit?: number): SheetResult {
+  const rows = xlsx.utils.sheet_to_json(sheet, {
+    header: 1,
+    defval: null,
+    raw: false,
+    blankrows: false,
+  }) as unknown[][];
+
+  const trimmedRows = limit ? rows.slice(0, limit + 1) : rows;
+  const hasHeader = inferHeader(trimmedRows);
+  const headerRow = trimmedRows[0] ?? [];
+  const seen = new Set<string>();
+  const columns = (hasHeader ? headerRow : headerRow.map((_, colIndex) => `column_${colIndex + 1}`))
+    .map((value, colIndex) => normalizeColumnName(value, colIndex, seen));
+
+  const dataRows = hasHeader ? trimmedRows.slice(1) : trimmedRows;
+  const normalizedRows = dataRows.map((row) =>
+    columns.reduce<Record<string, unknown>>((record, column, colIndex) => {
+      record[column] = row[colIndex] ?? null;
+      return record;
+    }, {})
+  );
+
+  return {
+    name,
+    index,
+    range: sheet["!ref"] ?? null,
+    rowCount: normalizedRows.length,
+    columnCount: columns.length,
+    columns,
+    rows: normalizedRows,
+    formattedCells: collectFormattedCells(sheet),
+  };
+}
+
+function collectNamedRanges(workbook: WorkBook): NamedRange[] {
+  const names = workbook.Workbook?.Names ?? [];
+  return names.map((entry) => ({
+    name: entry.Name ?? "",
+    ref: entry.Ref ?? "",
+    sheet: entry.Sheet != null ? workbook.SheetNames[entry.Sheet] : undefined,
+  }));
+}
+
+async function writeJson(path: string, payload: WorkbookResult): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const xlsx = await loadXlsx();
+  const inputPath = resolve(options.input!);
+  const workbook = xlsx.readFile(inputPath, {
+    cellDates: true,
+    cellNF: true,
+    cellStyles: true,
+    dense: false,
+  });
+
+  const selectedSheetNames = options.sheets?.length
+    ? workbook.SheetNames.filter((name) => options.sheets!.includes(name))
+    : workbook.SheetNames;
+
+  if (selectedSheetNames.length === 0) {
+    throw new Error("No matching sheets found");
+  }
+
+  const result: WorkbookResult = {
+    input: inputPath,
+    workbook: {
+      sheetNames: workbook.SheetNames,
+      namedRanges: collectNamedRanges(workbook),
+    },
+    sheets: selectedSheetNames.map((name) => parseSheet(xlsx, name, workbook.SheetNames.indexOf(name), workbook.Sheets[name], options.limit)),
+  };
+
+  if (options.output) {
+    await writeJson(resolve(options.output), result);
+  } else {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`read-excel: ${message}\n`);
+  process.exit(1);
+});

package/skills/read-image/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: read-image
+description: Analyze an image from a local path or URL with Claude vision. Supports prompt-controlled description, OCR, object counting, and brand/visual extraction.
+---
+
+# Read Image
+
+Analyze an image with Claude vision and return structured JSON containing the prompt, model, and extracted analysis.
+
+## Features
+
+- Supports local files and remote URLs
+- Accepts PNG, JPG, JPEG, GIF, and WEBP
+- Prompt-controlled output for OCR, object counting, branding, layout analysis, and more
+- Emits plain text or JSON
+
+## Requirements
+
+- `ANTHROPIC_API_KEY` must be available in the environment
+
+## Usage
+
+```bash
+# Describe a local image
+read-image --input ./product-shot.jpg
+
+# OCR a receipt from a URL
+read-image \
+  --input https://example.com/receipt.png \
+  --prompt "Extract every line item, subtotal, tax, and total."
+
+# Return plain text only
+read-image --input ./wireframe.webp --text
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-i, --input <path-or-url>` | Local image path or image URL | required |
+| `-p, --prompt <text>` | What Claude should extract or describe | detailed description + OCR |
+| `-m, --model <name>` | Anthropic model to call | `ANTHROPIC_MODEL` or built-in default |
+| `--max-tokens <n>` | Maximum response tokens | 1200 |
+| `-o, --output <path>` | Save result to a file | stdout |
+| `--text` | Emit only Claude's text response | false |
+| `--help` | Show usage | |
+| `--version` | Show version | |

package/skills/read-image/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "read-image",
+  "version": "0.1.0",
+  "description": "Analyze local or remote images with Claude vision",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "read-image": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "image",
+    "vision",
+    "ocr",
+    "claude",
+    "skill"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/read-image/src/index.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, extname, resolve } from "path";
+
+const VERSION = "0.1.0";
+const DEFAULT_MODEL = process.env.ANTHROPIC_MODEL || "claude-sonnet-4-20250514";
+const DEFAULT_PROMPT =
+  "Describe this image in detail. Extract any visible text, call out objects, layout, branding, and anything notable.";
+const API_URL = process.env.ANTHROPIC_API_URL || "https://api.anthropic.com/v1/messages";
+
+interface CliOptions {
+  input?: string;
+  prompt: string;
+  model: string;
+  maxTokens: number;
+  output?: string;
+  text: boolean;
+}
+
+interface ImageAnalysisResult {
+  input: string;
+  sourceType: "file" | "url";
+  model: string;
+  prompt: string;
+  analysis: string;
+  stopReason: string | null;
+  usage: unknown;
+}
+
+function printHelp(): void {
+  console.log(`read-image v${VERSION}
+
+USAGE:
+  read-image --input <path-or-url> [options]
+
+OPTIONS:
+  -i, --input <path-or-url>  Local image path or remote URL
+  -p, --prompt <text>        Extraction or analysis prompt
+  -m, --model <name>         Anthropic model to call
+      --max-tokens <n>       Maximum response tokens
+  -o, --output <path>        Save result to a file
+      --text                 Print only Claude's text response
+      --help                 Show this help message
+      --version              Show the current version
+`);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    prompt: DEFAULT_PROMPT,
+    model: DEFAULT_MODEL,
+    maxTokens: 1200,
+    text: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      case "--version":
+      case "-v":
+        console.log(VERSION);
+        process.exit(0);
+      case "--input":
+      case "-i":
+        options.input = argv[++i];
+        break;
+      case "--prompt":
+      case "-p":
+        options.prompt = argv[++i] ?? DEFAULT_PROMPT;
+        break;
+      case "--model":
+      case "-m":
+        options.model = argv[++i] ?? DEFAULT_MODEL;
+        break;
+      case "--max-tokens": {
+        const value = Number.parseInt(argv[++i] ?? "", 10);
+        if (!Number.isFinite(value) || value <= 0) {
+          throw new Error(`Invalid --max-tokens value: ${argv[i]}`);
+        }
+        options.maxTokens = value;
+        break;
+      }
+      case "--output":
+      case "-o":
+        options.output = argv[++i];
+        break;
+      case "--text":
+        options.text = true;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        if (!options.input) {
+          options.input = arg;
+          break;
+        }
+        throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  if (!options.input) {
+    throw new Error("Missing required --input <path-or-url> argument");
+  }
+
+  return options;
+}
+
+function isUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function getImageMediaType(value: string): string {
+  const extension = extname(value).toLowerCase();
+  switch (extension) {
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".png":
+      return "image/png";
+    case ".gif":
+      return "image/gif";
+    case ".webp":
+      return "image/webp";
+    default:
+      throw new Error(`Unsupported image format: ${extension || value}`);
+  }
+}
+
+async function buildImageBlock(input: string): Promise<{ block: Record<string, unknown>; sourceType: "file" | "url"; resolvedInput: string }> {
+  if (isUrl(input)) {
+    return {
+      block: {
+        type: "image",
+        source: {
+          type: "url",
+          url: input,
+        },
+      },
+      sourceType: "url",
+      resolvedInput: input,
+    };
+  }
+
+  const resolvedInput = resolve(input);
+  const mediaType = getImageMediaType(resolvedInput);
+  const bytes = await readFile(resolvedInput);
+  return {
+    block: {
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: mediaType,
+        data: Buffer.from(bytes).toString("base64"),
+      },
+    },
+    sourceType: "file",
+    resolvedInput,
+  };
+}
+
+async function callAnthropic(
+  model: string,
+  maxTokens: number,
+  prompt: string,
+  imageBlock: Record<string, unknown>,
+): Promise<{ analysis: string; usage: unknown; stopReason: string | null }> {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing ANTHROPIC_API_KEY");
+  }
+
+  const response = await fetch(API_URL, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      messages: [
+        {
+          role: "user",
+          content: [
+            imageBlock,
+            {
+              type: "text",
+              text: prompt,
+            },
+          ],
+        },
+      ],
+    }),
+  });
+
+  const payload = await response.json() as {
+    content?: Array<{ type: string; text?: string }>;
+    usage?: unknown;
+    stop_reason?: string | null;
+    error?: { message?: string };
+  };
+
+  if (!response.ok) {
+    throw new Error(payload.error?.message || `Anthropic request failed with status ${response.status}`);
+  }
+
+  const analysis = (payload.content ?? [])
+    .filter((entry) => entry.type === "text" && typeof entry.text === "string")
+    .map((entry) => entry.text)
+    .join("\n\n");
+
+  return {
+    analysis,
+    usage: payload.usage ?? null,
+    stopReason: payload.stop_reason ?? null,
+  };
+}
+
+async function writeOutput(path: string, value: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, value, "utf8");
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const { block, sourceType, resolvedInput } = await buildImageBlock(options.input!);
+  const response = await callAnthropic(options.model, options.maxTokens, options.prompt, block);
+
+  const result: ImageAnalysisResult = {
+    input: resolvedInput,
+    sourceType,
+    model: options.model,
+    prompt: options.prompt,
+    analysis: response.analysis,
+    stopReason: response.stopReason,
+    usage: response.usage,
+  };
+
+  const output = options.text ? `${response.analysis}\n` : `${JSON.stringify(result, null, 2)}\n`;
+
+  if (options.output) {
+    await writeOutput(resolve(options.output), output);
+  } else {
+    process.stdout.write(output);
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`read-image: ${message}\n`);
+  process.exit(1);
+});

package/skills/read-pdf/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: read-pdf
+description: Analyze PDF files with Claude document blocks. Supports page-range selection, 20-page chunking, and merged structured output.
+---
+
+# Read PDF
+
+Analyze a PDF with Claude's native document support and return structured output for the requested pages.
+
+## Features
+
+- Supports page range selection like `1-5,8,10-12`
+- Chunks large selections into windows of up to 20 pages per request
+- Emits merged JSON, markdown, or plain-text output
+- Preserves chunk/page metadata so downstream tools can trace the source pages
+
+## Requirements
+
+- `ANTHROPIC_API_KEY` must be available in the environment
+
+## Usage
+
+```bash
+# Read the whole PDF with markdown output
+read-pdf --input ./deck.pdf
+
+# Restrict to a few pages
+read-pdf --input ./contract.pdf --pages 1-3,8 --format text
+
+# Ask for specific structure and save it
+read-pdf \
+  --input ./invoice.pdf \
+  --prompt "Extract invoice metadata, every line item, and the payment terms." \
+  --format json \
+  --output ./invoice.json
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-i, --input <path-or-url>` | PDF file path or URL | required |
+| `--pages <ranges>` | Page ranges like `1-5,8,10-12` | all pages |
+| `-p, --prompt <text>` | What Claude should extract | text + tables + structure |
+| `-f, --format <value>` | `json`, `markdown`, or `text` | `markdown` |
+| `-m, --model <name>` | Anthropic model to call | `ANTHROPIC_MODEL` or built-in default |
+| `--chunk-size <n>` | Pages per request (max 20) | 20 |
+| `--max-tokens <n>` | Maximum response tokens per chunk | 1600 |
+| `-o, --output <path>` | Save result to a file | stdout |
+| `--text` | Emit only the merged extracted text | false |
+| `--help` | Show usage | |
+| `--version` | Show version | |

package/skills/read-pdf/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "read-pdf",
+  "version": "0.1.0",
+  "description": "Analyze PDFs with Claude document blocks and merge chunked output",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "read-pdf": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "pdf",
+    "claude",
+    "document",
+    "ocr",
+    "skill"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}