@tanstack/ai-skills 0.0.0 → 0.1.1

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Core types for portable Agent Skills.
+ *
+ * `SkillSource` is the central abstraction: bytes only, no filesystem
+ * assumption. A source that exposed a `path` would couple future script
+ * execution to fs-backed sources and permanently exclude S3/DB/registry
+ * sources — so there is deliberately no `path` field, ever. Path resolution
+ * is a `skillDirectory`-only concern.
+ */
+
+/** Parsed `SKILL.md` frontmatter. */
+export interface SkillMetadata {
+  /** spec-validated: ≤64 chars, `[a-z0-9-]`. */
+  name: string
+  /** ≤1024 chars. */
+  description: string
+  license?: string
+  /** ≤500 chars, free text. */
+  compatibility?: string
+  metadata?: Record<string, string>
+  /** experimental in spec; parsed, not enforced. */
+  allowedTools?: Array<string>
+}
+
+/**
+ * A script referenced by a skill. Inventoried in phase 1, executed in phase 2.
+ * `executable` flips to `true` and `reason` is dropped in phase 2.
+ */
+export interface SkillScriptRef {
+  /** relative to skill root, e.g. `scripts/extract.py`. */
+  path: string
+  executable: false
+  reason?: 'no-runtime'
+}
+
+/** A source of skills. Bytes only — no filesystem assumption. */
+export interface SkillSource {
+  /**
+   * Stable identity for the current content. `cache()` does not read this
+   * (it is time-based, and opt-in). Callers and custom combinators can use it
+   * as a catalog cache key. `withSkills` lists once per `chat()` call.
+   */
+  revision?: () => Promise<string>
+
+  /** Tier 1. Called once per `chat()` by `withSkills` setup. */
+  list: () => Promise<Array<SkillMetadata>>
+
+  /** Tier 2. Raw SKILL.md including frontmatter. Core strips it. */
+  load: (name: string) => Promise<string>
+
+  /** Tier 3a. references/ and assets/ paths, relative to skill root. */
+  listResources?: (name: string) => Promise<Array<string>>
+  readResource?: (name: string, path: string) => Promise<string | Uint8Array>
+
+  /** Tier 3b. Inventoried in phase 1, executed in phase 2. */
+  listScripts?: (name: string) => Promise<Array<SkillScriptRef>>
+  readScript?: (name: string, path: string) => Promise<Uint8Array>
+}
+
+/**
+ * Model family, derived from the middleware context's `provider` string. The
+ * codebase has no `ModelFamily` type of its own — `ctx.provider` is a plain
+ * string sourced from `adapter.name`. This is the single seam the catalog
+ * renderer keys on.
+ */
+export type ModelFamily = 'anthropic' | 'openai' | 'gemini' | 'other'
+
+/** Map a provider name (`ctx.provider`) to its {@link ModelFamily}. */
+export function modelFamilyOf(provider: string): ModelFamily {
+  const p = provider.toLowerCase()
+  if (p.includes('anthropic') || p.includes('claude')) return 'anthropic'
+  if (p.includes('openai') || p.includes('gpt')) return 'openai'
+  if (p.includes('gemini') || p.includes('google')) return 'gemini'
+  return 'other'
+}
+
+/** Result of activating a skill via `load_skill`. Shape frozen in phase 1. */
+export interface LoadSkillResult {
+  skill: string
+  /** frontmatter stripped. */
+  content: string
+  resources: Array<string>
+  /** `[]` or `executable:false` entries in phase 1. */
+  scripts: Array<SkillScriptRef>
+  compatibility?: string
+}

package/src/util.ts

@@ -0,0 +1,28 @@
+/**
+ * Reject a resource/script path that escapes its skill root. Pure string check
+ * (edge-safe, no `node:path`): no absolute paths, no `..` segments, no
+ * backslashes. Enforced here so both the resource tool and `skillDirectory`
+ * share one guard and the conformance suite can pin it.
+ */
+export function assertSafeResourcePath(path: string): void {
+  const normalized = path.replace(/\\/g, '/')
+  const bad =
+    normalized.startsWith('/') ||
+    /^[a-zA-Z]:/.test(normalized) ||
+    normalized.split('/').some((seg) => seg === '..' || seg === '~')
+  if (bad) {
+    throw new Error(`unsafe resource path: "${path}"`)
+  }
+}
+
+/** Small, edge-safe (no `node:crypto`) stable string hash for `revision()`. */
+export function stableHash(input: string): string {
+  // ponytail: FNV-1a; collisions don't matter here — revision only needs to
+  // change when content changes, not be cryptographically unique.
+  let h = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(16).padStart(8, '0')
+}

package/src/validate.ts

@@ -0,0 +1,63 @@
+/**
+ * `validateSkill` — author-time linting against native-delivery constraints, so
+ * a skill authored today can be promoted to a hosted (Anthropic/OpenAI) skill
+ * later without surprises. Phase 1 never uploads; this only warns.
+ */
+import type { SkillMetadata } from './types'
+
+export type SkillTarget = 'portable' | 'anthropic' | 'openai'
+
+export interface SkillValidationIssue {
+  target: SkillTarget
+  message: string
+}
+
+export interface SkillValidationResult {
+  ok: boolean
+  issues: Array<SkillValidationIssue>
+}
+
+const XML_TAG = /<[^>]+>/
+const RESERVED_ANTHROPIC = ['anthropic', 'claude']
+
+/** Lint a skill against the given delivery targets (default `['portable']`). */
+export function validateSkill(
+  skill: SkillMetadata,
+  options: { targets?: Array<SkillTarget> } = {},
+): SkillValidationResult {
+  const targets = options.targets ?? ['portable']
+  const issues: Array<SkillValidationIssue> = []
+
+  const add = (target: SkillTarget, message: string) =>
+    issues.push({ target, message })
+
+  // Portable: the spec's own name/description bounds.
+  if (targets.includes('portable')) {
+    if (!/^[a-z0-9-]+$/.test(skill.name)) {
+      add('portable', 'name must match [a-z0-9-]')
+    }
+    if (skill.name.length > 64) add('portable', 'name exceeds 64 characters')
+    if (skill.description.length > 1024) {
+      add('portable', 'description exceeds 1024 characters')
+    }
+  }
+
+  if (targets.includes('anthropic')) {
+    const lower = skill.name.toLowerCase()
+    if (RESERVED_ANTHROPIC.some((r) => lower.includes(r))) {
+      add('anthropic', 'name may not contain "anthropic" or "claude"')
+    }
+    if (XML_TAG.test(skill.name) || XML_TAG.test(skill.description)) {
+      add('anthropic', 'name/description may not contain XML tags')
+    }
+  }
+
+  if (targets.includes('openai')) {
+    // OpenAI requires exactly one case-insensitive SKILL.md per bundle — a
+    // bundle-shape constraint not visible from metadata alone. Only the
+    // metadata-checkable rule is enforced here.
+    if (skill.name.trim() === '') add('openai', 'name must not be empty')
+  }
+
+  return { ok: issues.length === 0, issues }
+}

package/src/walk.ts

@@ -0,0 +1,84 @@
+/**
+ * Generic skill-directory walk, shared with `@tanstack/ai-sandbox`.
+ *
+ * The algorithm is identical to the one in `ai-sandbox/src/agents-file.ts`, but
+ * parameterized over an injected `list` function so it works over any backing
+ * store (`node:fs`, a `SandboxHandle.fs`, an in-memory tree). Taking only an
+ * injected function keeps this edge-safe, so it lives in the root barrel.
+ */
+
+/** A directory that contains `SKILL.md`. */
+export interface DiscoveredSkillDir {
+  name: string
+  dir: string
+}
+
+/** One entry as reported by an injected {@link ListDir}. */
+export interface WalkEntry {
+  name: string
+  path: string
+  type: 'file' | 'dir'
+}
+
+export type ListDir = (dir: string) => Promise<Array<WalkEntry>>
+
+export const SKILL_FILE = 'SKILL.md'
+export const MAX_SKILL_WALK_DEPTH = 6
+const SKIP_DIR_NAMES = new Set(['.git', 'node_modules'])
+
+function basenameOf(path: string): string {
+  const normalized = path.replace(/\\/g, '/')
+  const segments = normalized.split('/').filter((segment) => segment !== '')
+  return segments[segments.length - 1] ?? path
+}
+
+/**
+ * Find every skill folder under `root`. A skill folder is a directory that
+ * directly contains `SKILL.md`; the walk stops descending once found. Skips
+ * dot-directories, `.git`, and `node_modules`. Bounded by `maxDepth`. Errors
+ * from `list` are swallowed (an unreadable directory yields nothing).
+ *
+ * Unlike `ai-sandbox`'s `discoverSkillDirs`, this returns `[]` when nothing is
+ * found — the "fall back to the clone dir" behavior is a harness-projection
+ * concern and stays at that call site (it is wrong for a catalog).
+ */
+export async function walkSkillDirs(
+  list: ListDir,
+  root: string,
+  opts: { maxDepth?: number } = {},
+): Promise<Array<DiscoveredSkillDir>> {
+  const maxDepth = opts.maxDepth ?? MAX_SKILL_WALK_DEPTH
+  const found: Array<DiscoveredSkillDir> = []
+  await walk(list, root, found, 0, maxDepth)
+  return found
+}
+
+async function walk(
+  list: ListDir,
+  dir: string,
+  found: Array<DiscoveredSkillDir>,
+  depth: number,
+  maxDepth: number,
+): Promise<void> {
+  if (depth > maxDepth) return
+  let entries: Array<WalkEntry>
+  try {
+    entries = await list(dir)
+  } catch {
+    return
+  }
+  const hasSkill = entries.some(
+    (entry) =>
+      entry.type === 'file' &&
+      entry.name.toLowerCase() === SKILL_FILE.toLowerCase(),
+  )
+  if (hasSkill) {
+    found.push({ name: basenameOf(dir), dir })
+    return
+  }
+  for (const entry of entries) {
+    if (entry.type !== 'dir') continue
+    if (entry.name.startsWith('.') || SKIP_DIR_NAMES.has(entry.name)) continue
+    await walk(list, entry.path, found, depth + 1, maxDepth)
+  }
+}