@tanstack/ai-code-mode-skills 0.1.0

package/dist/esm/storage/memory-storage.js

@@ -0,0 +1,99 @@
+import { createDefaultTrustStrategy } from "../trust-strategies.js";
+function createMemorySkillStorage(optionsOrSkills = []) {
+  const options = Array.isArray(optionsOrSkills) ? { initialSkills: optionsOrSkills } : optionsOrSkills;
+  const { initialSkills = [], trustStrategy = createDefaultTrustStrategy() } = options;
+  const skills = /* @__PURE__ */ new Map();
+  for (const skill of initialSkills) {
+    skills.set(skill.name, skill);
+  }
+  async function loadIndex() {
+    return Array.from(skills.values()).map((skill) => ({
+      id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      usageHints: skill.usageHints,
+      trustLevel: skill.trustLevel
+    }));
+  }
+  async function loadAll() {
+    return Array.from(skills.values());
+  }
+  async function get(name) {
+    return skills.get(name) ?? null;
+  }
+  async function save(skill) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = skills.get(skill.name);
+    const fullSkill = {
+      ...skill,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now
+    };
+    skills.set(skill.name, fullSkill);
+    return fullSkill;
+  }
+  async function deleteSkill(name) {
+    if (!skills.has(name)) {
+      return false;
+    }
+    skills.delete(name);
+    return true;
+  }
+  async function search(query, options2 = {}) {
+    const { limit = 5 } = options2;
+    const queryLower = query.toLowerCase();
+    const terms = queryLower.split(/\s+/);
+    const scored = Array.from(skills.values()).map((skill) => {
+      let score = 0;
+      const searchText = [skill.name, skill.description, ...skill.usageHints].join(" ").toLowerCase();
+      for (const term of terms) {
+        if (searchText.includes(term)) {
+          score += 1;
+        }
+        if (skill.name.toLowerCase().includes(term)) {
+          score += 2;
+        }
+      }
+      return { skill, score };
+    });
+    return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => ({
+      id: s.skill.id,
+      name: s.skill.name,
+      description: s.skill.description,
+      usageHints: s.skill.usageHints,
+      trustLevel: s.skill.trustLevel
+    }));
+  }
+  async function updateStats(name, success) {
+    const skill = skills.get(name);
+    if (!skill) return;
+    const { executions, successRate } = skill.stats;
+    const newExecutions = executions + 1;
+    const newSuccessRate = (successRate * executions + (success ? 1 : 0)) / newExecutions;
+    const newStats = { executions: newExecutions, successRate: newSuccessRate };
+    const newTrustLevel = trustStrategy.calculateTrustLevel(
+      skill.trustLevel,
+      newStats
+    );
+    skills.set(name, {
+      ...skill,
+      stats: newStats,
+      trustLevel: newTrustLevel,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return {
+    loadIndex,
+    loadAll,
+    get,
+    save,
+    delete: deleteSkill,
+    search,
+    updateStats,
+    trustStrategy
+  };
+}
+export {
+  createMemorySkillStorage
+};
+//# sourceMappingURL=memory-storage.js.map

package/dist/esm/storage/memory-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-storage.js","sources":["../../../src/storage/memory-storage.ts"],"sourcesContent":["import { createDefaultTrustStrategy } from '../trust-strategies'\nimport type {\n  Skill,\n  SkillIndexEntry,\n  SkillSearchOptions,\n  SkillStorage,\n} from '../types'\nimport type { TrustStrategy } from '../trust-strategies'\n\nexport interface MemorySkillStorageOptions {\n  /**\n   * Initial skills to populate the storage with\n   */\n  initialSkills?: Array<Skill>\n\n  /**\n   * Trust strategy for determining skill trust levels\n   * @default createDefaultTrustStrategy()\n   */\n  trustStrategy?: TrustStrategy\n}\n\n/**\n * In-memory skill storage for testing and demos\n */\nexport function createMemorySkillStorage(\n  optionsOrSkills: MemorySkillStorageOptions | Array<Skill> = [],\n): SkillStorage {\n  const options = Array.isArray(optionsOrSkills)\n    ? { initialSkills: optionsOrSkills }\n    : optionsOrSkills\n\n  const { initialSkills = [], trustStrategy = createDefaultTrustStrategy() } =\n    options\n\n  // Store skills in a Map for O(1) lookup\n  const skills = new Map<string, Skill>()\n\n  // Initialize with any provided skills\n  for (const skill of initialSkills) {\n    skills.set(skill.name, skill)\n  }\n\n  async function loadIndex(): Promise<Array<SkillIndexEntry>> {\n    return Array.from(skills.values()).map((skill) => ({\n      id: skill.id,\n      name: skill.name,\n      description: skill.description,\n      usageHints: skill.usageHints,\n      trustLevel: skill.trustLevel,\n    }))\n  }\n\n  async function loadAll(): Promise<Array<Skill>> {\n    return Array.from(skills.values())\n  }\n\n  async function get(name: string): Promise<Skill | null> {\n    return skills.get(name) ?? null\n  }\n\n  async function save(\n    skill: Omit<Skill, 'createdAt' | 'updatedAt'>,\n  ): Promise<Skill> {\n    const now = new Date().toISOString()\n    const existing = skills.get(skill.name)\n\n    const fullSkill: Skill = {\n      ...skill,\n      createdAt: existing?.createdAt ?? now,\n      updatedAt: now,\n    }\n\n    skills.set(skill.name, fullSkill)\n    return fullSkill\n  }\n\n  async function deleteSkill(name: string): Promise<boolean> {\n    if (!skills.has(name)) {\n      return false\n    }\n    skills.delete(name)\n    return true\n  }\n\n  async function search(\n    query: string,\n    options: SkillSearchOptions = {},\n  ): Promise<Array<SkillIndexEntry>> {\n    const { limit = 5 } = options\n\n    // Simple text matching\n    const queryLower = query.toLowerCase()\n    const terms = queryLower.split(/\\s+/)\n\n    const scored = Array.from(skills.values()).map((skill) => {\n      let score = 0\n      const searchText = [skill.name, skill.description, ...skill.usageHints]\n        .join(' ')\n        .toLowerCase()\n\n      for (const term of terms) {\n        if (searchText.includes(term)) {\n          score += 1\n        }\n        // Boost exact name matches\n        if (skill.name.toLowerCase().includes(term)) {\n          score += 2\n        }\n      }\n\n      return { skill, score }\n    })\n\n    return scored\n      .filter((s) => s.score > 0)\n      .sort((a, b) => b.score - a.score)\n      .slice(0, limit)\n      .map((s) => ({\n        id: s.skill.id,\n        name: s.skill.name,\n        description: s.skill.description,\n        usageHints: s.skill.usageHints,\n        trustLevel: s.skill.trustLevel,\n      }))\n  }\n\n  async function updateStats(name: string, success: boolean): Promise<void> {\n    const skill = skills.get(name)\n    if (!skill) return\n\n    const { executions, successRate } = skill.stats\n    const newExecutions = executions + 1\n    const newSuccessRate =\n      (successRate * executions + (success ? 1 : 0)) / newExecutions\n\n    const newStats = { executions: newExecutions, successRate: newSuccessRate }\n\n    // Use trust strategy to calculate new trust level\n    const newTrustLevel = trustStrategy.calculateTrustLevel(\n      skill.trustLevel,\n      newStats,\n    )\n\n    skills.set(name, {\n      ...skill,\n      stats: newStats,\n      trustLevel: newTrustLevel,\n      updatedAt: new Date().toISOString(),\n    })\n  }\n\n  return {\n    loadIndex,\n    loadAll,\n    get,\n    save,\n    delete: deleteSkill,\n    search,\n    updateStats,\n    trustStrategy,\n  }\n}\n"],"names":["options"],"mappings":"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"}

package/dist/esm/trust-strategies.d.ts

@@ -0,0 +1,50 @@
+import { SkillStats, TrustLevel } from './types.js';
+/**
+ * Strategy for determining skill trust levels
+ */
+export interface TrustStrategy {
+    /**
+     * Get the initial trust level for a newly created skill
+     */
+    getInitialTrustLevel: () => TrustLevel;
+    /**
+     * Calculate the new trust level based on execution stats
+     */
+    calculateTrustLevel: (currentLevel: TrustLevel, stats: SkillStats) => TrustLevel;
+}
+/**
+ * Default trust strategy - skills must earn trust through successful executions
+ *
+ * - untrusted: New skill (0 executions)
+ * - provisional: 10+ executions with ≥90% success rate
+ * - trusted: 100+ executions with ≥95% success rate
+ */
+export declare function createDefaultTrustStrategy(): TrustStrategy;
+/**
+ * Always trusted strategy - skills are immediately trusted upon creation
+ *
+ * Use this for development/testing or when you trust the LLM's code generation
+ */
+export declare function createAlwaysTrustedStrategy(): TrustStrategy;
+/**
+ * Relaxed trust strategy - faster trust promotion for development
+ *
+ * - untrusted: New skill (0 executions)
+ * - provisional: 3+ executions with ≥80% success rate
+ * - trusted: 10+ executions with ≥90% success rate
+ */
+export declare function createRelaxedTrustStrategy(): TrustStrategy;
+/**
+ * Custom trust strategy with configurable thresholds
+ */
+export declare function createCustomTrustStrategy(config: {
+    initialLevel?: TrustLevel;
+    provisionalThreshold?: {
+        executions: number;
+        successRate: number;
+    };
+    trustedThreshold?: {
+        executions: number;
+        successRate: number;
+    };
+}): TrustStrategy;

package/dist/esm/trust-strategies.js

@@ -0,0 +1,63 @@
+function createDefaultTrustStrategy() {
+  return {
+    getInitialTrustLevel: () => "untrusted",
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats;
+      if (currentLevel === "untrusted" && executions >= 10 && successRate >= 0.9) {
+        return "provisional";
+      }
+      if (currentLevel === "provisional" && executions >= 100 && successRate >= 0.95) {
+        return "trusted";
+      }
+      return currentLevel;
+    }
+  };
+}
+function createAlwaysTrustedStrategy() {
+  return {
+    getInitialTrustLevel: () => "trusted",
+    calculateTrustLevel: () => "trusted"
+  };
+}
+function createRelaxedTrustStrategy() {
+  return {
+    getInitialTrustLevel: () => "untrusted",
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats;
+      if (currentLevel === "untrusted" && executions >= 3 && successRate >= 0.8) {
+        return "provisional";
+      }
+      if (currentLevel === "provisional" && executions >= 10 && successRate >= 0.9) {
+        return "trusted";
+      }
+      return currentLevel;
+    }
+  };
+}
+function createCustomTrustStrategy(config) {
+  const {
+    initialLevel = "untrusted",
+    provisionalThreshold = { executions: 10, successRate: 0.9 },
+    trustedThreshold = { executions: 100, successRate: 0.95 }
+  } = config;
+  return {
+    getInitialTrustLevel: () => initialLevel,
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats;
+      if (currentLevel === "untrusted" && executions >= provisionalThreshold.executions && successRate >= provisionalThreshold.successRate) {
+        return "provisional";
+      }
+      if (currentLevel === "provisional" && executions >= trustedThreshold.executions && successRate >= trustedThreshold.successRate) {
+        return "trusted";
+      }
+      return currentLevel;
+    }
+  };
+}
+export {
+  createAlwaysTrustedStrategy,
+  createCustomTrustStrategy,
+  createDefaultTrustStrategy,
+  createRelaxedTrustStrategy
+};
+//# sourceMappingURL=trust-strategies.js.map

package/dist/esm/trust-strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-strategies.js","sources":["../../src/trust-strategies.ts"],"sourcesContent":["import type { SkillStats, TrustLevel } from './types'\n\n/**\n * Strategy for determining skill trust levels\n */\nexport interface TrustStrategy {\n  /**\n   * Get the initial trust level for a newly created skill\n   */\n  getInitialTrustLevel: () => TrustLevel\n\n  /**\n   * Calculate the new trust level based on execution stats\n   */\n  calculateTrustLevel: (\n    currentLevel: TrustLevel,\n    stats: SkillStats,\n  ) => TrustLevel\n}\n\n/**\n * Default trust strategy - skills must earn trust through successful executions\n *\n * - untrusted: New skill (0 executions)\n * - provisional: 10+ executions with ≥90% success rate\n * - trusted: 100+ executions with ≥95% success rate\n */\nexport function createDefaultTrustStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'untrusted',\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= 10 &&\n        successRate >= 0.9\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= 100 &&\n        successRate >= 0.95\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n\n/**\n * Always trusted strategy - skills are immediately trusted upon creation\n *\n * Use this for development/testing or when you trust the LLM's code generation\n */\nexport function createAlwaysTrustedStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'trusted',\n    calculateTrustLevel: () => 'trusted',\n  }\n}\n\n/**\n * Relaxed trust strategy - faster trust promotion for development\n *\n * - untrusted: New skill (0 executions)\n * - provisional: 3+ executions with ≥80% success rate\n * - trusted: 10+ executions with ≥90% success rate\n */\nexport function createRelaxedTrustStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'untrusted',\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= 3 &&\n        successRate >= 0.8\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= 10 &&\n        successRate >= 0.9\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n\n/**\n * Custom trust strategy with configurable thresholds\n */\nexport function createCustomTrustStrategy(config: {\n  initialLevel?: TrustLevel\n  provisionalThreshold?: { executions: number; successRate: number }\n  trustedThreshold?: { executions: number; successRate: number }\n}): TrustStrategy {\n  const {\n    initialLevel = 'untrusted',\n    provisionalThreshold = { executions: 10, successRate: 0.9 },\n    trustedThreshold = { executions: 100, successRate: 0.95 },\n  } = config\n\n  return {\n    getInitialTrustLevel: () => initialLevel,\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= provisionalThreshold.executions &&\n        successRate >= provisionalThreshold.successRate\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= trustedThreshold.executions &&\n        successRate >= trustedThreshold.successRate\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n"],"names":[],"mappings":"AA2BO,SAAS,6BAA4C;AAC1D,SAAO;AAAA,IACL,sBAAsB,MAAM;AAAA,IAE5B,qBAAqB,CAAC,cAAc,UAAU;AAC5C,YAAM,EAAE,YAAY,YAAA,IAAgB;AAEpC,UACE,iBAAiB,eACjB,cAAc,MACd,eAAe,KACf;AACA,eAAO;AAAA,MACT;AAEA,UACE,iBAAiB,iBACjB,cAAc,OACd,eAAe,MACf;AACA,eAAO;AAAA,MACT;AAEA,aAAO;AAAA,IACT;AAAA,EAAA;AAEJ;AAOO,SAAS,8BAA6C;AAC3D,SAAO;AAAA,IACL,sBAAsB,MAAM;AAAA,IAC5B,qBAAqB,MAAM;AAAA,EAAA;AAE/B;AASO,SAAS,6BAA4C;AAC1D,SAAO;AAAA,IACL,sBAAsB,MAAM;AAAA,IAE5B,qBAAqB,CAAC,cAAc,UAAU;AAC5C,YAAM,EAAE,YAAY,YAAA,IAAgB;AAEpC,UACE,iBAAiB,eACjB,cAAc,KACd,eAAe,KACf;AACA,eAAO;AAAA,MACT;AAEA,UACE,iBAAiB,iBACjB,cAAc,MACd,eAAe,KACf;AACA,eAAO;AAAA,MACT;AAEA,aAAO;AAAA,IACT;AAAA,EAAA;AAEJ;AAKO,SAAS,0BAA0B,QAIxB;AAChB,QAAM;AAAA,IACJ,eAAe;AAAA,IACf,uBAAuB,EAAE,YAAY,IAAI,aAAa,IAAA;AAAA,IACtD,mBAAmB,EAAE,YAAY,KAAK,aAAa,KAAA;AAAA,EAAK,IACtD;AAEJ,SAAO;AAAA,IACL,sBAAsB,MAAM;AAAA,IAE5B,qBAAqB,CAAC,cAAc,UAAU;AAC5C,YAAM,EAAE,YAAY,YAAA,IAAgB;AAEpC,UACE,iBAAiB,eACjB,cAAc,qBAAqB,cACnC,eAAe,qBAAqB,aACpC;AACA,eAAO;AAAA,MACT;AAEA,UACE,iBAAiB,iBACjB,cAAc,iBAAiB,cAC/B,eAAe,iBAAiB,aAChC;AACA,eAAO;AAAA,MACT;AAEA,aAAO;AAAA,IACT;AAAA,EAAA;AAEJ;"}

package/dist/esm/types.d.ts

@@ -0,0 +1,216 @@
+import { AnyTextAdapter, ModelMessage, ToolRegistry } from '@tanstack/ai';
+import { CodeModeToolConfig } from '@tanstack/ai-code-mode';
+import { TrustStrategy } from './trust-strategies.js';
+/**
+ * Trust level for a skill
+ * - untrusted: Newly created, not yet proven
+ * - provisional: Has been successfully executed 10+ times with 90%+ success
+ * - trusted: Has been successfully executed 100+ times with 95%+ success
+ */
+export type TrustLevel = 'untrusted' | 'provisional' | 'trusted';
+/**
+ * Execution statistics for a skill
+ */
+export interface SkillStats {
+    /**
+     * Total number of times this skill has been executed
+     */
+    executions: number;
+    /**
+     * Success rate (0-1) based on execution history
+     */
+    successRate: number;
+}
+/**
+ * A reusable skill that can be executed in the Code Mode sandbox
+ */
+export interface Skill {
+    /**
+     * Unique identifier for the skill
+     */
+    id: string;
+    /**
+     * Unique name in snake_case (e.g., 'fetch_github_stats')
+     * This becomes the function name with skill_ prefix in the sandbox
+     */
+    name: string;
+    /**
+     * Human-readable description of what the skill does
+     */
+    description: string;
+    /**
+     * TypeScript code that implements the skill
+     * The code receives `input` as a variable and can call:
+     * - external_* functions (tools)
+     * - other skill_* functions (skills)
+     * Should return a value
+     */
+    code: string;
+    /**
+     * JSON Schema describing the input parameter
+     */
+    inputSchema: Record<string, unknown>;
+    /**
+     * JSON Schema describing the return value
+     */
+    outputSchema: Record<string, unknown>;
+    /**
+     * Hints about when to use this skill
+     * e.g., "Use when comparing NPM package popularity"
+     */
+    usageHints: Array<string>;
+    /**
+     * Names of other skills this skill depends on/calls
+     */
+    dependsOn: Array<string>;
+    /**
+     * Trust level based on execution history
+     */
+    trustLevel: TrustLevel;
+    /**
+     * Execution statistics
+     */
+    stats: SkillStats;
+    /**
+     * ISO timestamp when the skill was created
+     */
+    createdAt: string;
+    /**
+     * ISO timestamp when the skill was last updated
+     */
+    updatedAt: string;
+}
+/**
+ * Lightweight skill entry for the index (metadata only, no code)
+ * Used for fast loading and skill selection
+ */
+export type SkillIndexEntry = Pick<Skill, 'id' | 'name' | 'description' | 'usageHints' | 'trustLevel'>;
+/**
+ * Options for searching skills
+ */
+export interface SkillSearchOptions {
+    /**
+     * Maximum number of results to return
+     * @default 5
+     */
+    limit?: number;
+}
+/**
+ * Interface for skill storage implementations
+ */
+export interface SkillStorage {
+    /**
+     * Load the skill index (lightweight metadata for all skills)
+     */
+    loadIndex: () => Promise<Array<SkillIndexEntry>>;
+    /**
+     * Load all skills with full details (including code)
+     */
+    loadAll: () => Promise<Array<Skill>>;
+    /**
+     * Get a skill by name
+     */
+    get: (name: string) => Promise<Skill | null>;
+    /**
+     * Save a skill (create or update)
+     */
+    save: (skill: Omit<Skill, 'createdAt' | 'updatedAt'>) => Promise<Skill>;
+    /**
+     * Delete a skill by name
+     */
+    delete: (name: string) => Promise<boolean>;
+    /**
+     * Search for skills by query
+     */
+    search: (query: string, options?: SkillSearchOptions) => Promise<Array<SkillIndexEntry>>;
+    /**
+     * Update execution statistics for a skill
+     */
+    updateStats: (name: string, success: boolean) => Promise<void>;
+    /**
+     * Trust strategy used by this storage (optional, for creating new skills)
+     */
+    trustStrategy?: TrustStrategy;
+}
+/**
+ * Configuration for the skills system
+ */
+export interface SkillsConfig {
+    /**
+     * Storage implementation for skills
+     */
+    storage: SkillStorage;
+    /**
+     * Maximum number of skills to load into context per request
+     * @default 5
+     */
+    maxSkillsInContext?: number;
+    /**
+     * Trust strategy for determining skill trust levels
+     * @default createDefaultTrustStrategy()
+     */
+    trustStrategy?: TrustStrategy;
+}
+/**
+ * Options for codeModeWithSkills
+ */
+export interface CodeModeWithSkillsOptions {
+    /**
+     * Code Mode tool configuration (driver, tools, timeout, memoryLimit)
+     */
+    config: CodeModeToolConfig;
+    /**
+     * Text adapter for skill selection (should be a cheap/fast model)
+     */
+    adapter: AnyTextAdapter;
+    /**
+     * Skills configuration
+     */
+    skills: SkillsConfig;
+    /**
+     * Current conversation messages (used for context-aware skill selection)
+     */
+    messages: Array<ModelMessage>;
+    /**
+     * Whether to include skills as direct tools (not just sandbox bindings).
+     * When true, skills become first-class tools the LLM can call directly.
+     * @default true
+     */
+    skillsAsTools?: boolean;
+}
+/**
+ * Result from codeModeWithSkills
+ */
+export interface CodeModeWithSkillsResult {
+    /**
+     * Tool registry for dynamic tool management.
+     * Pass this to chat() via the toolRegistry option.
+     * Skills registered mid-stream will be added to this registry.
+     */
+    toolsRegistry: ToolRegistry;
+    /**
+     * System prompt documenting available skills and external functions
+     */
+    systemPrompt: string;
+    /**
+     * Skills that were selected for this request
+     */
+    selectedSkills: Array<Skill>;
+}
+/**
+ * A skill transformed into a format suitable for sandbox injection
+ */
+export interface SkillBinding {
+    /**
+     * Function name with skill_ prefix
+     */
+    name: string;
+    /**
+     * The skill this binding wraps
+     */
+    skill: Skill;
+    /**
+     * Execute function that runs the skill code
+     */
+    execute: (input: unknown) => Promise<unknown>;
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@tanstack/ai-code-mode-skills",
+  "version": "0.1.0",
+  "description": "Persistent skill library for TanStack AI Code Mode - LLM-created reusable code snippets",
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-code-mode-skills"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./storage": {
+      "types": "./dist/esm/storage/index.d.ts",
+      "import": "./dist/esm/storage/index.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:cli": "tsx test-cli/cli.ts",
+    "test:cli:run": "tsx test-cli/cli.ts run",
+    "test:cli:run:all": "tsx test-cli/cli.ts run --adapters openai,anthropic,gemini",
+    "test:cli:list": "tsx test-cli/cli.ts list",
+    "test:cli:simulated": "tsx test-cli/cli.ts simulated",
+    "test:cli:registry": "tsx test-cli/cli.ts registry",
+    "test:cli:live": "tsx test-cli/cli.ts live",
+    "test:cli:structured": "tsx test-cli/cli.ts structured"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "code-mode",
+    "skills",
+    "llm",
+    "sandbox"
+  ],
+  "dependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-code-mode": "workspace:*"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-code-mode": "workspace:*",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/ai-anthropic": "workspace:*",
+    "@tanstack/ai-gemini": "workspace:*",
+    "@tanstack/ai-isolate-node": "workspace:*",
+    "@tanstack/ai-openai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "commander": "^13.1.0",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.21.0",
+    "zod": "^4.2.0"
+  }
+}