add initial configuration and provider setup for skill generation

Author: LadyBluenotes

packages/skillgen/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@tanstack/skillgen",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tanstack/ai": "^0.5.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

packages/skillgen/src/config.ts

@@ -0,0 +1,29 @@
+export type SkillgenConfig = {
+  provider?: string
+  model?: string
+  apiKey?: string
+  baseUrl?: string
+  temperature?: number
+  maxTokens?: number
+  seed?: number
+}
+
+const parseNumber = (value?: string): number | undefined => {
+  if (!value) return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+export const readSkillgenConfig = (
+  env: NodeJS.ProcessEnv = process.env,
+): SkillgenConfig => {
+  return {
+    provider: env.SKILLGEN_PROVIDER,
+    model: env.SKILLGEN_MODEL,
+    apiKey: env.SKILLGEN_API_KEY,
+    baseUrl: env.SKILLGEN_BASE_URL,
+    temperature: parseNumber(env.SKILLGEN_TEMPERATURE),
+    maxTokens: parseNumber(env.SKILLGEN_MAX_TOKENS),
+    seed: parseNumber(env.SKILLGEN_SEED),
+  }
+}

packages/skillgen/src/index.ts

@@ -0,0 +1,16 @@
+export { readSkillgenConfig } from './config'
+export { createNoopProvider } from './noop'
+export { createTanstackAiProvider } from './tanstack-ai'
+export { renderSkillMarkdown } from './render'
+export { SkillInputSchema, SkillOutputSchema, SkillTopicSchema } from './schema'
+export type {
+  SkillGenerationInput,
+  SkillJsonOutput,
+  SkillTopic,
+} from './schema'
+export type {
+  SkillGenerationOptions,
+  SkillGenerationResult,
+  SkillGenerationUsage,
+  SkillProvider,
+} from './provider'

packages/skillgen/src/noop.ts

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto'
+import type { SkillGenerationOptions, SkillProvider } from './provider'
+import {
+  SkillInputSchema,
+  SkillOutputSchema,
+  type SkillGenerationInput,
+  type SkillJsonOutput,
+  type SkillTopic,
+} from './schema'
+
+const stableStringify = (value: unknown): string => {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`
+  }
+
+  const record = value as Record<string, unknown>
+  const keys = Object.keys(record).sort()
+  const entries = keys.map(
+    (key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`,
+  )
+  return `{${entries.join(',')}}`
+}
+
+const hashHex = (value: string): string =>
+  createHash('sha256').update(value).digest('hex')
+
+const sliceHex = (hash: string, index: number, size = 8): string =>
+  hash.slice(index * size, index * size + size)
+
+const makeTopics = (hash: string, count: number): SkillTopic[] => {
+  const topics: SkillTopic[] = []
+  for (let i = 0; i < count; i += 1) {
+    const token = sliceHex(hash, i + 3, 6)
+    topics.push({
+      title: `Topic ${i + 1} (${token.slice(0, 4)})`,
+      slug: `topic-${token}`,
+    })
+  }
+  return topics
+}
+
+const makeUsage = (hash: string) => {
+  const inputTokens = parseInt(sliceHex(hash, 0, 4), 16) % 1000
+  const outputTokens = parseInt(sliceHex(hash, 1, 4), 16) % 1000
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+  }
+}
+
+const normalizeOptions = (options?: SkillGenerationOptions) => {
+  if (!options) return undefined
+  const { model, temperature, maxTokens, seed, metadata } = options
+  return { model, temperature, maxTokens, seed, metadata }
+}
+
+const buildOutput = (
+  input: SkillGenerationInput,
+  hash: string,
+): SkillJsonOutput => {
+  const boundaries =
+    input.boundaries && input.boundaries.length > 0
+      ? input.boundaries
+      : [
+          `Avoid assumptions beyond provided inputs (${sliceHex(hash, 2, 6)}).`,
+          `Keep output deterministic (${sliceHex(hash, 3, 6)}).`,
+        ]
+
+  const topics =
+    input.topics && input.topics.length > 0 ? input.topics : makeTopics(hash, 3)
+
+  const output: SkillJsonOutput = {
+    schema: 1,
+    library: input.library,
+    version: input.version,
+    title: `TanStack ${input.library} skill`,
+    summary: `Deterministic summary for ${input.library} (${sliceHex(hash, 0, 6)}).`,
+    boundaries,
+    routing: `Route requests to ${input.library} topics. (${sliceHex(hash, 1, 6)})`,
+    topics,
+  }
+
+  return SkillOutputSchema.parse(output)
+}
+
+export const createNoopProvider = (): SkillProvider => {
+  return {
+    async generateSkillJson(input, options) {
+      const parsedInput = SkillInputSchema.parse(input)
+      const seedData = stableStringify({
+        input: parsedInput,
+        options: normalizeOptions(options),
+      })
+      const hash = hashHex(seedData)
+      const output = buildOutput(parsedInput, hash)
+      return {
+        output,
+        usage: makeUsage(hash),
+        rawMeta: {
+          provider: 'noop',
+          hash,
+        },
+      }
+    },
+  }
+}

packages/skillgen/src/provider.ts

@@ -0,0 +1,29 @@
+import type { SkillGenerationInput, SkillJsonOutput } from './schema'
+
+export type SkillGenerationOptions = {
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  seed?: number
+  metadata?: Record<string, unknown>
+  signal?: AbortSignal
+}
+
+export type SkillGenerationUsage = {
+  inputTokens?: number
+  outputTokens?: number
+  totalTokens?: number
+}
+
+export type SkillGenerationResult = {
+  output: SkillJsonOutput
+  usage?: SkillGenerationUsage
+  rawMeta?: unknown
+}
+
+export interface SkillProvider {
+  generateSkillJson(
+    input: SkillGenerationInput,
+    options?: SkillGenerationOptions,
+  ): Promise<SkillGenerationResult>
+}

packages/skillgen/src/render.ts

@@ -0,0 +1,58 @@
+import type { SkillJsonOutput } from './schema'
+
+export type RenderSkillOptions = {
+  maxTopics?: number
+}
+
+const escapePipes = (value: string): string => value.replaceAll('|', '\\|')
+
+export const renderSkillMarkdown = (
+  skill: SkillJsonOutput,
+  options: RenderSkillOptions = {},
+): string => {
+  const maxTopics = options.maxTopics ?? 250
+  const lines: string[] = []
+
+  lines.push(`# ${skill.title}`)
+  lines.push('')
+  lines.push(`**Version:** \`${skill.version}\``)
+  lines.push('')
+  lines.push('## What this skill is for')
+  lines.push('')
+  lines.push(skill.summary)
+  lines.push('')
+  lines.push('## Boundaries')
+  lines.push('')
+
+  if (skill.boundaries.length === 0) {
+    lines.push('- None.')
+  } else {
+    for (const boundary of skill.boundaries) {
+      lines.push(`- ${boundary}`)
+    }
+  }
+
+  lines.push('')
+  lines.push('## Routing')
+  lines.push('')
+  lines.push(skill.routing)
+  lines.push('')
+  lines.push('| Topic | Slug |')
+  lines.push('| --- | --- |')
+
+  const topics = skill.topics.slice(0, maxTopics)
+  if (topics.length === 0) {
+    lines.push('| (none) | (none) |')
+  } else {
+    for (const topic of topics) {
+      lines.push(`| ${escapePipes(topic.title)} | ${escapePipes(topic.slug)} |`)
+    }
+  }
+
+  if (skill.topics.length > maxTopics) {
+    lines.push('')
+    lines.push('(Index truncated in this view; see JSON output for full list.)')
+  }
+
+  return `${lines.join('\n')}\n`
+}

packages/skillgen/src/schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+export const SkillTopicSchema = z.object({
+  slug: z.string().min(1),
+  title: z.string().min(1),
+  kind: z.string().optional(),
+  relPath: z.string().optional(),
+})
+
+export const SkillInputSchema = z.object({
+  library: z.string().min(1),
+  version: z.string().min(1),
+  goal: z.string().min(1),
+  topics: z.array(SkillTopicSchema).optional(),
+  boundaries: z.array(z.string()).optional(),
+  notes: z.string().optional(),
+})
+
+export const SkillOutputSchema = z.object({
+  schema: z.literal(1),
+  library: z.string().min(1),
+  version: z.string().min(1),
+  title: z.string().min(1),
+  summary: z.string().min(1),
+  boundaries: z.array(z.string()),
+  routing: z.string().min(1),
+  topics: z.array(SkillTopicSchema),
+})
+
+export type SkillTopic = z.infer<typeof SkillTopicSchema>
+export type SkillGenerationInput = z.infer<typeof SkillInputSchema>
+export type SkillJsonOutput = z.infer<typeof SkillOutputSchema>