@tanstack/ai-skills 0.0.0 → 0.1.0

package/src/parse.ts

@@ -0,0 +1,247 @@
+/**
+ * Lenient `SKILL.md` frontmatter parsing (spec §7).
+ *
+ * Other clients emit malformed frontmatter — most commonly unquoted colons in
+ * descriptions — so the default is lenient. We hand-roll a tiny parser rather
+ * than pull in a YAML dependency: SKILL.md frontmatter is a flat key/value
+ * block (plus block scalars for `description` and simple lists for
+ * `allowedTools`), and taking `value = rest-of-line-after-first-colon` handles
+ * the unquoted-colon case in a single pass — no quote-and-retry needed.
+ *
+ * | Condition            | Behavior                        |
+ * |----------------------|---------------------------------|
+ * | name/dir mismatch    | warn, load                      |
+ * | name over 64 chars   | warn, load                      |
+ * | invalid name chars   | warn, load                      |
+ * | missing `description`| throw (caller skips)            |
+ * | no frontmatter       | throw (caller skips)            |
+ *
+ * `strict: true` promotes every warning to a thrown error.
+ */
+import type { SkillMetadata } from './types'
+
+export interface ParseWarning {
+  code: 'name-dir-mismatch' | 'name-too-long' | 'name-invalid-chars'
+  message: string
+}
+
+export interface ParsedSkill {
+  metadata: SkillMetadata
+  /** frontmatter stripped. */
+  body: string
+  warnings: Array<ParseWarning>
+}
+
+export class SkillParseError extends Error {
+  override name = 'SkillParseError'
+}
+
+const NAME_RE = /^[a-z0-9-]+$/
+
+/** Split leading `---` frontmatter from the body. Returns null if absent. */
+function splitFrontmatter(
+  raw: string,
+): { frontmatter: string; body: string } | null {
+  // Tolerate a BOM and leading blank lines before the opening fence.
+  const text = raw.replace(/^/, '')
+  const match = /^\s*---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/.exec(
+    text,
+  )
+  if (!match) return null
+  return { frontmatter: match[1] ?? '', body: match[2] ?? '' }
+}
+
+/** Parse the flat frontmatter block into raw string/list/map values. */
+function parseBlock(frontmatter: string): Record<string, unknown> {
+  const lines = frontmatter.split(/\r?\n/)
+  const out: Record<string, unknown> = {}
+  let i = 0
+
+  const indentOf = (s: string) => s.length - s.trimStart().length
+
+  while (i < lines.length) {
+    const line = lines[i]
+    if (line === undefined) break
+    if (line.trim() === '' || line.trimStart().startsWith('#')) {
+      i++
+      continue
+    }
+    // Top-level keys are unindented.
+    if (indentOf(line) > 0) {
+      i++
+      continue
+    }
+    const colon = line.indexOf(':')
+    if (colon === -1) {
+      i++
+      continue
+    }
+    const key = line.slice(0, colon).trim()
+    const value = line.slice(colon + 1).trim()
+
+    // Block scalar: `>` (folded) or `|` (literal), with optional chomp/indent.
+    if (value === '>' || value === '|' || /^[>|][+-]?\d*$/.test(value)) {
+      const folded = value.startsWith('>')
+      const collected: Array<string> = []
+      i++
+      while (i < lines.length) {
+        const next = lines[i]
+        if (next === undefined) break
+        if (next.trim() !== '' && indentOf(next) === 0) break
+        collected.push(next)
+        i++
+      }
+      // Strip the common leading indentation of the block.
+      const nonEmpty = collected.filter((l) => l.trim() !== '')
+      const minIndent = nonEmpty.length
+        ? Math.min(...nonEmpty.map(indentOf))
+        : 0
+      const stripped = collected.map((l) => l.slice(minIndent))
+      out[key] = folded
+        ? stripped.join(' ').replace(/\s+/g, ' ').trim()
+        : stripped.join('\n').trim()
+      continue
+    }
+
+    // Empty value → indented children: a block list (`- x`) or a nested map
+    // (`k: v`), one level deep.
+    if (value === '') {
+      const items: Array<string> = []
+      const map: Record<string, string> = {}
+      let j = i + 1
+      while (j < lines.length) {
+        const next = lines[j]
+        if (next === undefined) break
+        if (next.trim() === '') {
+          j++
+          continue
+        }
+        if (indentOf(next) === 0) break
+        const t = next.trim()
+        if (t.startsWith('- ')) {
+          items.push(unquote(t.slice(2).trim()))
+        } else {
+          const c = t.indexOf(':')
+          if (c === -1) break
+          map[t.slice(0, c).trim()] = unquote(t.slice(c + 1).trim())
+        }
+        j++
+      }
+      if (items.length) out[key] = items
+      else if (Object.keys(map).length) out[key] = map
+      else out[key] = ''
+      i = Math.max(j, i + 1)
+      continue
+    }
+
+    // Inline list `[a, b]`.
+    if (value.startsWith('[') && value.endsWith(']')) {
+      out[key] = value
+        .slice(1, -1)
+        .split(',')
+        .map((s) => unquote(s.trim()))
+        .filter((s) => s !== '')
+      i++
+      continue
+    }
+
+    out[key] = unquote(value)
+    i++
+  }
+  return out
+}
+
+function unquote(s: string): string {
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    return s.slice(1, -1)
+  }
+  return s
+}
+
+function asStringMap(value: unknown): Record<string, string> | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === 'string') out[k] = v
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+/**
+ * Parse a `SKILL.md`. Throws {@link SkillParseError} for cases the spec says to
+ * skip (no frontmatter, missing description). Non-fatal issues are returned as
+ * `warnings`; `strict` turns them into throws.
+ */
+export function parseSkill(
+  raw: string,
+  opts: { dirName?: string; strict?: boolean } = {},
+): ParsedSkill {
+  const split = splitFrontmatter(raw)
+  if (!split) {
+    throw new SkillParseError('SKILL.md has no frontmatter block')
+  }
+  const block = parseBlock(split.frontmatter)
+
+  const name = typeof block.name === 'string' ? block.name : undefined
+  const description =
+    typeof block.description === 'string' ? block.description : undefined
+
+  if (!description) {
+    throw new SkillParseError('SKILL.md is missing a `description`')
+  }
+
+  const warnings: Array<ParseWarning> = []
+  const effectiveName = name ?? opts.dirName ?? ''
+
+  if (name && opts.dirName && name !== opts.dirName) {
+    warnings.push({
+      code: 'name-dir-mismatch',
+      message: `skill name "${name}" does not match directory "${opts.dirName}"`,
+    })
+  }
+  if (effectiveName.length > 64) {
+    warnings.push({
+      code: 'name-too-long',
+      message: `skill name "${effectiveName}" exceeds 64 characters`,
+    })
+  }
+  if (effectiveName && !NAME_RE.test(effectiveName)) {
+    warnings.push({
+      code: 'name-invalid-chars',
+      message: `skill name "${effectiveName}" contains characters outside [a-z0-9-]`,
+    })
+  }
+
+  if (opts.strict && warnings.length) {
+    throw new SkillParseError(warnings.map((w) => w.message).join('; '))
+  }
+
+  const metadata: SkillMetadata = {
+    name: effectiveName,
+    description,
+    ...(typeof block.license === 'string' && { license: block.license }),
+    ...(typeof block.compatibility === 'string' && {
+      compatibility: block.compatibility,
+    }),
+    ...(Array.isArray(block.allowedTools) && {
+      allowedTools: block.allowedTools.filter(
+        (t): t is string => typeof t === 'string',
+      ),
+    }),
+    ...((): { metadata?: Record<string, string> } => {
+      const m = asStringMap(block.metadata)
+      return m ? { metadata: m } : {}
+    })(),
+  }
+
+  return { metadata, body: split.body.trim(), warnings }
+}
+
+/** Strip the frontmatter block, returning just the body. */
+export function stripFrontmatter(raw: string): string {
+  const split = splitFrontmatter(raw)
+  return split ? split.body.trim() : raw.trim()
+}

package/src/sources/inline.ts

@@ -0,0 +1,66 @@
+/**
+ * `inlineSkill` — an edge-safe {@link SkillSource} for a single skill defined
+ * next to app code, in a DB row, or per-session/per-tenant. Resource values may
+ * be thunks, evaluated at read time.
+ */
+import { stableHash } from '../util'
+import { validateSkill } from '../validate'
+import type { SkillMetadata, SkillSource } from '../types'
+
+export interface InlineSkillConfig {
+  name: string
+  description: string
+  instructions: string
+  resources?: Record<string, string | (() => string | Promise<string>)>
+  compatibility?: string
+}
+
+export function inlineSkill(config: InlineSkillConfig): SkillSource {
+  const metadata: SkillMetadata = {
+    name: config.name,
+    description: config.description,
+    ...(config.compatibility && { compatibility: config.compatibility }),
+  }
+  const lint = validateSkill(metadata)
+  if (!lint.ok) {
+    throw new Error(
+      `inlineSkill "${config.name}": ${lint.issues.map((i) => i.message).join('; ')}`,
+    )
+  }
+  const resourcePaths = Object.keys(config.resources ?? {})
+  const revision = stableHash(
+    JSON.stringify({
+      metadata,
+      instructions: config.instructions,
+      resources: resourcePaths,
+    }),
+  )
+
+  const assertName = (name: string) => {
+    if (name !== config.name) {
+      throw new Error(`inlineSkill has no skill named "${name}"`)
+    }
+  }
+
+  return {
+    revision: () => Promise.resolve(revision),
+    list: () => Promise.resolve([metadata]),
+    // Async so an unknown-name throw surfaces as a rejected promise.
+    load: async (name) => {
+      assertName(name)
+      return config.instructions
+    },
+    listResources: async (name) => {
+      assertName(name)
+      return resourcePaths
+    },
+    readResource: async (name, path) => {
+      assertName(name)
+      const value = config.resources?.[path]
+      if (value === undefined) {
+        throw new Error(`skill "${name}" has no resource "${path}"`)
+      }
+      return typeof value === 'function' ? await value() : value
+    },
+  }
+}

package/src/static/index.ts

@@ -0,0 +1,64 @@
+/**
+ * `staticSkills` — wrap a build-time-generated catalog as a {@link SkillSource}.
+ *
+ * Edge-safe: this file imports no `node:*` modules. The Vite plugin that GLOBS
+ * `skills/**​/SKILL.md` and emits the catalog lives in `@tanstack/ai-skills/node`
+ * (it needs `node:fs`); the emitted catalog is plain data consumed here.
+ *
+ * The generated catalog is `as const`, so `T` is the literal union of skill
+ * names — which flows into `load_skill`'s enum, the constraint the spec
+ * recommends, obtained at build time rather than runtime.
+ */
+import type { SkillMetadata, SkillSource } from '../types'
+
+export interface GeneratedSkill<T extends string = string> {
+  name: T
+  description: string
+  /** raw SKILL.md body, frontmatter stripped at generation time. */
+  body: string
+  compatibility?: string
+  /** embedded resource files, path → utf8 contents. */
+  resources?: Record<string, string>
+}
+
+export interface GeneratedCatalog<T extends string = string> {
+  revision: string
+  skills: ReadonlyArray<GeneratedSkill<T>>
+}
+
+export function staticSkills<T extends string>(
+  catalog: GeneratedCatalog<T>,
+): SkillSource & { names: ReadonlyArray<T> } {
+  const byName = new Map(catalog.skills.map((s) => [s.name, s]))
+  const get = (name: string): GeneratedSkill<T> => {
+    const s = byName.get(name as T)
+    if (!s) throw new Error(`static catalog has no skill named "${name}"`)
+    return s
+  }
+
+  return {
+    names: catalog.skills.map((s) => s.name),
+    revision: () => Promise.resolve(catalog.revision),
+    list: () =>
+      Promise.resolve(
+        catalog.skills.map(
+          (s): SkillMetadata => ({
+            name: s.name,
+            description: s.description,
+            ...(s.compatibility && { compatibility: s.compatibility }),
+          }),
+        ),
+      ),
+    // Methods are async so a missing-skill throw surfaces as a rejected
+    // promise (what callers `await`), not a synchronous throw.
+    load: async (name) => get(name).body,
+    listResources: async (name) => Object.keys(get(name).resources ?? {}),
+    readResource: async (name, path) => {
+      const value = get(name).resources?.[path]
+      if (value === undefined) {
+        throw new Error(`skill "${name}" has no resource "${path}"`)
+      }
+      return value
+    },
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,92 @@
+/**
+ * `runSkillSourceConformance` — the real deliverable for third-party adapters.
+ * Since adapter code is frequently LLM-generated, this suite (not prose) is what
+ * makes a new `SkillSource` safe to ship.
+ *
+ * The factory must return a source seeded with this fixed fixture contract:
+ *
+ *   - skill `alpha`: description non-empty; resource `references/note.md` whose
+ *     contents are exactly `hello`; script `scripts/run.py` whose bytes decode
+ *     to `print(1)` (only if the source supports scripts).
+ *   - skill `beta`: description non-empty; no resources required.
+ *
+ * Sources that cannot represent a tier (resources/scripts) simply omit the
+ * corresponding methods — those cases are skipped, not failed.
+ */
+import { describe, expect, it } from 'vitest'
+import type { SkillSource } from '../types'
+
+const dec = (v: string | Uint8Array) =>
+  typeof v === 'string' ? v : new TextDecoder().decode(v)
+
+export function runSkillSourceConformance(
+  factory: () => SkillSource | Promise<SkillSource>,
+  label = 'SkillSource',
+): void {
+  describe(`conformance: ${label}`, () => {
+    it('lists skills with a name and description', async () => {
+      const source = await factory()
+      const skills = await source.list()
+      const names = skills.map((s) => s.name)
+      expect(names).toContain('alpha')
+      expect(names).toContain('beta')
+      for (const s of skills) {
+        expect(s.name).toBeTruthy()
+        expect(s.description).toBeTruthy()
+      }
+    })
+
+    it('loads a known skill body', async () => {
+      const source = await factory()
+      const body = await source.load('alpha')
+      expect(typeof body).toBe('string')
+      expect(body.length).toBeGreaterThan(0)
+    })
+
+    it('throws (not returns empty) for a missing skill name', async () => {
+      const source = await factory()
+      await expect(source.load('does-not-exist')).rejects.toThrow()
+    })
+
+    it('has a stable revision across identical content', async () => {
+      const source = await factory()
+      const rev = source.revision
+      if (!rev) return
+      const a = await rev()
+      const b = await rev()
+      expect(a).toBe(b)
+      const other = await factory()
+      if (other.revision) expect(await other.revision()).toBe(a)
+    })
+
+    it('serves concurrent list() consistently', async () => {
+      const source = await factory()
+      const [a, b] = await Promise.all([source.list(), source.list()])
+      expect(a.map((s) => s.name).sort()).toEqual(b.map((s) => s.name).sort())
+    })
+
+    it('reads a bundled resource and rejects path traversal', async () => {
+      const source = await factory()
+      const { listResources, readResource } = source
+      if (!listResources || !readResource) return
+      const resources = await listResources('alpha')
+      expect(resources).toContain('references/note.md')
+      const value = await readResource('alpha', 'references/note.md')
+      // trimEnd: a file-backed source keeps the fixture's trailing newline (formatters add one); the payload is what matters.
+      expect(dec(value).trimEnd()).toBe('hello')
+      await expect(readResource('alpha', '../../etc/passwd')).rejects.toThrow()
+    })
+
+    it('returns script bytes correctly', async () => {
+      const source = await factory()
+      if (!source.listScripts || !source.readScript) return
+      const scripts = await source.listScripts('alpha')
+      const ref = scripts.find((s) => s.path === 'scripts/run.py')
+      if (!ref) return
+      expect(ref.executable).toBe(false)
+      const bytes = await source.readScript('alpha', 'scripts/run.py')
+      expect(bytes).toBeInstanceOf(Uint8Array)
+      expect(dec(bytes)).toContain('print(1)')
+    })
+  })
+}

package/src/tools/load-skill.ts

@@ -0,0 +1,96 @@
+/**
+ * `load_skill` — activates a skill by name and returns its (frontmatter-stripped)
+ * body plus a resource/script inventory. Result shape is frozen in phase 1;
+ * changing it later would churn every eval, snapshot, and devtools panel.
+ */
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import { stripFrontmatter } from '../parse'
+import type { Tool } from '@tanstack/ai'
+import type {
+  LoadSkillResult,
+  SkillMetadata,
+  SkillScriptRef,
+  SkillSource,
+} from '../types'
+
+export const ALREADY_LOADED =
+  '(already loaded earlier in this conversation — reuse the prior content)'
+
+const scriptSchema = z.object({
+  path: z.string(),
+  executable: z.literal(false),
+  reason: z.string().optional(),
+})
+
+const resultSchema = z.object({
+  skill: z.string(),
+  content: z.string(),
+  resources: z.array(z.string()),
+  scripts: z.array(scriptSchema),
+  compatibility: z.string().optional(),
+})
+
+export interface LoadSkillDeps {
+  source: SkillSource
+  skills: Array<SkillMetadata>
+  /** per-conversation activation set (dedupe). */
+  activated: Set<string>
+  requireApproval?: boolean
+}
+
+export function createLoadSkillTool(deps: LoadSkillDeps): Tool {
+  const names = deps.skills.map((s) => s.name)
+  const nameEnum = z.enum(names as [string, ...Array<string>])
+  const byName = new Map(deps.skills.map((s) => [s.name, s]))
+
+  const handler = async ({
+    name,
+  }: {
+    name: string
+  }): Promise<LoadSkillResult> => {
+    if (deps.activated.has(name)) {
+      return {
+        skill: name,
+        content: ALREADY_LOADED,
+        resources: [],
+        scripts: [],
+      }
+    }
+    const raw = await deps.source.load(name)
+    const resources = (await deps.source.listResources?.(name)) ?? []
+    const scripts = ((await deps.source.listScripts?.(name)) ??
+      []) as Array<SkillScriptRef>
+    deps.activated.add(name)
+    const compatibility = byName.get(name)?.compatibility
+    return {
+      skill: name,
+      content: stripFrontmatter(raw),
+      resources,
+      scripts,
+      ...(compatibility && { compatibility }),
+    }
+  }
+
+  const description =
+    'Activate an available skill by name. Returns its full instructions plus ' +
+    'a list of any bundled resources and scripts.'
+  const inputSchema = z.object({ name: nameEnum })
+
+  if (deps.requireApproval) {
+    return toolDefinition({
+      name: 'load_skill',
+      description,
+      inputSchema,
+      outputSchema: resultSchema,
+      needsApproval: true,
+      approvalSchema: z.object({ approve: z.boolean() }),
+    }).server(handler)
+  }
+  return toolDefinition({
+    name: 'load_skill',
+    description,
+    inputSchema,
+    outputSchema: resultSchema,
+  }).server(handler)
+}

package/src/tools/read-resource.ts

@@ -0,0 +1,64 @@
+/**
+ * `read_skill_resource` — reads a bundled resource (references/ or assets/) of a
+ * skill. Shipped but NOT auto-registered: pass it explicitly in `tools`, and
+ * `withSkills` phrases activation instructions based on its presence. This keeps
+ * DB/S3/inline sources' resources reachable — they have bytes but no file, so a
+ * caller-supplied file-read tool would never see them.
+ */
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import { assertSafeResourcePath } from '../util'
+import type { Tool } from '@tanstack/ai'
+import type { SkillSource } from '../types'
+
+export const READ_RESOURCE_TOOL_NAME = 'read_skill_resource'
+
+function toBase64(bytes: Uint8Array): string {
+  // ponytail: Buffer exists on node + workers; avoids a browser-only path we
+  // don't need for a server-side resource read.
+  return Buffer.from(bytes).toString('base64')
+}
+
+export function createResourceTool(source: SkillSource): Tool {
+  return toolDefinition({
+    name: READ_RESOURCE_TOOL_NAME,
+    description:
+      'Read a bundled resource file (from references/ or assets/) of an ' +
+      'activated skill, by its path relative to the skill root.',
+    inputSchema: z.object({
+      skill: z.string(),
+      path: z.string(),
+    }),
+    outputSchema: z.object({
+      skill: z.string(),
+      path: z.string(),
+      content: z.string(),
+      encoding: z.enum(['utf8', 'base64']),
+    }),
+  }).server(async ({ skill, path }) => {
+    assertSafeResourcePath(path)
+    const listed = await source.list()
+    if (!listed.some((s) => s.name === skill)) {
+      throw new Error(`no skill named "${skill}"`)
+    }
+    if (source.listResources) {
+      const allowed = await source.listResources(skill)
+      if (!allowed.includes(path)) {
+        throw new Error(`skill "${skill}" has no resource "${path}"`)
+      }
+    }
+    if (!source.readResource) {
+      throw new Error('this skill source does not support resources')
+    }
+    const value = await source.readResource(skill, path)
+    if (typeof value === 'string') {
+      return { skill, path, content: value, encoding: 'utf8' as const }
+    }
+    return {
+      skill,
+      path,
+      content: toBase64(value),
+      encoding: 'base64' as const,
+    }
+  })
+}