@hasna/skills 0.1.13 → 0.1.15

package/dist/lib/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Config file support for Open Skills
+ *
+ * Loads configuration from:
+ *   1. Project-local: ./skills.config.json (highest priority)
+ *   2. Global: ~/.skillsrc (JSON format, lowest priority)
+ *
+ * Values from the project config override global config.
+ */
+export interface SkillsConfig {
+    defaultAgent?: "claude" | "codex" | "gemini" | "all";
+    defaultScope?: "global" | "project";
+    format?: "compact" | "json" | "csv";
+}
+export type ConfigScope = "global" | "project";
+/**
+ * Get the config file path for a given scope
+ */
+export declare function getConfigPath(scope: ConfigScope): string;
+/**
+ * Load merged config: project-local overrides global
+ */
+export declare function loadConfig(): SkillsConfig;
+/**
+ * Save a single config key-value pair to the specified scope
+ */
+export declare function saveConfig(key: string, value: string, scope?: ConfigScope): void;

package/dist/lib/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/installer.d.ts

@@ -27,6 +27,30 @@ export declare function installSkill(name: string, options?: InstallOptions): In
  * Install multiple skills
  */
 export declare function installSkills(names: string[], options?: InstallOptions): InstallResult[];
+interface SkillMeta {
+    installedAt: string;
+    version: string;
+}
+interface MetaFile {
+    skills: Record<string, SkillMeta>;
+    disabled?: string[];
+}
+/**
+ * Get installation metadata for installed skills
+ */
+export declare function getInstallMeta(targetDir?: string): MetaFile;
+/**
+ * Disable a skill (exclude from .skills/index.ts without removing files)
+ */
+export declare function disableSkill(name: string, targetDir?: string): boolean;
+/**
+ * Enable a previously disabled skill (re-add to .skills/index.ts)
+ */
+export declare function enableSkill(name: string, targetDir?: string): boolean;
+/**
+ * Get list of disabled skills
+ */
+export declare function getDisabledSkills(targetDir?: string): string[];
 /**
  * Get list of installed skills in a directory
  */
@@ -35,9 +59,11 @@ export declare function getInstalledSkills(targetDir?: string): string[];
  * Remove an installed skill
  */
 export declare function removeSkill(name: string, targetDir?: string): boolean;
-export type AgentTarget = "claude" | "codex" | "gemini";
+export type AgentTarget = "claude" | "codex" | "gemini" | "pi" | "opencode";
 export type AgentScope = "global" | "project";
 export declare const AGENT_TARGETS: AgentTarget[];
+/** Human-readable labels for each agent */
+export declare const AGENT_LABELS: Record<AgentTarget, string>;
 /**
  * Resolve an agent argument ("all" or a specific agent name) to a list of AgentTarget values.
  * Throws if the agent name is not recognized.
@@ -49,7 +75,14 @@ export interface AgentInstallOptions {
     projectDir?: string;
 }
 /**
- * Get the skills directory for a given agent and scope
+ * Get the skills directory for a given agent and scope.
+ *
+ * Agent config dir conventions:
+ *   claude  — ~/.claude/skills/          | .claude/skills/
+ *   codex   — ~/.codex/skills/           | .codex/skills/
+ *   gemini  — ~/.gemini/skills/          | .gemini/skills/
+ *   pi      — ~/.pi/agent/skills/        | .pi/skills/
+ *   opencode — ~/.opencode/skills/       | .opencode/skills/
  */
 export declare function getAgentSkillsDir(agent: AgentTarget, scope?: AgentScope, projectDir?: string): string;
 /**
@@ -65,3 +98,4 @@ export declare function installSkillForAgent(name: string, options: AgentInstall
  * Remove a skill from an agent's skill directory
  */
 export declare function removeSkillForAgent(name: string, options: AgentInstallOptions): boolean;
+export {};

package/dist/lib/registry.d.ts

@@ -8,10 +8,22 @@ export interface SkillMeta {
     category: string;
     tags: string[];
     dependencies?: string[];
+    source?: "official" | "custom";
 }
 export declare const CATEGORIES: readonly ["Development Tools", "Business & Marketing", "Productivity & Organization", "Project Management", "Content Generation", "Finance & Compliance", "Data & Analysis", "Media Processing", "Design & Branding", "Web & Browser", "Research & Writing", "Science & Academic", "Education & Learning", "Communication", "Health & Wellness", "Travel & Lifestyle", "Event Management"];
 export type Category = (typeof CATEGORIES)[number];
 export declare const SKILLS: SkillMeta[];
+/**
+ * Load the full registry: official skills merged with custom skills from:
+ * - ~/.skills/ (global custom)
+ * - ./.custom-skills/ (project-level custom, relative to cwd)
+ *
+ * Custom skills with the same name as official skills take precedence.
+ * Results are cached for 5 seconds.
+ */
+export declare function loadRegistry(cwd?: string): SkillMeta[];
+/** Invalidate the registry cache (e.g. after installing a custom skill). */
+export declare function clearRegistryCache(): void;
 export declare function getSkillsByCategory(category: Category): SkillMeta[];
 export declare function searchSkills(query: string): SkillMeta[];
 export declare function getSkill(name: string): SkillMeta | undefined;
@@ -23,3 +35,7 @@ export declare function getSkillsByTag(tag: string): SkillMeta[];
  * Return all unique tags across every skill, sorted alphabetically.
  */
 export declare function getAllTags(): string[];
+/**
+ * Find skills with names similar to the given query (for "did you mean?" suggestions)
+ */
+export declare function findSimilarSkills(query: string, maxResults?: number): string[];

package/dist/lib/scheduler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Skill scheduler — cron-based scheduling for skills
+ *
+ * Schedules are stored in .skills/schedules.json in the project directory.
+ * Each schedule entry defines a skill to run on a cron expression.
+ *
+ * Cron format: standard 5-field (minute hour dom month dow)
+ * e.g. "0 9 * * *" = every day at 9am
+ */
+export interface SkillSchedule {
+    id: string;
+    name: string;
+    skill: string;
+    cron: string;
+    args?: string[];
+    enabled: boolean;
+    createdAt: string;
+    lastRun?: string;
+    lastRunStatus?: "success" | "error";
+    nextRun?: string;
+}
+/** Validate a 5-field cron expression (basic syntax check). */
+export declare function validateCron(expr: string): {
+    valid: boolean;
+    error?: string;
+};
+/** Compute the next run time for a cron expression relative to a given date. */
+export declare function getNextRun(cron: string, from?: Date): Date | null;
+/** Add a new schedule. Returns the created schedule. */
+export declare function addSchedule(skill: string, cron: string, options?: {
+    name?: string;
+    args?: string[];
+    targetDir?: string;
+}): {
+    schedule: SkillSchedule | null;
+    error?: string;
+};
+/** List all schedules. */
+export declare function listSchedules(targetDir?: string): SkillSchedule[];
+/** Remove a schedule by id or name. Returns true if removed. */
+export declare function removeSchedule(idOrName: string, targetDir?: string): boolean;
+/** Enable or disable a schedule by id or name. */
+export declare function setScheduleEnabled(idOrName: string, enabled: boolean, targetDir?: string): boolean;
+/** Get all schedules that are due now (nextRun <= now and enabled). */
+export declare function getDueSchedules(targetDir?: string): SkillSchedule[];
+/** Mark a schedule as having just run. Updates lastRun and nextRun. */
+export declare function recordScheduleRun(id: string, status: "success" | "error", targetDir?: string): void;

package/dist/types/api.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared API response types used by both the HTTP server and the dashboard.
+ * Import from "@hasna/skills" to get type-safe API responses.
+ */
+export interface SkillResponse {
+    name: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    installed: boolean;
+    envVars: string[];
+    envVarsSet: string[];
+    systemDeps: string[];
+    cliCommand: string | null;
+}
+export interface SkillDetailResponse extends SkillResponse {
+    docs: string | null;
+}
+export interface CategoryResponse {
+    name: string;
+    count: number;
+}
+export interface TagResponse {
+    name: string;
+    count: number;
+}
+export interface InstallResponse {
+    skill: string;
+    success: boolean;
+    error?: string;
+    results?: Array<{
+        skill: string;
+        success: boolean;
+        error?: string;
+    }>;
+}
+export interface RemoveResponse {
+    skill: string;
+    success: boolean;
+}
+export interface VersionResponse {
+    version: string;
+    name: string;
+}
+export interface ExportResponse {
+    version: number;
+    skills: string[];
+    timestamp: string;
+}
+export interface ImportResponse {
+    imported: number;
+    total: number;
+    results: Array<{
+        skill: string;
+        success: boolean;
+        error?: string;
+    }>;
+}
+export interface SearchResponse extends SkillResponse {
+}
+export interface CategoryInstallResponse {
+    category: string;
+    count: number;
+    success: boolean;
+    results: Array<{
+        skill: string;
+        success: boolean;
+        error?: string;
+    }>;
+}
+export interface ErrorResponse {
+    error: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -23,9 +23,12 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "bun build ./src/cli/index.tsx --outdir ./bin --target bun --external ink --external react --external chalk && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/index.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "clean": "rm -rf bin/ dist/",
+    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external ink --external react --external chalk && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/index.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "test": "bun test",
     "dev": "bun run ./src/cli/index.tsx",
+    "dev:watch": "bun --watch run ./src/cli/index.tsx",
+    "dev:mcp": "bun --watch run ./src/mcp/index.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build",
     "dashboard:dev": "cd dashboard && bun run dev",

package/skills/_common/index.ts

@@ -21,3 +21,7 @@ export {
   type AssistantType,
 } from './installer';
 export { handleInstallCommand } from './skill-install';
+
+// Vision client — multi-provider (anthropic/openai/xai/gemini)
+// import { analyzeImage, detectProvider } from './vision.js'
+export * from './vision.js';

package/skills/_common/vision.ts

@@ -0,0 +1,374 @@
+/**
+ * Unified vision client for AI providers.
+ * Follows @hasna/connectors pattern — auto-detects from env vars.
+ * Providers: anthropic, openai, xai, gemini
+ *
+ * Uses built-in fetch only — no external SDK dependencies.
+ */
+
+export type VisionProvider = "anthropic" | "openai" | "xai" | "gemini";
+
+export interface VisionOptions {
+  provider?: VisionProvider;
+  model?: string;
+  maxTokens?: number;
+  systemPrompt?: string;
+  jsonMode?: boolean; // wrap prompt to request JSON response
+}
+
+export interface VisionResult {
+  text: string;
+  provider: VisionProvider;
+  model: string;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+// Default models per provider (vision-capable)
+export const DEFAULT_MODELS: Record<VisionProvider, string> = {
+  anthropic: "claude-sonnet-4-6",
+  openai: "gpt-4o",
+  xai: "grok-2-vision-1212",
+  gemini: "gemini-2.0-flash",
+};
+
+// API key env vars per provider
+export const API_KEY_VARS: Record<VisionProvider, string> = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  xai: "XAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+};
+
+// Base URLs
+const BASE_URLS: Record<VisionProvider, string> = {
+  anthropic: "https://api.anthropic.com/v1/messages",
+  openai: "https://api.openai.com/v1/chat/completions",
+  xai: "https://api.x.ai/v1/chat/completions",
+  gemini: "https://generativelanguage.googleapis.com/v1beta/models",
+};
+
+/**
+ * Auto-detect provider from env vars.
+ * Priority: ANTHROPIC_API_KEY → OPENAI_API_KEY → XAI_API_KEY → GEMINI_API_KEY
+ */
+export function detectProvider(): VisionProvider | null {
+  const order: VisionProvider[] = ["anthropic", "openai", "xai", "gemini"];
+  for (const provider of order) {
+    if (process.env[API_KEY_VARS[provider]]) {
+      return provider;
+    }
+  }
+  return null;
+}
+
+/**
+ * Get API key for a provider. Throws if not set.
+ */
+export function getApiKey(provider: VisionProvider): string {
+  const key = process.env[API_KEY_VARS[provider]];
+  if (!key) {
+    throw new Error(
+      `${API_KEY_VARS[provider]} is not set. Run: connectors setup ${provider}`
+    );
+  }
+  return key;
+}
+
+/**
+ * Strip markdown code fences and JSON.parse.
+ * Throws with raw text on failure.
+ */
+export function parseJsonResponse(text: string): unknown {
+  let str = text.trim();
+  if (str.startsWith("```")) {
+    str = str
+      .replace(/^```(?:json)?\n?/, "")
+      .replace(/\n?```$/, "")
+      .trim();
+  }
+  try {
+    return JSON.parse(str);
+  } catch {
+    throw new Error(
+      `Failed to parse response as JSON.\nRaw response:\n${text}`
+    );
+  }
+}
+
+/**
+ * Returns all providers that have an API key set.
+ */
+export function listAvailableProviders(): VisionProvider[] {
+  return (["anthropic", "openai", "xai", "gemini"] as VisionProvider[]).filter(
+    (p) => !!process.env[API_KEY_VARS[p]]
+  );
+}
+
+/**
+ * Returns availability status for all providers.
+ */
+export function getProviderInfo(): Record<
+  VisionProvider,
+  { available: boolean; model: string; keyVar: string }
+> {
+  return {
+    anthropic: {
+      available: !!process.env[API_KEY_VARS.anthropic],
+      model: DEFAULT_MODELS.anthropic,
+      keyVar: API_KEY_VARS.anthropic,
+    },
+    openai: {
+      available: !!process.env[API_KEY_VARS.openai],
+      model: DEFAULT_MODELS.openai,
+      keyVar: API_KEY_VARS.openai,
+    },
+    xai: {
+      available: !!process.env[API_KEY_VARS.xai],
+      model: DEFAULT_MODELS.xai,
+      keyVar: API_KEY_VARS.xai,
+    },
+    gemini: {
+      available: !!process.env[API_KEY_VARS.gemini],
+      model: DEFAULT_MODELS.gemini,
+      keyVar: API_KEY_VARS.gemini,
+    },
+  };
+}
+
+// ============================================================================
+// Provider implementations
+// ============================================================================
+
+async function analyzeWithAnthropic(
+  imageBase64: string,
+  mediaType: string,
+  prompt: string,
+  model: string,
+  options: VisionOptions
+): Promise<VisionResult> {
+  const apiKey = getApiKey("anthropic");
+  const body: Record<string, unknown> = {
+    model,
+    max_tokens: options.maxTokens ?? 1024,
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "image",
+            source: { type: "base64", media_type: mediaType, data: imageBase64 },
+          },
+          { type: "text", text: prompt },
+        ],
+      },
+    ],
+  };
+  if (options.systemPrompt) {
+    body.system = options.systemPrompt;
+  }
+
+  const response = await fetch(BASE_URLS.anthropic, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${err}`);
+  }
+
+  const data = (await response.json()) as {
+    content: Array<{ type: string; text: string }>;
+    usage: { input_tokens: number; output_tokens: number };
+  };
+
+  return {
+    text: data.content[0].text,
+    provider: "anthropic",
+    model,
+    inputTokens: data.usage?.input_tokens,
+    outputTokens: data.usage?.output_tokens,
+  };
+}
+
+async function analyzeWithOpenAICompat(
+  provider: "openai" | "xai",
+  imageBase64: string,
+  mediaType: string,
+  prompt: string,
+  model: string,
+  options: VisionOptions
+): Promise<VisionResult> {
+  const apiKey = getApiKey(provider);
+  const messages: unknown[] = [];
+
+  if (options.systemPrompt) {
+    messages.push({ role: "system", content: options.systemPrompt });
+  }
+
+  messages.push({
+    role: "user",
+    content: [
+      {
+        type: "image_url",
+        image_url: {
+          url: `data:${mediaType};base64,${imageBase64}`,
+          detail: "high",
+        },
+      },
+      { type: "text", text: prompt },
+    ],
+  });
+
+  const body = {
+    model,
+    max_tokens: options.maxTokens ?? 1024,
+    messages,
+  };
+
+  const response = await fetch(BASE_URLS[provider], {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(
+      `${provider.toUpperCase()} API error ${response.status}: ${err}`
+    );
+  }
+
+  const data = (await response.json()) as {
+    choices: Array<{ message: { content: string } }>;
+    usage: { prompt_tokens: number; completion_tokens: number };
+  };
+
+  return {
+    text: data.choices[0].message.content,
+    provider,
+    model,
+    inputTokens: data.usage?.prompt_tokens,
+    outputTokens: data.usage?.completion_tokens,
+  };
+}
+
+async function analyzeWithGemini(
+  imageBase64: string,
+  mediaType: string,
+  prompt: string,
+  model: string,
+  options: VisionOptions
+): Promise<VisionResult> {
+  const apiKey = getApiKey("gemini");
+  const url = `${BASE_URLS.gemini}/${model}:generateContent?key=${apiKey}`;
+
+  const body: Record<string, unknown> = {
+    contents: [
+      {
+        parts: [
+          { inlineData: { mimeType: mediaType, data: imageBase64 } },
+          { text: prompt },
+        ],
+      },
+    ],
+    generationConfig: {
+      maxOutputTokens: options.maxTokens ?? 1024,
+      ...(options.jsonMode ? { responseMimeType: "application/json" } : {}),
+    },
+  };
+
+  if (options.systemPrompt) {
+    body.systemInstruction = { parts: [{ text: options.systemPrompt }] };
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Gemini API error ${response.status}: ${err}`);
+  }
+
+  const data = (await response.json()) as {
+    candidates: Array<{
+      content: { parts: Array<{ text: string }> };
+    }>;
+    usageMetadata?: { promptTokenCount: number; candidatesTokenCount: number };
+  };
+
+  return {
+    text: data.candidates[0].content.parts[0].text,
+    provider: "gemini",
+    model,
+    inputTokens: data.usageMetadata?.promptTokenCount,
+    outputTokens: data.usageMetadata?.candidatesTokenCount,
+  };
+}
+
+// ============================================================================
+// Main entry point
+// ============================================================================
+
+/**
+ * Analyze an image with a vision-capable model.
+ * Auto-detects provider from env vars unless options.provider is specified.
+ */
+export async function analyzeImage(
+  imageBase64: string,
+  mediaType: string,
+  prompt: string,
+  options: VisionOptions = {}
+): Promise<VisionResult> {
+  const provider = options.provider ?? detectProvider();
+  if (!provider) {
+    throw new Error(
+      "No AI provider API key found. Set one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GEMINI_API_KEY"
+    );
+  }
+
+  const model = options.model ?? DEFAULT_MODELS[provider];
+  const jsonPrompt =
+    options.jsonMode
+      ? `${prompt}\n\nIMPORTANT: Respond ONLY with valid JSON. No markdown, no code fences, no commentary.`
+      : prompt;
+
+  switch (provider) {
+    case "anthropic":
+      return analyzeWithAnthropic(
+        imageBase64,
+        mediaType,
+        jsonPrompt,
+        model,
+        options
+      );
+    case "openai":
+    case "xai":
+      return analyzeWithOpenAICompat(
+        provider,
+        imageBase64,
+        mediaType,
+        jsonPrompt,
+        model,
+        options
+      );
+    case "gemini":
+      return analyzeWithGemini(imageBase64, mediaType, jsonPrompt, model, options);
+    default: {
+      const _exhaustive: never = provider;
+      throw new Error(`Unknown provider: ${_exhaustive}`);
+    }
+  }
+}

package/skills/skill-academic-journal-matcher/bin/cli.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { homedir } from "os";
+import { join } from "path";
+
+function getDataDir(): string {
+  return process.env.DATA_DIR || join(homedir(), ".skill", "skill-academic-journal-matcher");
+}
+
+const program = new Command();
+
+program
+  .name("skill-academic-journal-matcher")
+  .description("Academic Journal Matcher skill")
+  .version("0.1.0");
+
+program
+  .command("run")
+  .description("Run the skill")
+  .option("-o, --output <path>", "Output directory", join(getDataDir(), "output"))
+  .allowUnknownOption(true)
+  .action(async (options, command) => {
+    try {
+      const args = command.args;
+      process.env.DATA_DIR = process.env.DATA_DIR || getDataDir();
+      await import("../src/index.js");
+    } catch (err) {
+      console.error(`Error: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();