@tanstack/ai-code-mode-skills 0.1.0

package/src/create-skills-system-prompt.ts

@@ -0,0 +1,289 @@
+import { generateSkillTypes } from './generate-skill-types'
+import type { Skill } from './types'
+
+interface CreateSkillsSystemPromptOptions {
+  /**
+   * Skills that were selected for this request
+   */
+  selectedSkills: Array<Skill>
+
+  /**
+   * Total number of skills in the library
+   */
+  totalSkillCount: number
+
+  /**
+   * Whether skills are exposed as direct tools (not just sandbox bindings)
+   * @default true
+   */
+  skillsAsTools?: boolean
+}
+
+/**
+ * Generate example input from a JSON Schema
+ */
+function generateExampleFromSchema(schema: Record<string, unknown>): string {
+  if (schema.type === 'object' && schema.properties) {
+    const props = schema.properties as Record<string, { type: string }>
+    const example: Record<string, unknown> = {}
+
+    for (const [key, value] of Object.entries(props)) {
+      if (value.type === 'string') example[key] = `'example_${key}'`
+      else if (value.type === 'number') example[key] = 0
+      else if (value.type === 'boolean') example[key] = true
+      else if (value.type === 'array') example[key] = []
+      else example[key] = null
+    }
+
+    return JSON.stringify(example).replace(/"/g, '')
+  }
+  return '{}'
+}
+
+/**
+ * Create system prompt documentation for the skill library.
+ * This is appended to the Code Mode system prompt.
+ */
+export function createSkillsSystemPrompt({
+  selectedSkills,
+  totalSkillCount,
+  skillsAsTools = true,
+}: CreateSkillsSystemPromptOptions): string {
+  // No skills in library
+  if (totalSkillCount === 0) {
+    return `## Skill Library
+
+You have access to a skill library for storing reusable code. The library is currently empty.
+
+### Skill Management Tools
+
+- \`search_skills(query, limit?)\` - Search for skills (currently empty)
+- \`get_skill(name)\` - Get full skill details including code
+- \`register_skill(...)\` - Save working code as a reusable skill
+
+When you write useful, reusable code, consider registering it as a skill for future use.
+
+**Important**: Newly registered skills become available as tools on the **next message**, not immediately in the current conversation turn.
+`
+  }
+
+  // No skills selected for this conversation
+  if (selectedSkills.length === 0) {
+    return `## Skill Library
+
+You have access to a persistent skill library with ${totalSkillCount} skill${totalSkillCount === 1 ? '' : 's'}. No skills were pre-loaded for this conversation based on context.
+
+### Skill Management Tools
+
+- \`search_skills(query, limit?)\` - Search for relevant skills
+- \`get_skill(name)\` - Get full skill details including code
+- \`register_skill(...)\` - Save working code as a reusable skill
+
+When you write useful, reusable code, consider registering it as a skill for future use.
+
+**Important**: Newly registered skills become available as tools on the **next message**, not immediately in the current conversation turn.
+`
+  }
+
+  if (skillsAsTools) {
+    // Skills are available as direct tools
+    const skillToolDocs = selectedSkills
+      .map((skill) => {
+        const inputExample = generateExampleFromSchema(skill.inputSchema)
+        const trustBadge =
+          skill.trustLevel === 'trusted'
+            ? '✓ trusted'
+            : skill.trustLevel === 'provisional'
+              ? '◐ provisional'
+              : '○ untrusted'
+
+        return `
+### ${skill.name} [${trustBadge}]
+
+${skill.description}
+
+${skill.usageHints.map((h) => `- ${h}`).join('\n')}
+
+**Input Schema:**
+\`\`\`json
+${JSON.stringify(skill.inputSchema, null, 2)}
+\`\`\`
+
+**Output Schema:**
+\`\`\`json
+${JSON.stringify(skill.outputSchema, null, 2)}
+\`\`\`
+
+**Example:**
+Call the \`${skill.name}\` tool with: ${inputExample}
+`
+      })
+      .join('\n---\n')
+
+    return `## Skill Library
+
+${selectedSkills.length} skill${selectedSkills.length === 1 ? '' : 's'} pre-loaded for this conversation (${totalSkillCount} total in library).
+
+### Available Skill Tools
+
+These skills are available as **direct tools** you can call (marked with [SKILL] in description):
+
+${skillToolDocs}
+
+### Skill Management Tools
+
+- \`search_skills(query, limit?)\` - Find additional skills not pre-loaded
+- \`get_skill(name)\` - Get full details of any skill
+- \`register_skill(...)\` - Save working code as a new skill
+
+### Using Skills
+
+Skills are **regular tools** - call them directly like any other tool. No need to use \`execute_typescript\`.
+
+### Creating New Skills
+
+When you write useful, reusable code with \`execute_typescript\`, register it:
+
+\`\`\`typescript
+// After verifying code works, call the register_skill tool
+register_skill({
+  name: 'compare_npm_packages',
+  description: 'Compare download counts for multiple NPM packages',
+  code: \`
+    const { packages } = input;
+    const results = await Promise.all(
+      packages.map(pkg => external_getNpmDownloads({ package: pkg }))
+    );
+    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))
+      .sort((a, b) => b.downloads - a.downloads);
+  \`,
+  inputSchema: { 
+    type: 'object', 
+    properties: { packages: { type: 'array', items: { type: 'string' } } },
+    required: ['packages']
+  },
+  outputSchema: {
+    type: 'array',
+    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }
+  },
+  usageHints: ['Use when comparing popularity of NPM packages'],
+  dependsOn: [],
+});
+\`\`\`
+
+**Important**: Newly registered skills become available as tools on the **next message**, not immediately in the current conversation turn.
+`
+  }
+
+  // Skills as sandbox bindings (legacy mode)
+  const skillDocs = selectedSkills
+    .map((skill) => {
+      const inputExample = generateExampleFromSchema(skill.inputSchema)
+      const trustBadge =
+        skill.trustLevel === 'trusted'
+          ? '✓ trusted'
+          : skill.trustLevel === 'provisional'
+            ? '◐ provisional'
+            : '○ untrusted'
+
+      return `
+### skill_${skill.name} [${trustBadge}]
+
+${skill.description}
+
+${skill.usageHints.map((h) => `- ${h}`).join('\n')}
+
+**Input Schema:**
+\`\`\`json
+${JSON.stringify(skill.inputSchema, null, 2)}
+\`\`\`
+
+**Output Schema:**
+\`\`\`json
+${JSON.stringify(skill.outputSchema, null, 2)}
+\`\`\`
+
+**Example:**
+\`\`\`typescript
+const result = await skill_${skill.name}(${inputExample});
+\`\`\`
+`
+    })
+    .join('\n---\n')
+
+  // Generate type stubs for selected skills
+  const typeStubs = generateSkillTypes(selectedSkills)
+
+  return `## Skill Library
+
+${selectedSkills.length} skill${selectedSkills.length === 1 ? '' : 's'} pre-loaded for this conversation (${totalSkillCount} total in library).
+
+### Pre-loaded Skills
+
+These are available as \`skill_*\` functions in your TypeScript code:
+
+${skillDocs}
+
+### Type Definitions
+
+\`\`\`typescript
+${typeStubs}
+\`\`\`
+
+### Skill Management Tools
+
+- \`search_skills(query, limit?)\` - Find additional skills not pre-loaded
+- \`get_skill(name)\` - Get full details of any skill
+- \`register_skill(...)\` - Save working code as a new skill
+
+### Using Skills
+
+Skills work just like \`external_*\` functions inside \`execute_typescript\`:
+
+\`\`\`typescript
+// Call a pre-loaded skill
+const stats = await skill_fetch_github_stats({ owner: 'tanstack', repo: 'query' });
+
+// Compose skills with external tools
+const repos = await external_searchRepositories({ query: 'react state' });
+const detailed = await Promise.all(
+  repos.items.slice(0, 5).map(r => 
+    skill_fetch_github_stats({ owner: r.owner.login, repo: r.name })
+  )
+);
+\`\`\`
+
+### Creating New Skills
+
+When you write useful, reusable code, register it:
+
+\`\`\`typescript
+// After verifying code works, call the register_skill tool
+register_skill({
+  name: 'compare_npm_packages',
+  description: 'Compare download counts for multiple NPM packages',
+  code: \`
+    const { packages } = input;
+    const results = await Promise.all(
+      packages.map(pkg => external_getNpmDownloads({ package: pkg }))
+    );
+    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))
+      .sort((a, b) => b.downloads - a.downloads);
+  \`,
+  inputSchema: { 
+    type: 'object', 
+    properties: { packages: { type: 'array', items: { type: 'string' } } },
+    required: ['packages']
+  },
+  outputSchema: {
+    type: 'array',
+    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }
+  },
+  usageHints: ['Use when comparing popularity of NPM packages'],
+  dependsOn: [],
+});
+\`\`\`
+
+**Important**: Newly registered skills become available as tools on the **next message**, not immediately in the current conversation turn.
+`
+}

package/src/generate-skill-types.ts

@@ -0,0 +1,162 @@
+import type { Skill } from './types'
+
+/**
+ * Convert a JSON Schema to a TypeScript type string
+ */
+function schemaToType(schema: Record<string, unknown>): string {
+  if (typeof schema !== 'object') {
+    return 'unknown'
+  }
+
+  const schemaType = schema.type
+
+  // Handle basic types
+  if (schemaType === 'string') return 'string'
+  if (schemaType === 'number' || schemaType === 'integer') return 'number'
+  if (schemaType === 'boolean') return 'boolean'
+  if (schemaType === 'null') return 'null'
+
+  // Handle arrays
+  if (schemaType === 'array') {
+    const items = schema.items as Record<string, unknown> | undefined
+    const itemType = items ? schemaToType(items) : 'unknown'
+    return `Array<${itemType}>`
+  }
+
+  // Handle objects with properties
+  if (schemaType === 'object' && schema.properties) {
+    const properties = schema.properties as Record<
+      string,
+      Record<string, unknown>
+    >
+    const required = new Set(
+      (schema.required as Array<string> | undefined) ?? [],
+    )
+
+    const props = Object.entries(properties)
+      .map(([key, propSchema]) => {
+        const optional = required.has(key) ? '' : '?'
+        const propType = schemaToType(propSchema)
+        // Handle property names that need quoting
+        const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+          ? key
+          : `"${key}"`
+        return `  ${safeName}${optional}: ${propType};`
+      })
+      .join('\n')
+
+    return `{\n${props}\n}`
+  }
+
+  // Handle enums
+  if (schema.enum) {
+    const enumValues = schema.enum as Array<unknown>
+    return enumValues.map((v) => JSON.stringify(v)).join(' | ')
+  }
+
+  // Handle union types (anyOf, oneOf)
+  if (schema.anyOf || schema.oneOf) {
+    const variants = (schema.anyOf || schema.oneOf) as Array<
+      Record<string, unknown>
+    >
+    return variants.map((v) => schemaToType(v)).join(' | ')
+  }
+
+  // Handle type arrays (e.g., ["string", "null"])
+  if (Array.isArray(schemaType)) {
+    return schemaType
+      .map((t) => {
+        if (t === 'string') return 'string'
+        if (t === 'number' || t === 'integer') return 'number'
+        if (t === 'boolean') return 'boolean'
+        if (t === 'null') return 'null'
+        if (t === 'array') return 'Array<unknown>'
+        if (t === 'object') return 'object'
+        return 'unknown'
+      })
+      .join(' | ')
+  }
+
+  // Fallback for unknown schemas
+  return 'unknown'
+}
+
+/**
+ * Capitalize the first letter of a string
+ */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Convert snake_case to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split('_')
+    .map((part) => capitalize(part))
+    .join('')
+}
+
+/**
+ * Generate TypeScript type stubs for skills.
+ * These are included in the system prompt so the LLM knows
+ * the exact type signatures of available skills.
+ */
+export function generateSkillTypes(skills: Array<Skill>): string {
+  const declarations: Array<string> = []
+
+  for (const skill of skills) {
+    const baseName = toPascalCase(skill.name)
+    const inputTypeName = `Skill${baseName}Input`
+    const outputTypeName = `Skill${baseName}Output`
+
+    // Generate input type
+    const inputType = schemaToType(skill.inputSchema)
+    if (
+      skill.inputSchema.type === 'object' &&
+      skill.inputSchema.properties &&
+      Object.keys(skill.inputSchema.properties as object).length > 0
+    ) {
+      declarations.push(`interface ${inputTypeName} ${inputType}`)
+    }
+
+    // Generate output type
+    const outputType = schemaToType(skill.outputSchema)
+    if (
+      skill.outputSchema.type === 'object' &&
+      skill.outputSchema.properties &&
+      Object.keys(skill.outputSchema.properties as object).length > 0
+    ) {
+      declarations.push(`interface ${outputTypeName} ${outputType}`)
+    }
+
+    // Determine type references
+    const inputRef =
+      skill.inputSchema.type === 'object' &&
+      skill.inputSchema.properties &&
+      Object.keys(skill.inputSchema.properties as object).length > 0
+        ? inputTypeName
+        : inputType
+
+    const outputRef =
+      skill.outputSchema.type === 'object' &&
+      skill.outputSchema.properties &&
+      Object.keys(skill.outputSchema.properties as object).length > 0
+        ? outputTypeName
+        : outputType
+
+    // Generate function declaration with JSDoc
+    const hintsDoc = skill.usageHints.map((h) => ` * @hint ${h}`).join('\n')
+
+    declarations.push(
+      `/**
+ * ${skill.description}
+${hintsDoc}
+ */
+declare function skill_${skill.name}(input: ${inputRef}): Promise<${outputRef}>;`,
+    )
+  }
+
+  return declarations.join('\n\n')
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Main entry point
+export {
+  codeModeWithSkills,
+  createCodeModeWithSkillsConfig,
+} from './code-mode-with-skills'
+export type {
+  CodeModeWithSkillsOptions,
+  CodeModeWithSkillsResult,
+} from './code-mode-with-skills'
+
+// Trust strategies
+export {
+  createDefaultTrustStrategy,
+  createAlwaysTrustedStrategy,
+  createRelaxedTrustStrategy,
+  createCustomTrustStrategy,
+} from './trust-strategies'
+export type { TrustStrategy } from './trust-strategies'
+
+// Skill selection
+export { selectRelevantSkills } from './select-relevant-skills'
+
+// Skills to tools (for direct calling)
+export { skillsToTools, skillToTool } from './skills-to-tools'
+export type { SkillToToolOptions } from './skills-to-tools'
+
+// Skills to bindings (for sandbox injection - legacy)
+export { skillsToBindings, skillsToSimpleBindings } from './skills-to-bindings'
+
+// Skill management tools
+export { createSkillManagementTools } from './create-skill-management-tools'
+
+// System prompt generation
+export { createSkillsSystemPrompt } from './create-skills-system-prompt'
+
+// Type generation
+export { generateSkillTypes } from './generate-skill-types'
+
+// Storage implementations
+export * from './storage'
+
+// All types
+export type {
+  Skill,
+  SkillIndexEntry,
+  SkillStorage,
+  SkillsConfig,
+  SkillStats,
+  TrustLevel,
+  SkillBinding,
+} from './types'

package/src/select-relevant-skills.ts

@@ -0,0 +1,136 @@
+import { chat } from '@tanstack/ai'
+import type { AnyTextAdapter, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { Skill, SkillIndexEntry, SkillStorage } from './types'
+
+interface SelectRelevantSkillsOptions {
+  /**
+   * Text adapter for skill selection (should be a cheap/fast model)
+   */
+  adapter: AnyTextAdapter
+
+  /**
+   * Current conversation messages
+   */
+  messages: Array<ModelMessage>
+
+  /**
+   * Skill index (lightweight metadata)
+   */
+  skillIndex: Array<SkillIndexEntry>
+
+  /**
+   * Maximum number of skills to select
+   */
+  maxSkills: number
+
+  /**
+   * Storage to load full skill data
+   */
+  storage: SkillStorage
+}
+
+/**
+ * Use a cheap/fast LLM to select which skills are relevant for the current conversation
+ */
+export async function selectRelevantSkills({
+  adapter,
+  messages,
+  skillIndex,
+  maxSkills,
+  storage,
+}: SelectRelevantSkillsOptions): Promise<Array<Skill>> {
+  // Early exit conditions
+  if (skillIndex.length === 0) return []
+  if (messages.length === 0) return []
+
+  // Build context from recent messages (last 5)
+  const recentMessages = messages.slice(-5)
+  const recentContext = recentMessages
+    .map((m) => {
+      let content: string
+      if (typeof m.content === 'string') {
+        content = m.content
+      } else if (Array.isArray(m.content)) {
+        // Handle content parts (text, images, etc.)
+        content = m.content
+          .map((part: unknown) => {
+            if (typeof part === 'string') return part
+            if (part && typeof part === 'object' && 'text' in part)
+              return (part as { text: string }).text
+            return '[non-text content]'
+          })
+          .join(' ')
+      } else {
+        content = '[complex content]'
+      }
+      return `${m.role}: ${content}`
+    })
+    .join('\n')
+
+  // Build skill catalog for selection prompt
+  const skillCatalog = skillIndex
+    .map((s) => {
+      const hints = s.usageHints.length > 0 ? ` (${s.usageHints[0]})` : ''
+      return `- ${s.name}: ${s.description}${hints}`
+    })
+    .join('\n')
+
+  // Ask cheap model to select relevant skills
+  const selectionPrompt = `Given this conversation context:
+---
+${recentContext}
+---
+
+Which of these skills (if any) would be useful for the next response? Return a JSON array of skill names, max ${maxSkills}. Return [] if none are relevant.
+
+Available skills:
+${skillCatalog}
+
+Respond with only the JSON array, no explanation. Example: ["skill_name_1", "skill_name_2"]`
+
+  try {
+    // Use chat to get the selection
+    const stream = chat({
+      adapter,
+      messages: [
+        {
+          role: 'user',
+          content: selectionPrompt,
+        },
+      ],
+    })
+
+    // Collect the full response
+    let responseText = ''
+    for await (const chunk of stream as AsyncIterable<StreamChunk>) {
+      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+        responseText += chunk.delta
+      }
+    }
+
+    // Parse the JSON response
+    // Handle potential markdown code blocks
+    let jsonText = responseText.trim()
+    if (jsonText.startsWith('```')) {
+      // Remove markdown code block
+      jsonText = jsonText.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '')
+    }
+
+    const selectedNames: Array<string> = JSON.parse(jsonText)
+
+    if (!Array.isArray(selectedNames)) {
+      return []
+    }
+
+    // Load full skill data for selected skills
+    const selectedSkills = await Promise.all(
+      selectedNames.slice(0, maxSkills).map((name) => storage.get(name)),
+    )
+
+    return selectedSkills.filter((s): s is Skill => s !== null)
+  } catch (error) {
+    // If parsing fails or any error occurs, return empty (safe fallback)
+    console.warn('Skill selection failed, returning empty selection:', error)
+    return []
+  }
+}