@tanstack/ai-skills 0.0.0 → 0.1.0

package/skills/ai-skills/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: ai-skills
+description: >
+  Portable Agent Skills (SKILL.md) for TanStack AI with @tanstack/ai-skills.
+  Renders a skill catalog and a load_skill tool via the withSkills middleware so
+  any tool-calling model loads skills on demand, on any provider. Covers the
+  SkillSource interface, inlineSkill/skillDirectory/staticSkills, the aggregate/
+  dedupe/filter/cache combinators, read_skill_resource, and the conformance
+  suite. Use for provider-agnostic runtime skills — NOT hosted provider skills
+  (codeExecutionTool/shellTool), which run in a provider sandbox.
+type: core
+library: tanstack-ai
+library_version: '0.0.0'
+sources:
+  - 'TanStack/ai:docs/skills/agent-skills.md'
+  - 'TanStack/ai:docs/skills/skill-sources.md'
+  - 'TanStack/ai:docs/skills/writing-adapters.md'
+  - 'TanStack/ai:docs/tools/provider-skills.md'
+---
+
+# TanStack AI Skills
+
+> Builds on the `ai-core` skill in `@tanstack/ai`. Package: `@tanstack/ai-skills`.
+
+Portable Agent Skills give a tool-calling model a library of `SKILL.md` skills it
+can load on demand, on any provider, with no server sandbox. This is separate
+from hosted **Provider Skills** (`codeExecutionTool` / `shellTool`), which run in
+the provider's sandbox and are referenced by ID.
+
+## Two skill features, do not confuse them
+
+| Need                                            | Use                                   |
+| ----------------------------------------------- | ------------------------------------- |
+| Model loads SKILL.md at runtime, any provider   | `withSkills` (this package)           |
+| Hosted skill runs in a provider sandbox by ID   | `codeExecutionTool` / `shellTool`     |
+| Teach a coding assistant how to use TanStack AI | Ship a `SKILL.md`, install via Intent |
+
+The portable and hosted paths do not mix in one `chat()` call: `withSkills`
+throws if a `code_execution`/`shell` tool in the same call carries skills.
+
+## Add skills to a chat
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { inlineSkill, withSkills } from '@tanstack/ai-skills'
+
+const pptx = inlineSkill({
+  name: 'pptx-builder',
+  description: 'Build and edit PowerPoint decks with python-pptx.',
+  instructions: '# Building a deck\nUse python-pptx. Edit slides, then save.',
+})
+
+const stream = chat({
+  adapter: anthropicText('claude-sonnet-4-5'),
+  messages,
+  middleware: [withSkills(pptx)],
+})
+```
+
+`withSkills` adds a catalog to the system prompt and a `load_skill` tool whose
+`name` is constrained to your skill names. It renders `<available_skills>` XML
+for Anthropic models and markdown for the rest. Re-loading a skill in the same
+conversation returns a short "already loaded" marker.
+
+## Sources
+
+A `SkillSource` is bytes only (no filesystem assumption), so the middleware runs
+on the edge too.
+
+- `inlineSkill({ name, description, instructions, resources? })` — one skill in
+  code or a DB row. Edge-safe.
+- `skillDirectory(root, { strict? })` — walk a folder for `SKILL.md`. Import from
+  `@tanstack/ai-skills/node` (uses `node:fs`). Strict by default.
+- `staticSkills(catalog)` — build-time bundle via `skillsCatalogPlugin` (Vite).
+  Edge-safe, and `.names` is a typed union.
+
+Combine with `aggregate`, `dedupe`, `filter`, `cache`. `withSkills([a, b])` is
+sugar for `dedupe(aggregate([a, b]))`. A single source is never auto-wrapped, so
+a tenant-scoped source is never cached into a shared bucket.
+
+## Resources
+
+To let the model read a skill's bundled files, pass `createResourceTool(source)`
+in `tools`. `withSkills` detects it and advertises `read_skill_resource`. Paths
+that escape the skill root are rejected.
+
+## Skills that carry code
+
+`withSkills` inventories a skill's `scripts/` in the `load_skill` result but does
+NOT run them (script execution is a later phase). To let a skill run code, pass
+your own execution tool to `chat({ tools })` alongside `withSkills` and write the
+skill so it tells the model to call that tool. `withSkills` composes with any
+tools you provide.
+
+```ts ignore
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const executeShell = toolDefinition({
+  name: 'execute_shell',
+  description: 'Run a shell command and return its stdout.',
+  inputSchema: z.object({ command: z.string() }),
+  outputSchema: z.object({ stdout: z.string() }),
+}).server(async ({ command }) => ({ stdout: await runSomewhere(command) }))
+
+// chat({ tools: [executeShell], middleware: [withSkills(source)] })
+```
+
+The skill supplies the command; your tool supplies the ability to run it. Swap in
+a provider sandbox, a Code Mode isolate, or a remote worker without changing the
+skill. For hosted skills that run in the provider's own sandbox, use
+`codeExecutionTool` / `shellTool` instead (see provider-skills).
+
+## Write a custom source
+
+Implement `SkillSource` (`list` + `load`, optional `revision`/`listResources`/
+`readResource`), then validate it with the shipped conformance suite:
+
+```typescript
+import { runSkillSourceConformance } from '@tanstack/ai-skills/testing'
+
+runSkillSourceConformance(() => myS3Source(fixtures), 's3')
+```
+
+## Entry points
+
+- `@tanstack/ai-skills` — types, `inlineSkill`, combinators, `withSkills`,
+  `createResourceTool`, `validateSkill`, `staticSkills`, `SkillLimitError`.
+- `@tanstack/ai-skills/node` — `skillDirectory`, `skillsCatalogPlugin` (`node:fs`).
+- `@tanstack/ai-skills/testing` — `runSkillSourceConformance`.
+
+## Docs
+
+- Portable Agent Skills: `docs/skills/agent-skills.md`
+- Skill sources: `docs/skills/skill-sources.md`
+- Write a skill source: `docs/skills/writing-adapters.md`
+- Provider (hosted) skills: `docs/tools/provider-skills.md`

package/src/catalog.ts

@@ -0,0 +1,44 @@
+/**
+ * Catalog rendering (spec §4.3). Deterministic order (sort by name) and a fixed
+ * position in the system prompt are prompt-cache requirements, not style. The
+ * shape is per model family because `skills-ref` documents `<available_skills>`
+ * XML as recommended specifically for Anthropic models.
+ */
+import type { ModelFamily, SkillMetadata } from './types'
+
+/** Sort skills into a stable, cache-friendly order. */
+export function sortSkills(skills: Array<SkillMetadata>): Array<SkillMetadata> {
+  return [...skills].sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  )
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/** Render the skill catalog for a model family. Skills are sorted by name. */
+export function renderCatalog(
+  skills: Array<SkillMetadata>,
+  family: ModelFamily,
+): string {
+  const sorted = sortSkills(skills)
+  if (family === 'anthropic') {
+    const entries = sorted
+      .map(
+        (s) =>
+          `  <skill name="${escapeXml(s.name)}">${escapeXml(s.description)}</skill>`,
+      )
+      .join('\n')
+    return `<available_skills>\n${entries}\n</available_skills>`
+  }
+  const entries = sorted
+    .map((s) => `- **${s.name}**: ${s.description}`)
+    .join('\n')
+  return `## Available skills\n\n${entries}`
+}

package/src/combinators.ts

@@ -0,0 +1,224 @@
+/**
+ * Source combinators (spec §3.3). Sources compose in practice: org skills +
+ * project skills + tenant skills. `aggregate` concatenates, `dedupe` resolves
+ * collisions, `filter` hides, `cache` memoizes.
+ */
+import { stableHash } from './util'
+import type { SkillMetadata, SkillScriptRef, SkillSource } from './types'
+
+export type FilterContext = Record<string, unknown>
+export type FilterPredicate = (
+  skill: SkillMetadata,
+  ctx?: FilterContext,
+) => boolean
+
+/** Forward a source's optional `revision`, preserving `undefined` when absent. */
+function forwardRevision(
+  source: SkillSource,
+): (() => Promise<string>) | undefined {
+  const rev = source.revision
+  return rev ? () => rev() : undefined
+}
+
+/** Route a delegating method to the first source that lists `name`. */
+async function ownerOf(
+  sources: Array<SkillSource>,
+  name: string,
+): Promise<SkillSource> {
+  for (const source of sources) {
+    const list = await source.list()
+    if (list.some((s) => s.name === name)) return source
+  }
+  throw new Error(`no source provides a skill named "${name}"`)
+}
+
+async function combinedRevision(
+  sources: Array<SkillSource>,
+): Promise<string | undefined> {
+  const revs = await Promise.all(
+    sources.map((s) => s.revision?.() ?? Promise.resolve(undefined)),
+  )
+  if (revs.some((r) => r === undefined)) return undefined
+  return stableHash(revs.join('|'))
+}
+
+/** Concatenate sources in registration order. No dedupe. */
+export function aggregate(sources: Array<SkillSource>): SkillSource {
+  // Only expose revision() when every child does — a partial revision would
+  // report "unchanged" while an unversioned child mutated underneath.
+  const allVersioned = sources.every((s) => s.revision)
+  return {
+    ...(allVersioned && {
+      revision: async () => (await combinedRevision(sources)) ?? '',
+    }),
+    list: async () => {
+      const lists = await Promise.all(sources.map((s) => s.list()))
+      return lists.flat()
+    },
+    load: async (name) => (await ownerOf(sources, name)).load(name),
+    listResources: async (name) => {
+      const owner = await ownerOf(sources, name)
+      return owner.listResources?.(name) ?? []
+    },
+    readResource: async (name, path) => {
+      const owner = await ownerOf(sources, name)
+      if (!owner.readResource) {
+        throw new Error(`skill "${name}" does not support resources`)
+      }
+      return owner.readResource(name, path)
+    },
+    listScripts: async (name) => {
+      const owner = await ownerOf(sources, name)
+      return (owner.listScripts?.(name) ?? []) as Array<SkillScriptRef>
+    },
+    readScript: async (name, path) => {
+      const owner = await ownerOf(sources, name)
+      if (!owner.readScript) {
+        throw new Error(`skill "${name}" does not support scripts`)
+      }
+      return owner.readScript(name, path)
+    },
+  }
+}
+
+/** First occurrence of a name wins; warns on collision. */
+export function dedupe(
+  source: SkillSource,
+  onCollision: (name: string) => void = (name) =>
+    console.warn(`[ai-skills] duplicate skill "${name}" — first one wins`),
+): SkillSource {
+  return {
+    ...source,
+    revision: forwardRevision(source),
+    list: async () => {
+      const seen = new Set<string>()
+      const out: Array<SkillMetadata> = []
+      for (const skill of await source.list()) {
+        if (seen.has(skill.name)) {
+          onCollision(skill.name)
+          continue
+        }
+        seen.add(skill.name)
+        out.push(skill)
+      }
+      return out
+    },
+  }
+}
+
+/** Hide skills the predicate rejects. Filtered skills never reach the catalog. */
+export function filter(
+  source: SkillSource,
+  predicate: FilterPredicate,
+  ctx?: FilterContext,
+): SkillSource {
+  const list = async () =>
+    (await source.list()).filter((s) => predicate(s, ctx))
+  const assertVisible = async (name: string) => {
+    const skills = await list()
+    if (!skills.some((s) => s.name === name)) {
+      throw new Error(`no skill named "${name}"`)
+    }
+  }
+  return {
+    ...source,
+    revision: forwardRevision(source),
+    list,
+    load: async (name) => {
+      await assertVisible(name)
+      return source.load(name)
+    },
+    listResources: source.listResources
+      ? async (name) => {
+          await assertVisible(name)
+          return source.listResources?.(name) ?? []
+        }
+      : undefined,
+    readResource: source.readResource
+      ? async (name, path) => {
+          await assertVisible(name)
+          const read = source.readResource
+          if (!read) {
+            throw new Error(`skill "${name}" does not support resources`)
+          }
+          return read(name, path)
+        }
+      : undefined,
+    listScripts: source.listScripts
+      ? async (name) => {
+          await assertVisible(name)
+          return (source.listScripts?.(name) ?? []) as Array<SkillScriptRef>
+        }
+      : undefined,
+    readScript: source.readScript
+      ? async (name, path) => {
+          await assertVisible(name)
+          const read = source.readScript
+          if (!read) {
+            throw new Error(`skill "${name}" does not support scripts`)
+          }
+          return read(name, path)
+        }
+      : undefined,
+  }
+}
+
+/**
+ * Memoize `list()`/`load()`. Concurrent `list()` calls share one underlying
+ * fetch. `refreshInterval` (ms) expires the memo; omit for forever.
+ *
+ * Never auto-applied by the middleware — caching a tenant-scoped source in a
+ * shared bucket would replay one tenant's skills for another. Opt in explicitly.
+ */
+export function cache(
+  source: SkillSource,
+  opts: { refreshInterval?: number } = {},
+): SkillSource {
+  let listPromise: Promise<Array<SkillMetadata>> | undefined
+  let listAt = 0
+  const loads = new Map<string, Promise<string>>()
+
+  const now = () => (opts.refreshInterval ? Date.now() : 0)
+  const fresh = () =>
+    opts.refreshInterval === undefined || now() - listAt < opts.refreshInterval
+
+  return {
+    ...source,
+    revision: forwardRevision(source),
+    list: () => {
+      if (!listPromise || !fresh()) {
+        listAt = now()
+        loads.clear()
+        listPromise = source.list().catch((err) => {
+          listPromise = undefined // don't cache failures
+          throw err
+        })
+      }
+      return listPromise
+    },
+    load: (name) => {
+      let p = loads.get(name)
+      if (!p) {
+        p = source.load(name).catch((err) => {
+          loads.delete(name)
+          throw err
+        })
+        loads.set(name, p)
+      }
+      return p
+    },
+  }
+}
+
+/**
+ * Combine the sources handed to the middleware. An array is deduped and
+ * aggregated; a single bare source is used as-is (never auto-wrapped).
+ */
+export function combineSources(
+  sources: SkillSource | Array<SkillSource>,
+): SkillSource {
+  if (!Array.isArray(sources)) return sources
+  const [first] = sources
+  if (sources.length === 1 && first) return first
+  return dedupe(aggregate(sources))
+}

package/src/errors.ts

@@ -0,0 +1,7 @@
+/**
+ * `SkillLimitError` is defined in core `@tanstack/ai` (so the native tool
+ * factories can throw it without depending on this package) and re-exported
+ * here for the portable path.
+ */
+export { SkillLimitError } from '@tanstack/ai'
+export type { SkillLimitErrorInit } from '@tanstack/ai'

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@tanstack/ai-skills` — portable Agent Skills (`SKILL.md`) as a first-class
+ * `chat()` middleware. Edge-safe root export; `skillDirectory` (node:fs) lives
+ * behind the `/node` subpath, the Vite plugin behind `/static`, and the
+ * conformance suite behind `/testing`.
+ */
+export type {
+  SkillSource,
+  SkillMetadata,
+  SkillScriptRef,
+  LoadSkillResult,
+  ModelFamily,
+} from './types'
+export { modelFamilyOf } from './types'
+
+export { parseSkill, stripFrontmatter, SkillParseError } from './parse'
+export type { ParsedSkill, ParseWarning } from './parse'
+
+export { walkSkillDirs, SKILL_FILE, MAX_SKILL_WALK_DEPTH } from './walk'
+export type { DiscoveredSkillDir, WalkEntry, ListDir } from './walk'
+
+export { inlineSkill } from './sources/inline'
+export type { InlineSkillConfig } from './sources/inline'
+
+export { aggregate, dedupe, filter, cache, combineSources } from './combinators'
+export type { FilterContext, FilterPredicate } from './combinators'
+
+export { renderCatalog, sortSkills } from './catalog'
+
+export { withSkills, SKILLS_STATE_EVENT } from './middleware'
+export type { SkillsOptions, SkillsStateEventValue } from './middleware'
+
+export { createLoadSkillTool, ALREADY_LOADED } from './tools/load-skill'
+export {
+  createResourceTool,
+  READ_RESOURCE_TOOL_NAME,
+} from './tools/read-resource'
+
+export { validateSkill } from './validate'
+export type {
+  SkillTarget,
+  SkillValidationIssue,
+  SkillValidationResult,
+} from './validate'
+
+export { SkillLimitError } from './errors'
+export type { SkillLimitErrorInit } from './errors'
+
+export { assertSafeResourcePath, stableHash } from './util'