@tanstack/ai-skills 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/catalog.d.ts

@@ -0,0 +1,5 @@
+import { ModelFamily, SkillMetadata } from './types.js';
+/** Sort skills into a stable, cache-friendly order. */
+export declare function sortSkills(skills: Array<SkillMetadata>): Array<SkillMetadata>;
+/** Render the skill catalog for a model family. Skills are sorted by name. */
+export declare function renderCatalog(skills: Array<SkillMetadata>, family: ModelFamily): string;

package/dist/esm/catalog.js

@@ -0,0 +1,18 @@
+//#region src/catalog.ts
+/** Sort skills into a stable, cache-friendly order. */
+function sortSkills(skills) {
+	return [...skills].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+function escapeXml(s) {
+	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. */
+function renderCatalog(skills, family) {
+	const sorted = sortSkills(skills);
+	if (family === "anthropic") return `<available_skills>\n${sorted.map((s) => `  <skill name="${escapeXml(s.name)}">${escapeXml(s.description)}</skill>`).join("\n")}\n</available_skills>`;
+	return `## Available skills\n\n${sorted.map((s) => `- **${s.name}**: ${s.description}`).join("\n")}`;
+}
+//#endregion
+export { renderCatalog, sortSkills };
+
+//# sourceMappingURL=catalog.js.map

package/dist/esm/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","names":[],"sources":["../../src/catalog.ts"],"sourcesContent":["/**\n * Catalog rendering (spec §4.3). Deterministic order (sort by name) and a fixed\n * position in the system prompt are prompt-cache requirements, not style. The\n * shape is per model family because `skills-ref` documents `<available_skills>`\n * XML as recommended specifically for Anthropic models.\n */\nimport type { ModelFamily, SkillMetadata } from './types'\n\n/** Sort skills into a stable, cache-friendly order. */\nexport function sortSkills(skills: Array<SkillMetadata>): Array<SkillMetadata> {\n  return [...skills].sort((a, b) =>\n    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,\n  )\n}\n\nfunction escapeXml(s: string): string {\n  return s\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&apos;')\n}\n\n/** Render the skill catalog for a model family. Skills are sorted by name. */\nexport function renderCatalog(\n  skills: Array<SkillMetadata>,\n  family: ModelFamily,\n): string {\n  const sorted = sortSkills(skills)\n  if (family === 'anthropic') {\n    const entries = sorted\n      .map(\n        (s) =>\n          `  <skill name=\"${escapeXml(s.name)}\">${escapeXml(s.description)}</skill>`,\n      )\n      .join('\\n')\n    return `<available_skills>\\n${entries}\\n</available_skills>`\n  }\n  const entries = sorted\n    .map((s) => `- **${s.name}**: ${s.description}`)\n    .join('\\n')\n  return `## Available skills\\n\\n${entries}`\n}\n"],"mappings":";;AASA,SAAgB,WAAW,QAAoD;CAC7E,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,GAAG,MAC1B,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,CAC/C;AACF;AAEA,SAAS,UAAU,GAAmB;CACpC,OAAO,EACJ,QAAQ,MAAM,OAAO,CAAC,CACtB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,QAAQ,CAAC,CACvB,QAAQ,MAAM,QAAQ;AAC3B;;AAGA,SAAgB,cACd,QACA,QACQ;CACR,MAAM,SAAS,WAAW,MAAM;CAChC,IAAI,WAAW,aAOb,OAAO,uBANS,OACb,KACE,MACC,kBAAkB,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU,EAAE,WAAW,EAAE,SACrE,CAAC,CACA,KAAK,IACsB,EAAQ;CAKxC,OAAO,0BAHS,OACb,KAAK,MAAM,OAAO,EAAE,KAAK,MAAM,EAAE,aAAa,CAAC,CAC/C,KAAK,IACyB;AACnC"}

package/dist/esm/combinators.d.ts

@@ -0,0 +1,24 @@
+import { SkillMetadata, SkillSource } from './types.js';
+export type FilterContext = Record<string, unknown>;
+export type FilterPredicate = (skill: SkillMetadata, ctx?: FilterContext) => boolean;
+/** Concatenate sources in registration order. No dedupe. */
+export declare function aggregate(sources: Array<SkillSource>): SkillSource;
+/** First occurrence of a name wins; warns on collision. */
+export declare function dedupe(source: SkillSource, onCollision?: (name: string) => void): SkillSource;
+/** Hide skills the predicate rejects. Filtered skills never reach the catalog. */
+export declare function filter(source: SkillSource, predicate: FilterPredicate, ctx?: FilterContext): SkillSource;
+/**
+ * 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 declare function cache(source: SkillSource, opts?: {
+    refreshInterval?: number;
+}): SkillSource;
+/**
+ * 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 declare function combineSources(sources: SkillSource | Array<SkillSource>): SkillSource;

package/dist/esm/combinators.js

@@ -0,0 +1,158 @@
+import { stableHash } from "./util.js";
+//#region src/combinators.ts
+/**
+* Source combinators (spec §3.3). Sources compose in practice: org skills +
+* project skills + tenant skills. `aggregate` concatenates, `dedupe` resolves
+* collisions, `filter` hides, `cache` memoizes.
+*/
+/** Forward a source's optional `revision`, preserving `undefined` when absent. */
+function forwardRevision(source) {
+	const rev = source.revision;
+	return rev ? () => rev() : void 0;
+}
+/** Route a delegating method to the first source that lists `name`. */
+async function ownerOf(sources, name) {
+	for (const source of sources) if ((await source.list()).some((s) => s.name === name)) return source;
+	throw new Error(`no source provides a skill named "${name}"`);
+}
+async function combinedRevision(sources) {
+	const revs = await Promise.all(sources.map((s) => s.revision?.() ?? Promise.resolve(void 0)));
+	if (revs.some((r) => r === void 0)) return void 0;
+	return stableHash(revs.join("|"));
+}
+/** Concatenate sources in registration order. No dedupe. */
+function aggregate(sources) {
+	return {
+		...sources.every((s) => s.revision) && { revision: async () => await combinedRevision(sources) ?? "" },
+		list: async () => {
+			return (await Promise.all(sources.map((s) => s.list()))).flat();
+		},
+		load: async (name) => (await ownerOf(sources, name)).load(name),
+		listResources: async (name) => {
+			return (await ownerOf(sources, name)).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) => {
+			return (await ownerOf(sources, name)).listScripts?.(name) ?? [];
+		},
+		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. */
+function dedupe(source, onCollision = (name) => console.warn(`[ai-skills] duplicate skill "${name}" — first one wins`)) {
+	return {
+		...source,
+		revision: forwardRevision(source),
+		list: async () => {
+			const seen = /* @__PURE__ */ new Set();
+			const out = [];
+			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. */
+function filter(source, predicate, ctx) {
+	const list = async () => (await source.list()).filter((s) => predicate(s, ctx));
+	const assertVisible = async (name) => {
+		if (!(await list()).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) ?? [];
+		} : void 0,
+		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);
+		} : void 0,
+		listScripts: source.listScripts ? async (name) => {
+			await assertVisible(name);
+			return source.listScripts?.(name) ?? [];
+		} : void 0,
+		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);
+		} : void 0
+	};
+}
+/**
+* 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.
+*/
+function cache(source, opts = {}) {
+	let listPromise;
+	let listAt = 0;
+	const loads = /* @__PURE__ */ new Map();
+	const now = () => opts.refreshInterval ? Date.now() : 0;
+	const fresh = () => opts.refreshInterval === void 0 || now() - listAt < opts.refreshInterval;
+	return {
+		...source,
+		revision: forwardRevision(source),
+		list: () => {
+			if (!listPromise || !fresh()) {
+				listAt = now();
+				loads.clear();
+				listPromise = source.list().catch((err) => {
+					listPromise = void 0;
+					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).
+*/
+function combineSources(sources) {
+	if (!Array.isArray(sources)) return sources;
+	const [first] = sources;
+	if (sources.length === 1 && first) return first;
+	return dedupe(aggregate(sources));
+}
+//#endregion
+export { aggregate, cache, combineSources, dedupe, filter };
+
+//# sourceMappingURL=combinators.js.map

package/dist/esm/combinators.js.map

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

package/dist/esm/errors.d.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/dist/esm/errors.js

@@ -0,0 +1,2 @@
+import { SkillLimitError as SkillLimitError$1 } from "@tanstack/ai";
+export { SkillLimitError$1 as SkillLimitError };

package/dist/esm/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@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.js';
+export { modelFamilyOf } from './types.js';
+export { parseSkill, stripFrontmatter, SkillParseError } from './parse.js';
+export type { ParsedSkill, ParseWarning } from './parse.js';
+export { walkSkillDirs, SKILL_FILE, MAX_SKILL_WALK_DEPTH } from './walk.js';
+export type { DiscoveredSkillDir, WalkEntry, ListDir } from './walk.js';
+export { inlineSkill } from './sources/inline.js';
+export type { InlineSkillConfig } from './sources/inline.js';
+export { aggregate, dedupe, filter, cache, combineSources } from './combinators.js';
+export type { FilterContext, FilterPredicate } from './combinators.js';
+export { renderCatalog, sortSkills } from './catalog.js';
+export { withSkills, SKILLS_STATE_EVENT } from './middleware.js';
+export type { SkillsOptions, SkillsStateEventValue } from './middleware.js';
+export { createLoadSkillTool, ALREADY_LOADED } from './tools/load-skill.js';
+export { createResourceTool, READ_RESOURCE_TOOL_NAME, } from './tools/read-resource.js';
+export { validateSkill } from './validate.js';
+export type { SkillTarget, SkillValidationIssue, SkillValidationResult, } from './validate.js';
+export { SkillLimitError } from './errors.js';
+export type { SkillLimitErrorInit } from './errors.js';
+export { assertSafeResourcePath, stableHash } from './util.js';

package/dist/esm/index.js

@@ -0,0 +1,13 @@
+import { modelFamilyOf } from "./types.js";
+import { SkillParseError, parseSkill, stripFrontmatter } from "./parse.js";
+import { MAX_SKILL_WALK_DEPTH, SKILL_FILE, walkSkillDirs } from "./walk.js";
+import { assertSafeResourcePath, stableHash } from "./util.js";
+import { validateSkill } from "./validate.js";
+import { inlineSkill } from "./sources/inline.js";
+import { aggregate, cache, combineSources, dedupe, filter } from "./combinators.js";
+import { renderCatalog, sortSkills } from "./catalog.js";
+import { ALREADY_LOADED, createLoadSkillTool } from "./tools/load-skill.js";
+import { READ_RESOURCE_TOOL_NAME, createResourceTool } from "./tools/read-resource.js";
+import { SKILLS_STATE_EVENT, withSkills } from "./middleware.js";
+import { SkillLimitError } from "./errors.js";
+export { ALREADY_LOADED, MAX_SKILL_WALK_DEPTH, READ_RESOURCE_TOOL_NAME, SKILLS_STATE_EVENT, SKILL_FILE, SkillLimitError, SkillParseError, aggregate, assertSafeResourcePath, cache, combineSources, createLoadSkillTool, createResourceTool, dedupe, filter, inlineSkill, modelFamilyOf, parseSkill, renderCatalog, sortSkills, stableHash, stripFrontmatter, validateSkill, walkSkillDirs, withSkills };

package/dist/esm/middleware.d.ts

@@ -0,0 +1,44 @@
+import { DefinedChatMiddleware, Tool } from '@tanstack/ai';
+import { ModelFamily, SkillMetadata, SkillSource } from './types.js';
+/** CUSTOM stream-event name carrying the catalog to the browser DevTools. */
+export declare const SKILLS_STATE_EVENT = "skills:state";
+export interface SkillsStateEventValue {
+    catalog: Array<{
+        name: string;
+        description: string;
+    }>;
+    activated: Array<string>;
+}
+export interface SkillsOptions {
+    /** Override catalog rendering. Receives resolved metadata + the model family. */
+    renderCatalog?: (skills: Array<SkillMetadata>, family: ModelFamily) => string;
+    /** Template with a required `{skills}` placeholder. Literal braces escape as `{{`/`}}`. */
+    instructionTemplate?: string;
+    /** Hard cap on tier-1 catalog token spend. Default 4000. */
+    maxCatalogTokens?: number;
+    /** `'error'` (default) or a reducer invoked when the cap is exceeded. */
+    onLimitExceeded?: 'error' | ((skills: Array<SkillMetadata>, limit: number) => Array<SkillMetadata>);
+    /** Where the catalog goes. Default `'system'`. */
+    catalogPlacement?: 'system' | 'tool-description';
+    /** Require approval before load_skill / read_skill_resource. Default false. */
+    requireApproval?: boolean;
+}
+interface SkillsRuntime {
+    skills: Array<SkillMetadata>;
+    activated: Set<string>;
+    source: SkillSource;
+    family: ModelFamily;
+    catalog: string;
+    options: SkillsOptions;
+    /** Built on first onConfig (needs config.tools to detect the resource tool). */
+    memo?: {
+        prompt: {
+            content: string;
+        } | undefined;
+        tools: Array<Tool>;
+    };
+    stateChunkEmitted?: boolean;
+}
+declare const SkillsCapability: import('@tanstack/ai').Capability<SkillsRuntime, "skills">;
+export declare function withSkills(sources: SkillSource | Array<SkillSource>, options?: SkillsOptions): DefinedChatMiddleware<unknown, readonly [], readonly [typeof SkillsCapability]>;
+export {};

package/dist/esm/middleware.js

@@ -0,0 +1,133 @@
+import { modelFamilyOf } from "./types.js";
+import { combineSources } from "./combinators.js";
+import { renderCatalog } from "./catalog.js";
+import { createLoadSkillTool } from "./tools/load-skill.js";
+import { READ_RESOURCE_TOOL_NAME } from "./tools/read-resource.js";
+import { SkillLimitError, createCapability, defineChatMiddleware } from "@tanstack/ai";
+//#region src/middleware.ts
+/**
+* `withSkills` — portable Agent Skills as a chat middleware.
+*
+* All source resolution and catalog rendering happen once in `setup`; `onConfig`
+* (which fires every agent iteration) only returns memoized values. Otherwise an
+* S3-backed source would hit the network per loop turn and catalog reordering
+* would break Anthropic's cache prefix mid-run.
+*/
+/** CUSTOM stream-event name carrying the catalog to the browser DevTools. */
+var SKILLS_STATE_EVENT = "skills:state";
+var SkillsCapability = createCapability()("skills");
+/** ~4 chars/token — good enough to guard a runaway catalog. */
+var estimateTokens = (s) => Math.ceil(s.length / 4);
+function fillTemplate(template, catalog) {
+	const OPEN = "\0OPEN\0";
+	const CLOSE = "\0CLOSE\0";
+	return template.split("{{").join(OPEN).split("}}").join(CLOSE).split("{skills}").join(catalog).split(OPEN).join("{").split(CLOSE).join("}");
+}
+/** True when a code_execution/shell tool in `tools` carries hosted skills. */
+function findNativeSkillTool(tools) {
+	for (const tool of tools) {
+		const meta = tool.metadata;
+		if (tool.name === "code_execution" && (meta?.skills?.length ?? 0) > 0) return "code_execution";
+		if (tool.name === "shell" && (meta?.environment?.skills?.length ?? 0) > 0) return "shell";
+	}
+}
+function activationInstructions(catalog, hasResourceTool) {
+	return [
+		"You have access to a library of skills. When a task matches one, call the `load_skill` tool with its name to load its full instructions before proceeding.",
+		catalog,
+		hasResourceTool ? "To read a skill’s bundled resource files, call `read_skill_resource` with the skill name and the resource path." : "Some skills may list resource files; they are not loadable in this configuration."
+	].join("\n\n");
+}
+function withSkills(sources, options = {}) {
+	if (options.instructionTemplate && options.renderCatalog) throw new Error("`instructionTemplate` and `renderCatalog` are mutually exclusive");
+	if (options.instructionTemplate && !options.instructionTemplate.includes("{skills}")) throw new Error("`instructionTemplate` must contain a `{skills}` placeholder");
+	return defineChatMiddleware({
+		name: "skills",
+		provides: [SkillsCapability],
+		async setup(ctx) {
+			const source = combineSources(sources);
+			let skills = await source.list();
+			const family = modelFamilyOf(ctx.provider);
+			const limit = options.maxCatalogTokens ?? 4e3;
+			const render = options.renderCatalog ?? renderCatalog;
+			let catalog = render(skills, family);
+			if (estimateTokens(catalog) > limit) {
+				if (options.onLimitExceeded && options.onLimitExceeded !== "error") {
+					skills = options.onLimitExceeded(skills, limit);
+					catalog = render(skills, family);
+				}
+				if (estimateTokens(catalog) > limit) throw new SkillLimitError({
+					provider: family,
+					path: "portable",
+					limit: `maxCatalogTokens (${limit})`,
+					allowed: limit,
+					actual: estimateTokens(catalog),
+					offending: skills.map((s) => s.name)
+				});
+			}
+			ctx.provide(SkillsCapability, {
+				skills,
+				activated: /* @__PURE__ */ new Set(),
+				source,
+				family,
+				catalog,
+				options
+			});
+		},
+		onConfig(ctx, config) {
+			const rt = ctx.get(SkillsCapability);
+			if (rt.skills.length === 0) return;
+			const native = findNativeSkillTool(config.tools);
+			if (native) throw new Error(`withSkills (portable skills) cannot be combined with a "${native}" tool that carries hosted/native skills. Use one delivery mode: remove the hosted skills, or drop withSkills.`);
+			if (!rt.memo) {
+				const hasResourceTool = config.tools.some((t) => t.name === READ_RESOURCE_TOOL_NAME);
+				const body = options.instructionTemplate !== void 0 ? fillTemplate(options.instructionTemplate, rt.catalog) : activationInstructions(rt.catalog, hasResourceTool);
+				const loadTool = createLoadSkillTool({
+					source: rt.source,
+					skills: rt.skills,
+					activated: rt.activated,
+					requireApproval: options.requireApproval
+				});
+				if ((options.catalogPlacement ?? "system") === "tool-description") {
+					loadTool.description = `${loadTool.description}\n\n${body}`;
+					rt.memo = {
+						prompt: void 0,
+						tools: [loadTool]
+					};
+				} else rt.memo = {
+					prompt: { content: body },
+					tools: [loadTool]
+				};
+			}
+			const prompt = rt.memo.prompt;
+			const promptPresent = !prompt || config.systemPrompts.some((p) => typeof p === "string" ? p === prompt.content : p.content === prompt.content);
+			const existingNames = new Set(config.tools.map((t) => t.name));
+			const toolsToAdd = rt.memo.tools.filter((t) => !existingNames.has(t.name));
+			return {
+				systemPrompts: prompt && !promptPresent ? [...config.systemPrompts, prompt] : config.systemPrompts,
+				tools: toolsToAdd.length > 0 ? [...config.tools, ...toolsToAdd] : config.tools
+			};
+		},
+		onChunk(ctx, chunk) {
+			const rt = ctx.getOptional(SkillsCapability);
+			if (!rt || rt.stateChunkEmitted) return;
+			rt.stateChunkEmitted = true;
+			return [chunk, {
+				type: "CUSTOM",
+				name: SKILLS_STATE_EVENT,
+				value: {
+					catalog: rt.skills.map((s) => ({
+						name: s.name,
+						description: s.description
+					})),
+					activated: [...rt.activated]
+				},
+				timestamp: Date.now()
+			}];
+		}
+	});
+}
+//#endregion
+export { SKILLS_STATE_EVENT, withSkills };
+
+//# sourceMappingURL=middleware.js.map

package/dist/esm/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","names":[],"sources":["../../src/middleware.ts"],"sourcesContent":["/**\n * `withSkills` — portable Agent Skills as a chat middleware.\n *\n * All source resolution and catalog rendering happen once in `setup`; `onConfig`\n * (which fires every agent iteration) only returns memoized values. Otherwise an\n * S3-backed source would hit the network per loop turn and catalog reordering\n * would break Anthropic's cache prefix mid-run.\n */\nimport {\n  createCapability,\n  defineChatMiddleware,\n  SkillLimitError,\n} from '@tanstack/ai'\nimport { combineSources } from './combinators'\nimport { renderCatalog } from './catalog'\nimport { modelFamilyOf } from './types'\nimport { createLoadSkillTool } from './tools/load-skill'\nimport { READ_RESOURCE_TOOL_NAME } from './tools/read-resource'\nimport type { DefinedChatMiddleware, StreamChunk, Tool } from '@tanstack/ai'\nimport type { ModelFamily, SkillMetadata, SkillSource } from './types'\n\n/** CUSTOM stream-event name carrying the catalog to the browser DevTools. */\nexport const SKILLS_STATE_EVENT = 'skills:state'\n\nexport interface SkillsStateEventValue {\n  catalog: Array<{ name: string; description: string }>\n  activated: Array<string>\n}\n\nexport interface SkillsOptions {\n  /** Override catalog rendering. Receives resolved metadata + the model family. */\n  renderCatalog?: (skills: Array<SkillMetadata>, family: ModelFamily) => string\n  /** Template with a required `{skills}` placeholder. Literal braces escape as `{{`/`}}`. */\n  instructionTemplate?: string\n  /** Hard cap on tier-1 catalog token spend. Default 4000. */\n  maxCatalogTokens?: number\n  /** `'error'` (default) or a reducer invoked when the cap is exceeded. */\n  onLimitExceeded?:\n    | 'error'\n    | ((skills: Array<SkillMetadata>, limit: number) => Array<SkillMetadata>)\n  /** Where the catalog goes. Default `'system'`. */\n  catalogPlacement?: 'system' | 'tool-description'\n  /** Require approval before load_skill / read_skill_resource. Default false. */\n  requireApproval?: boolean\n}\n\ninterface SkillsRuntime {\n  skills: Array<SkillMetadata>\n  activated: Set<string>\n  source: SkillSource\n  family: ModelFamily\n  catalog: string\n  options: SkillsOptions\n  /** Built on first onConfig (needs config.tools to detect the resource tool). */\n  memo?: { prompt: { content: string } | undefined; tools: Array<Tool> }\n  stateChunkEmitted?: boolean\n}\n\nconst SkillsCapability = createCapability<SkillsRuntime>()('skills')\n\n/** ~4 chars/token — good enough to guard a runaway catalog. */\nconst estimateTokens = (s: string) => Math.ceil(s.length / 4)\n\nfunction fillTemplate(template: string, catalog: string): string {\n  // Escape `{{`/`}}` to sentinels, substitute `{skills}`, then restore braces.\n  const OPEN = '\\u0000OPEN\\u0000'\n  const CLOSE = '\\u0000CLOSE\\u0000'\n  return template\n    .split('{{')\n    .join(OPEN)\n    .split('}}')\n    .join(CLOSE)\n    .split('{skills}')\n    .join(catalog)\n    .split(OPEN)\n    .join('{')\n    .split(CLOSE)\n    .join('}')\n}\n\n/** True when a code_execution/shell tool in `tools` carries hosted skills. */\nfunction findNativeSkillTool(tools: Array<Tool>): string | undefined {\n  for (const tool of tools) {\n    const meta = tool.metadata as\n      | { skills?: Array<unknown>; environment?: { skills?: Array<unknown> } }\n      | undefined\n    if (tool.name === 'code_execution' && (meta?.skills?.length ?? 0) > 0) {\n      return 'code_execution'\n    }\n    if (tool.name === 'shell' && (meta?.environment?.skills?.length ?? 0) > 0) {\n      return 'shell'\n    }\n  }\n  return undefined\n}\n\nfunction activationInstructions(\n  catalog: string,\n  hasResourceTool: boolean,\n): string {\n  const resourceLine = hasResourceTool\n    ? 'To read a skill’s bundled resource files, call `read_skill_resource` with the skill name and the resource path.'\n    : 'Some skills may list resource files; they are not loadable in this configuration.'\n  return [\n    'You have access to a library of skills. When a task matches one, call the `load_skill` tool with its name to load its full instructions before proceeding.',\n    catalog,\n    resourceLine,\n  ].join('\\n\\n')\n}\n\nexport function withSkills(\n  sources: SkillSource | Array<SkillSource>,\n  options: SkillsOptions = {},\n): DefinedChatMiddleware<\n  unknown,\n  readonly [],\n  readonly [typeof SkillsCapability]\n> {\n  if (options.instructionTemplate && options.renderCatalog) {\n    throw new Error(\n      '`instructionTemplate` and `renderCatalog` are mutually exclusive',\n    )\n  }\n  if (\n    options.instructionTemplate &&\n    !options.instructionTemplate.includes('{skills}')\n  ) {\n    throw new Error(\n      '`instructionTemplate` must contain a `{skills}` placeholder',\n    )\n  }\n\n  return defineChatMiddleware({\n    name: 'skills',\n    provides: [SkillsCapability],\n\n    async setup(ctx) {\n      const source = combineSources(sources)\n      let skills = await source.list()\n      const family = modelFamilyOf(ctx.provider)\n\n      // Catalog token cap (spec §4.2).\n      const limit = options.maxCatalogTokens ?? 4000\n      const render = options.renderCatalog ?? renderCatalog\n      let catalog = render(skills, family)\n      if (estimateTokens(catalog) > limit) {\n        if (options.onLimitExceeded && options.onLimitExceeded !== 'error') {\n          skills = options.onLimitExceeded(skills, limit)\n          catalog = render(skills, family)\n        }\n        if (estimateTokens(catalog) > limit) {\n          throw new SkillLimitError({\n            provider: family,\n            path: 'portable',\n            limit: `maxCatalogTokens (${limit})`,\n            allowed: limit,\n            actual: estimateTokens(catalog),\n            offending: skills.map((s) => s.name),\n          })\n        }\n      }\n\n      ctx.provide(SkillsCapability, {\n        skills,\n        activated: new Set<string>(),\n        source,\n        family,\n        catalog,\n        options,\n      })\n    },\n\n    onConfig(ctx, config) {\n      const rt = ctx.get(SkillsCapability)\n      if (rt.skills.length === 0) return // empty catalog → no tools, no prompt\n\n      // Native co-existence: portable + hosted skills don't compose (spec §6.1).\n      const native = findNativeSkillTool(config.tools)\n      if (native) {\n        throw new Error(\n          `withSkills (portable skills) cannot be combined with a \"${native}\" tool that carries hosted/native skills. ` +\n            'Use one delivery mode: remove the hosted skills, or drop withSkills.',\n        )\n      }\n\n      if (!rt.memo) {\n        const hasResourceTool = config.tools.some(\n          (t) => t.name === READ_RESOURCE_TOOL_NAME,\n        )\n        const body =\n          options.instructionTemplate !== undefined\n            ? fillTemplate(options.instructionTemplate, rt.catalog)\n            : activationInstructions(rt.catalog, hasResourceTool)\n\n        const loadTool = createLoadSkillTool({\n          source: rt.source,\n          skills: rt.skills,\n          activated: rt.activated,\n          requireApproval: options.requireApproval,\n        })\n\n        const placement = options.catalogPlacement ?? 'system'\n        if (placement === 'tool-description') {\n          loadTool.description = `${loadTool.description}\\n\\n${body}`\n          rt.memo = { prompt: undefined, tools: [loadTool] }\n        } else {\n          rt.memo = { prompt: { content: body }, tools: [loadTool] }\n        }\n      }\n\n      // onConfig fires every iteration and the engine feeds the merged config\n      // back in — so appending must be idempotent (add our prompt/tools only\n      // when not already present) or a second iteration duplicates them.\n      const prompt = rt.memo.prompt\n      const promptPresent =\n        !prompt ||\n        config.systemPrompts.some((p) =>\n          typeof p === 'string'\n            ? p === prompt.content\n            : p.content === prompt.content,\n        )\n      const existingNames = new Set(config.tools.map((t) => t.name))\n      const toolsToAdd = rt.memo.tools.filter((t) => !existingNames.has(t.name))\n\n      return {\n        systemPrompts:\n          prompt && !promptPresent\n            ? [...config.systemPrompts, prompt]\n            : config.systemPrompts,\n        tools:\n          toolsToAdd.length > 0\n            ? [...config.tools, ...toolsToAdd]\n            : config.tools,\n      }\n    },\n\n    onChunk(ctx, chunk) {\n      const rt = ctx.getOptional(SkillsCapability)\n      if (!rt || rt.stateChunkEmitted) return\n      rt.stateChunkEmitted = true\n      const custom: StreamChunk = {\n        type: 'CUSTOM',\n        name: SKILLS_STATE_EVENT,\n        value: {\n          catalog: rt.skills.map((s) => ({\n            name: s.name,\n            description: s.description,\n          })),\n          activated: [...rt.activated],\n        } satisfies SkillsStateEventValue,\n        timestamp: Date.now(),\n      }\n      return [chunk, custom]\n    },\n  })\n}\n"],"mappings":"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"}

package/dist/esm/node/index.d.ts

@@ -0,0 +1,33 @@
+import { GeneratedCatalog } from '../static/index.js';
+import { SkillSource } from '../types.js';
+export interface SkillDirectoryOptions {
+    maxDepth?: number;
+    /** default true — promote parse warnings to errors (see spec §7). */
+    strict?: boolean;
+}
+export declare function skillDirectory(root: string | Array<string>, options?: SkillDirectoryOptions): SkillSource;
+/**
+ * Read a skill directory tree into a plain {@link GeneratedCatalog} — the shape
+ * `staticSkills` consumes. Used by the Vite plugin and directly available for
+ * custom build scripts.
+ */
+export declare function generateCatalog(root: string | Array<string>, options?: SkillDirectoryOptions): Promise<GeneratedCatalog>;
+/** Structural Vite plugin (no `vite` type dependency). */
+export interface SkillsCatalogPlugin {
+    name: string;
+    resolveId: (id: string) => string | undefined;
+    load: (this: {
+        addWatchFile?: (id: string) => void;
+    }, id: string) => Promise<string | undefined>;
+}
+/**
+ * Vite plugin that globs `SKILL.md` under `dir` at build time and serves a
+ * virtual module (default id `virtual:tanstack-skills`) exporting the catalog
+ * `as const`. Consumers then wrap it with `staticSkills` for a literal-union of
+ * skill names. The catalog is embedded as JSON, so the bundle hash tracks it.
+ */
+export declare function skillsCatalogPlugin(options?: {
+    dir?: string;
+    virtualId?: string;
+    maxDepth?: number;
+}): SkillsCatalogPlugin;