toolnexus 0.7.0 → 0.8.0

package/dist/serve.js

@@ -50,7 +50,13 @@ export class FileTaskStore {
         }
     }
     async save(task) {
-        fs.writeFileSync(this.file(task.id), JSON.stringify(task));
+        // Atomic write: a concurrent get() must never read a half-written file (that
+        // would surface as a spurious "Task not found" mid-poll). Write a temp file in
+        // the same dir, then rename over the target.
+        const target = this.file(task.id);
+        const tmp = `${target}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(task));
+        fs.renameSync(tmp, target);
     }
 }
 /** Map a `store` selector to a concrete TaskStore. `"file:<dir>"` → FileTaskStore. */

package/dist/skill.d.ts

@@ -10,6 +10,42 @@ export interface SkillInfo {
     description?: string;
     location: string;
     content: string;
+    /** Internal origin discriminator; "fs" ⇒ on-disk (default), "logical" ⇒ data. */
+    origin?: "fs" | "logical";
+    /** Logical resource list (data-sourced skills only). */
+    resources?: string[];
+    /** Logical base, e.g. skill://name/ (data-sourced skills only). */
+    base?: string;
+}
+/** A skill supplied directly as data, bypassing the filesystem (SPEC.md §3, S1). */
+export interface SkillDef {
+    name: string;
+    description?: string;
+    content: string;
+    /** Optional logical resource names surfaced in the invoke-time <skill_files> block. */
+    resources?: string[];
+    /** Optional logical base; defaults to `skill://<name>/`. */
+    base?: string;
+}
+/** Why a candidate SKILL.md did not become a skill (SPEC.md §3, S3). */
+export type SkillSkipReason = "missing-name" | "malformed-frontmatter" | "duplicate-name" | "unreadable";
+export interface SkillSkip {
+    location: string;
+    reason: SkillSkipReason;
+}
+/** Result of a list-only validate pass (SPEC.md §3, S3). */
+export interface SkillInventory {
+    skills: SkillInfo[];
+    skipped: SkillSkip[];
+}
+/** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
+export interface LoadSkillsOptions {
+    dirs?: string | string[];
+    skills?: SkillDef[];
+    /** Per-agent allowlist keyed on skill name; same semantics as the MCP tools filter. */
+    filter?: Record<string, boolean>;
+    /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files>. */
+    sampleLimit?: number;
 }
 export interface SkillSource {
     skills: Record<string, SkillInfo>;
@@ -17,5 +53,11 @@ export interface SkillSource {
     /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
     prompt(): string;
 }
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export declare function loadSkills(dirs: string | string[]): SkillSource;
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+export declare function listSkills(input: string | string[] | LoadSkillsOptions): SkillInventory;
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export declare function loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource;

package/dist/skill.js

@@ -3,6 +3,11 @@
  * discover **\/SKILL.md, parse frontmatter, and expose ONE `skill` tool that
  * loads a skill's instructions + sampled resources on demand (progressive
  * disclosure).
+ *
+ * Beyond on-disk discovery the source also accepts skills supplied as data
+ * (`SkillDef`) — SPEC.md §3. Directory-sourced skills keep the exact `file://`
+ * base + on-disk sibling sampling (byte-identical); data-sourced skills use a
+ * logical `skill://name/` base + a supplied resource list and never touch disk.
  */
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
@@ -23,18 +28,25 @@ export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions a
  * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
  * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
  * values all resolve correctly. Scalar values are coerced to strings.
+ *
+ * `malformed` is true only when fences are present but the YAML fails to parse —
+ * distinguishing a malformed header from a body with no frontmatter, so the
+ * inventory (S3) can report the right skip reason. loadSkills' behavior is
+ * unchanged: a malformed header yields no name and the skill is skipped.
  */
 function parseFrontmatter(text) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!match)
-        return { data: {}, content: text };
+        return { data: {}, content: text, malformed: false };
     const data = {};
     let parsed;
+    let malformed = false;
     try {
         parsed = parseYaml(match[1]);
     }
     catch {
         parsed = null;
+        malformed = true;
     }
     if (parsed && typeof parsed === "object") {
         for (const [key, value] of Object.entries(parsed)) {
@@ -45,7 +57,7 @@ function parseFrontmatter(text) {
             }
         }
     }
-    return { data, content: match[2] };
+    return { data, content: match[2], malformed };
 }
 function walkSkillFiles(root) {
     const out = [];
@@ -150,45 +162,130 @@ function sampleSiblingFiles(dir, limit = 10) {
     }
     return out;
 }
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export function loadSkills(dirs) {
-    const roots = Array.isArray(dirs) ? dirs : [dirs];
-    const skills = {};
-    for (const root of roots) {
-        let isDir = false;
+/** Discover candidates under one on-disk root (order = discovery order). */
+function candidatesFromDir(root) {
+    const out = [];
+    let isDir = false;
+    try {
+        isDir = statSync(root).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        console.warn(`[toolnexus] skills dir not found: ${root}`);
+        return out;
+    }
+    for (const file of walkSkillFiles(root)) {
+        let text;
         try {
-            isDir = statSync(root).isDirectory();
+            text = readFileSync(file, "utf8");
         }
         catch {
-            isDir = false;
+            out.push({ skip: { location: file, reason: "unreadable" } });
+            continue;
         }
-        if (!isDir) {
-            console.warn(`[toolnexus] skills dir not found: ${root}`);
+        const { data, content, malformed } = parseFrontmatter(text);
+        if (malformed) {
+            out.push({ skip: { location: file, reason: "malformed-frontmatter" } });
             continue;
         }
-        for (const file of walkSkillFiles(root)) {
-            let text;
-            try {
-                text = readFileSync(file, "utf8");
-            }
-            catch {
-                continue;
-            }
-            const { data, content } = parseFrontmatter(text);
-            if (!data.name)
-                continue;
-            if (skills[data.name]) {
-                console.warn(`[toolnexus] duplicate skill name "${data.name}" (${file}) — keeping first`);
-                continue;
-            }
-            skills[data.name] = {
-                name: data.name,
-                description: data.description,
-                location: file,
-                content,
-            };
+        if (!data.name) {
+            out.push({ skip: { location: file, reason: "missing-name" } });
+            continue;
         }
+        out.push({ info: { name: data.name, description: data.description, location: file, content, origin: "fs" } });
     }
+    return out;
+}
+/** Turn data-supplied skill defs into candidates (logical origin). */
+function candidatesFromDefs(defs) {
+    return defs.map((d) => {
+        if (!d.name)
+            return { skip: { location: d.base ?? "skill://", reason: "missing-name" } };
+        const base = d.base && d.base.length > 0 ? d.base : `skill://${d.name}/`;
+        return {
+            info: {
+                name: d.name,
+                description: d.description,
+                location: base,
+                content: d.content ?? "",
+                origin: "logical",
+                resources: d.resources ?? [],
+                base,
+            },
+        };
+    });
+}
+/** Collect ordered candidates from dirs then data defs. */
+function collectCandidates(opts) {
+    const roots = opts.dirs === undefined ? [] : Array.isArray(opts.dirs) ? opts.dirs : [opts.dirs];
+    const cands = [];
+    for (const root of roots)
+        cands.push(...candidatesFromDir(root));
+    if (opts.skills)
+        cands.push(...candidatesFromDefs(opts.skills));
+    return cands;
+}
+/** Dedupe candidates by name (first-wins); later duplicates become skips. */
+function mergeCandidates(cands) {
+    const skills = {};
+    const skipped = [];
+    for (const c of cands) {
+        if (c.skip) {
+            skipped.push(c.skip);
+            continue;
+        }
+        const info = c.info;
+        if (skills[info.name]) {
+            console.warn(`[toolnexus] duplicate skill name "${info.name}" (${info.location}) — keeping first`);
+            skipped.push({ location: info.location, reason: "duplicate-name" });
+            continue;
+        }
+        skills[info.name] = info;
+    }
+    return { skills, skipped };
+}
+/**
+ * Apply the per-agent skill allowlist (S2), semantics identical to the MCP
+ * per-server tools filter and builtins: nil/empty ⇒ all; ≥1 true ⇒ allowlist
+ * (only true-mapped names); only-false ⇒ drop-list over all-on; unknown names
+ * are ignored and warned once.
+ */
+function applySkillsFilter(skills, filter) {
+    if (!filter)
+        return skills;
+    const keys = Object.keys(filter);
+    if (keys.length === 0)
+        return skills;
+    const hasTrue = keys.some((k) => filter[k] === true);
+    for (const k of keys) {
+        if (!(k in skills))
+            console.warn(`[toolnexus] skill filter name "${k}" matched no skill`);
+    }
+    const out = {};
+    for (const [name, info] of Object.entries(skills)) {
+        if (hasTrue ? filter[name] === true : filter[name] !== false)
+            out[name] = info;
+    }
+    return out;
+}
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+export function listSkills(input) {
+    const opts = typeof input === "string" || Array.isArray(input) ? { dirs: input } : input;
+    const merged = mergeCandidates(collectCandidates(opts));
+    return { skills: Object.values(merged.skills), skipped: merged.skipped };
+}
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export function loadSkills(input) {
+    const opts = typeof input === "string" || Array.isArray(input) ? { dirs: input } : input;
+    const sampleLimit = opts.sampleLimit ?? 0;
+    const merged = mergeCandidates(collectCandidates(opts));
+    const skills = applySkillsFilter(merged.skills, opts.filter);
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -208,10 +305,30 @@ export function loadSkills(dirs) {
                     isError: true,
                 };
             }
-            const dir = path.dirname(info.location);
-            const base = pathToFileURL(dir).href;
-            const files = sampleSiblingFiles(dir);
-            const output = [
+            // effLimit: 0 ⇒ default 10 (byte-identical to today), n>0 ⇒ cap, -1 ⇒ omit.
+            const effLimit = sampleLimit === 0 ? 10 : sampleLimit;
+            let base;
+            let files;
+            let metaDir;
+            // Emit the <skill_files> block: always for fs skills (byte-identical, even
+            // when empty), only when a data skill actually carries resources (an
+            // instruction-only data skill omits it). Never when sampling is disabled.
+            let emitFiles = effLimit !== -1;
+            if (info.origin === "logical") {
+                base = info.base ?? `skill://${info.name}/`;
+                const res = info.resources ?? [];
+                if (res.length === 0)
+                    emitFiles = false;
+                files = effLimit > 0 ? res.slice(0, effLimit) : res;
+                metaDir = base;
+            }
+            else {
+                const dir = path.dirname(info.location);
+                base = pathToFileURL(dir).href;
+                files = effLimit === -1 ? [] : sampleSiblingFiles(dir, effLimit);
+                metaDir = dir;
+            }
+            const lines = [
                 `<skill_content name="${info.name}">`,
                 `# Skill: ${info.name}`,
                 "",
@@ -219,14 +336,12 @@ export function loadSkills(dirs) {
                 "",
                 `Base directory for this skill: ${base}`,
                 "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
-                "Note: file list is sampled.",
-                "",
-                "<skill_files>",
-                files.map((f) => `<file>${f}</file>`).join("\n"),
-                "</skill_files>",
-                "</skill_content>",
-            ].join("\n");
-            return { output, isError: false, metadata: { name: info.name, dir } };
+            ];
+            if (emitFiles) {
+                lines.push("Note: file list is sampled.", "", "<skill_files>", files.map((f) => `<file>${f}</file>`).join("\n"), "</skill_files>");
+            }
+            lines.push("</skill_content>");
+            return { output: lines.join("\n"), isError: false, metadata: { name: info.name, dir: metaDir } };
         },
     };
     return {

package/dist/toolkit.d.ts

@@ -3,6 +3,7 @@
  * single uniform list, with provider adapters and a single execute() router.
  */
 import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js";
+import { type SkillDef } from "./skill.js";
 import { type BuiltinsConfig } from "./builtin.js";
 import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
@@ -11,6 +12,14 @@ import type { Client } from "./client.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
     skillsDir?: string | string[];
+    /** Skills supplied as data, bypassing the filesystem (§3, S1). */
+    skills?: SkillDef[];
+    /** Lazy provider of data-supplied skills, resolved once at toolkit build (§3, S1). */
+    skillProvider?: () => SkillDef[] | Promise<SkillDef[]>;
+    /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
+    skillsFilter?: Record<string, boolean>;
+    /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
+    skillSampleLimit?: number;
     extraTools?: Tool[];
     /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
     builtins?: BuiltinsConfig;

package/dist/toolkit.js

@@ -35,7 +35,29 @@ export class Toolkit {
     }
     static async create(opts) {
         const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined;
-        const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined;
+        // Skills come from directories, in-memory data, and/or a lazy provider (§3,
+        // S1). The provider is resolved here (create() is async) and merged with the
+        // data list; a provider failure is isolated so other sources still load.
+        let skill;
+        if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+            let providerDefs = [];
+            if (opts.skillProvider) {
+                try {
+                    providerDefs = await opts.skillProvider();
+                }
+                catch (e) {
+                    console.warn(`[toolnexus] skill provider failed: ${e instanceof Error ? e.message : String(e)}`);
+                    providerDefs = [];
+                }
+            }
+            const dataDefs = [...(opts.skills ?? []), ...providerDefs];
+            skill = loadSkills({
+                dirs: opts.skillsDir,
+                skills: dataDefs.length > 0 ? dataDefs : undefined,
+                filter: opts.skillsFilter,
+                sampleLimit: opts.skillSampleLimit,
+            });
+        }
         // The toggle comes from the `builtins` option, or a top-level `builtins`
         // key on a parsed config object — same precedence as MCP's isEnabled.
         let builtinsCfg = opts.builtins;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/serve.ts

@@ -62,7 +62,13 @@ export class FileTaskStore implements TaskStore {
     }
   }
   async save(task: A2ATask): Promise<void> {
-    fs.writeFileSync(this.file(task.id), JSON.stringify(task))
+    // Atomic write: a concurrent get() must never read a half-written file (that
+    // would surface as a spurious "Task not found" mid-poll). Write a temp file in
+    // the same dir, then rename over the target.
+    const target = this.file(task.id)
+    const tmp = `${target}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(task))
+    fs.renameSync(tmp, target)
   }
 }
 

package/src/skill.ts

@@ -3,6 +3,11 @@
  * discover **\/SKILL.md, parse frontmatter, and expose ONE `skill` tool that
  * loads a skill's instructions + sampled resources on demand (progressive
  * disclosure).
+ *
+ * Beyond on-disk discovery the source also accepts skills supplied as data
+ * (`SkillDef`) — SPEC.md §3. Directory-sourced skills keep the exact `file://`
+ * base + on-disk sibling sampling (byte-identical); data-sourced skills use a
+ * logical `skill://name/` base + a supplied resource list and never touch disk.
  */
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs"
 import path from "node:path"
@@ -27,24 +32,72 @@ export const SKILLS_PROMPT_PREAMBLE =
 export interface SkillInfo {
   name: string
   description?: string
-  location: string // absolute path to SKILL.md
+  location: string // absolute path to SKILL.md (fs) or logical base (data)
   content: string // body after frontmatter
+  /** Internal origin discriminator; "fs" ⇒ on-disk (default), "logical" ⇒ data. */
+  origin?: "fs" | "logical"
+  /** Logical resource list (data-sourced skills only). */
+  resources?: string[]
+  /** Logical base, e.g. skill://name/ (data-sourced skills only). */
+  base?: string
+}
+
+/** A skill supplied directly as data, bypassing the filesystem (SPEC.md §3, S1). */
+export interface SkillDef {
+  name: string
+  description?: string
+  content: string
+  /** Optional logical resource names surfaced in the invoke-time <skill_files> block. */
+  resources?: string[]
+  /** Optional logical base; defaults to `skill://<name>/`. */
+  base?: string
+}
+
+/** Why a candidate SKILL.md did not become a skill (SPEC.md §3, S3). */
+export type SkillSkipReason = "missing-name" | "malformed-frontmatter" | "duplicate-name" | "unreadable"
+
+export interface SkillSkip {
+  location: string
+  reason: SkillSkipReason
+}
+
+/** Result of a list-only validate pass (SPEC.md §3, S3). */
+export interface SkillInventory {
+  skills: SkillInfo[]
+  skipped: SkillSkip[]
+}
+
+/** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
+export interface LoadSkillsOptions {
+  dirs?: string | string[]
+  skills?: SkillDef[]
+  /** Per-agent allowlist keyed on skill name; same semantics as the MCP tools filter. */
+  filter?: Record<string, boolean>
+  /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files>. */
+  sampleLimit?: number
 }
 
 /**
  * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
  * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
  * values all resolve correctly. Scalar values are coerced to strings.
+ *
+ * `malformed` is true only when fences are present but the YAML fails to parse —
+ * distinguishing a malformed header from a body with no frontmatter, so the
+ * inventory (S3) can report the right skip reason. loadSkills' behavior is
+ * unchanged: a malformed header yields no name and the skill is skipped.
  */
-function parseFrontmatter(text: string): { data: Record<string, string>; content: string } {
+function parseFrontmatter(text: string): { data: Record<string, string>; content: string; malformed: boolean } {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
-  if (!match) return { data: {}, content: text }
+  if (!match) return { data: {}, content: text, malformed: false }
   const data: Record<string, string> = {}
   let parsed: unknown
+  let malformed = false
   try {
     parsed = parseYaml(match[1])
   } catch {
     parsed = null
+    malformed = true
   }
   if (parsed && typeof parsed === "object") {
     for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
@@ -55,7 +108,7 @@ function parseFrontmatter(text: string): { data: Record<string, string>; content
       }
     }
   }
-  return { data, content: match[2] }
+  return { data, content: match[2], malformed }
 }
 
 function walkSkillFiles(root: string): string[] {
@@ -150,50 +203,145 @@ function sampleSiblingFiles(dir: string, limit = 10): string[] {
   return out
 }
 
-export interface SkillSource {
-  skills: Record<string, SkillInfo>
-  tool: Tool
-  /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
-  prompt(): string
+/** One raw candidate before cross-source dedupe: a parsed skill OR a typed skip. */
+interface RawCandidate {
+  info?: SkillInfo
+  skip?: SkillSkip
 }
 
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export function loadSkills(dirs: string | string[]): SkillSource {
-  const roots = Array.isArray(dirs) ? dirs : [dirs]
-  const skills: Record<string, SkillInfo> = {}
-
-  for (const root of roots) {
-    let isDir = false
+/** Discover candidates under one on-disk root (order = discovery order). */
+function candidatesFromDir(root: string): RawCandidate[] {
+  const out: RawCandidate[] = []
+  let isDir = false
+  try {
+    isDir = statSync(root).isDirectory()
+  } catch {
+    isDir = false
+  }
+  if (!isDir) {
+    console.warn(`[toolnexus] skills dir not found: ${root}`)
+    return out
+  }
+  for (const file of walkSkillFiles(root)) {
+    let text: string
     try {
-      isDir = statSync(root).isDirectory()
+      text = readFileSync(file, "utf8")
     } catch {
-      isDir = false
+      out.push({ skip: { location: file, reason: "unreadable" } })
+      continue
     }
-    if (!isDir) {
-      console.warn(`[toolnexus] skills dir not found: ${root}`)
+    const { data, content, malformed } = parseFrontmatter(text)
+    if (malformed) {
+      out.push({ skip: { location: file, reason: "malformed-frontmatter" } })
       continue
     }
-    for (const file of walkSkillFiles(root)) {
-      let text: string
-      try {
-        text = readFileSync(file, "utf8")
-      } catch {
-        continue
-      }
-      const { data, content } = parseFrontmatter(text)
-      if (!data.name) continue
-      if (skills[data.name]) {
-        console.warn(`[toolnexus] duplicate skill name "${data.name}" (${file}) — keeping first`)
-        continue
-      }
-      skills[data.name] = {
-        name: data.name,
-        description: data.description,
-        location: file,
-        content,
-      }
+    if (!data.name) {
+      out.push({ skip: { location: file, reason: "missing-name" } })
+      continue
     }
+    out.push({ info: { name: data.name, description: data.description, location: file, content, origin: "fs" } })
   }
+  return out
+}
+
+/** Turn data-supplied skill defs into candidates (logical origin). */
+function candidatesFromDefs(defs: SkillDef[]): RawCandidate[] {
+  return defs.map((d): RawCandidate => {
+    if (!d.name) return { skip: { location: d.base ?? "skill://", reason: "missing-name" } }
+    const base = d.base && d.base.length > 0 ? d.base : `skill://${d.name}/`
+    return {
+      info: {
+        name: d.name,
+        description: d.description,
+        location: base,
+        content: d.content ?? "",
+        origin: "logical",
+        resources: d.resources ?? [],
+        base,
+      },
+    }
+  })
+}
+
+/** Collect ordered candidates from dirs then data defs. */
+function collectCandidates(opts: LoadSkillsOptions): RawCandidate[] {
+  const roots = opts.dirs === undefined ? [] : Array.isArray(opts.dirs) ? opts.dirs : [opts.dirs]
+  const cands: RawCandidate[] = []
+  for (const root of roots) cands.push(...candidatesFromDir(root))
+  if (opts.skills) cands.push(...candidatesFromDefs(opts.skills))
+  return cands
+}
+
+/** Dedupe candidates by name (first-wins); later duplicates become skips. */
+function mergeCandidates(cands: RawCandidate[]): { skills: Record<string, SkillInfo>; skipped: SkillSkip[] } {
+  const skills: Record<string, SkillInfo> = {}
+  const skipped: SkillSkip[] = []
+  for (const c of cands) {
+    if (c.skip) {
+      skipped.push(c.skip)
+      continue
+    }
+    const info = c.info!
+    if (skills[info.name]) {
+      console.warn(`[toolnexus] duplicate skill name "${info.name}" (${info.location}) — keeping first`)
+      skipped.push({ location: info.location, reason: "duplicate-name" })
+      continue
+    }
+    skills[info.name] = info
+  }
+  return { skills, skipped }
+}
+
+/**
+ * Apply the per-agent skill allowlist (S2), semantics identical to the MCP
+ * per-server tools filter and builtins: nil/empty ⇒ all; ≥1 true ⇒ allowlist
+ * (only true-mapped names); only-false ⇒ drop-list over all-on; unknown names
+ * are ignored and warned once.
+ */
+function applySkillsFilter(
+  skills: Record<string, SkillInfo>,
+  filter: Record<string, boolean> | undefined,
+): Record<string, SkillInfo> {
+  if (!filter) return skills
+  const keys = Object.keys(filter)
+  if (keys.length === 0) return skills
+  const hasTrue = keys.some((k) => filter[k] === true)
+  for (const k of keys) {
+    if (!(k in skills)) console.warn(`[toolnexus] skill filter name "${k}" matched no skill`)
+  }
+  const out: Record<string, SkillInfo> = {}
+  for (const [name, info] of Object.entries(skills)) {
+    if (hasTrue ? filter[name] === true : filter[name] !== false) out[name] = info
+  }
+  return out
+}
+
+export interface SkillSource {
+  skills: Record<string, SkillInfo>
+  tool: Tool
+  /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
+  prompt(): string
+}
+
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+export function listSkills(input: string | string[] | LoadSkillsOptions): SkillInventory {
+  const opts: LoadSkillsOptions =
+    typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
+  const merged = mergeCandidates(collectCandidates(opts))
+  return { skills: Object.values(merged.skills), skipped: merged.skipped }
+}
+
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource {
+  const opts: LoadSkillsOptions =
+    typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
+  const sampleLimit = opts.sampleLimit ?? 0
+  const merged = mergeCandidates(collectCandidates(opts))
+  const skills = applySkillsFilter(merged.skills, opts.filter)
 
   const tool: Tool = {
     name: "skill",
@@ -214,10 +362,28 @@ export function loadSkills(dirs: string | string[]): SkillSource {
           isError: true,
         }
       }
-      const dir = path.dirname(info.location)
-      const base = pathToFileURL(dir).href
-      const files = sampleSiblingFiles(dir)
-      const output = [
+      // effLimit: 0 ⇒ default 10 (byte-identical to today), n>0 ⇒ cap, -1 ⇒ omit.
+      const effLimit = sampleLimit === 0 ? 10 : sampleLimit
+      let base: string
+      let files: string[]
+      let metaDir: string
+      // Emit the <skill_files> block: always for fs skills (byte-identical, even
+      // when empty), only when a data skill actually carries resources (an
+      // instruction-only data skill omits it). Never when sampling is disabled.
+      let emitFiles = effLimit !== -1
+      if (info.origin === "logical") {
+        base = info.base ?? `skill://${info.name}/`
+        const res = info.resources ?? []
+        if (res.length === 0) emitFiles = false
+        files = effLimit > 0 ? res.slice(0, effLimit) : res
+        metaDir = base
+      } else {
+        const dir = path.dirname(info.location)
+        base = pathToFileURL(dir).href
+        files = effLimit === -1 ? [] : sampleSiblingFiles(dir, effLimit)
+        metaDir = dir
+      }
+      const lines = [
         `<skill_content name="${info.name}">`,
         `# Skill: ${info.name}`,
         "",
@@ -225,14 +391,18 @@ export function loadSkills(dirs: string | string[]): SkillSource {
         "",
         `Base directory for this skill: ${base}`,
         "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
-        "Note: file list is sampled.",
-        "",
-        "<skill_files>",
-        files.map((f) => `<file>${f}</file>`).join("\n"),
-        "</skill_files>",
-        "</skill_content>",
-      ].join("\n")
-      return { output, isError: false, metadata: { name: info.name, dir } }
+      ]
+      if (emitFiles) {
+        lines.push(
+          "Note: file list is sampled.",
+          "",
+          "<skill_files>",
+          files.map((f) => `<file>${f}</file>`).join("\n"),
+          "</skill_files>",
+        )
+      }
+      lines.push("</skill_content>")
+      return { output: lines.join("\n"), isError: false, metadata: { name: info.name, dir: metaDir } }
     },
   }
 

package/src/toolkit.ts

@@ -4,7 +4,7 @@
  */
 import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js"
 import { loadMcp, type McpSource } from "./mcp.js"
-import { loadSkills, type SkillSource } from "./skill.js"
+import { loadSkills, type SkillDef, type SkillSource } from "./skill.js"
 import { selectBuiltins, type BuiltinsConfig } from "./builtin.js"
 import { agentTools, parseAgentsConfig, type Agent } from "./a2a.js"
 import { startA2AServer, type A2AConfig, type OnTask, type ServeHandle } from "./serve.js"
@@ -15,6 +15,14 @@ import type { Client } from "./client.js"
 export interface ToolkitOptions {
   mcpConfig?: string | object
   skillsDir?: string | string[]
+  /** Skills supplied as data, bypassing the filesystem (§3, S1). */
+  skills?: SkillDef[]
+  /** Lazy provider of data-supplied skills, resolved once at toolkit build (§3, S1). */
+  skillProvider?: () => SkillDef[] | Promise<SkillDef[]>
+  /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
+  skillsFilter?: Record<string, boolean>
+  /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
+  skillSampleLimit?: number
   extraTools?: Tool[]
   /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
   builtins?: BuiltinsConfig
@@ -59,7 +67,28 @@ export class Toolkit {
 
   static async create(opts: ToolkitOptions): Promise<Toolkit> {
     const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined
-    const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined
+    // Skills come from directories, in-memory data, and/or a lazy provider (§3,
+    // S1). The provider is resolved here (create() is async) and merged with the
+    // data list; a provider failure is isolated so other sources still load.
+    let skill: SkillSource | undefined
+    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+      let providerDefs: SkillDef[] = []
+      if (opts.skillProvider) {
+        try {
+          providerDefs = await opts.skillProvider()
+        } catch (e) {
+          console.warn(`[toolnexus] skill provider failed: ${e instanceof Error ? e.message : String(e)}`)
+          providerDefs = []
+        }
+      }
+      const dataDefs = [...(opts.skills ?? []), ...providerDefs]
+      skill = loadSkills({
+        dirs: opts.skillsDir,
+        skills: dataDefs.length > 0 ? dataDefs : undefined,
+        filter: opts.skillsFilter,
+        sampleLimit: opts.skillSampleLimit,
+      })
+    }
     // The toggle comes from the `builtins` option, or a top-level `builtins`
     // key on a parsed config object — same precedence as MCP's isEnabled.
     let builtinsCfg = opts.builtins