@kaleidorg/mind 0.0.1 → 0.1.0

package/skills/kaleido-wallet/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: kaleido-wallet
+description: "Manage a KaleidoSwap Lightning + RGB wallet: check BTC and asset balances, get a receive address, create or pay Lightning invoices, send on-chain BTC, open or list channels. Triggers when the user asks about their balance, wants to receive or send funds, pay an invoice, or manage Lightning channels."
+tools: wdk_get_balances, wdk_get_asset_balance, wdk_get_address, wdk_create_ln_invoice, wdk_pay_invoice, wdk_send_btc, wdk_list_channels, wdk_open_channel, wdk_get_node_info
+triggers: balance, receive, address, send, pay, invoice, channel, deposit, withdraw, funds
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+  surface: "kaleido-mcp (WDK node)"
+---
+
+# KaleidoSwap wallet
+
+Operate the user's KaleidoSwap node (Lightning + RGB assets) through the
+`wdk_*` MCP tools.
+
+## Rules
+
+- **Read before you write.** Check the balance (`wdk_get_balances`) before any
+  send or channel open, and confirm the node is healthy (`wdk_get_node_info`).
+- **Confirm every spend.** State the amount, destination, and resulting balance,
+  then wait for explicit approval before calling `wdk_send_btc`,
+  `wdk_pay_invoice`, or `wdk_open_channel`.
+- **Match the rail to the asset.** Lightning for fast BTC/asset payments,
+  on-chain for settlement or channel funding. Use `wdk_get_asset_balance` for
+  RGB assets (USDT, XAUT, …).
+- Never reveal seeds or private keys — this skill operates a node, it is not a
+  key vault.

package/src/engine.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Engine + tool-calling tests.
+ *
+ * These exercise the full agentic loop deterministically — no model, no
+ * device — using a scripted mock provider and mock tool sources. This is the
+ * fastest way to verify tools are selected, executed, fed back, and gated by
+ * confirmation, exactly as they would be with a real QVAC model.
+ *
+ *   pnpm --filter @kaleidorg/mind test
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { Engine } from './engine.js';
+import { ToolRegistry } from './tools/registry.js';
+import { InProcessToolSource } from './tools/in-process.js';
+import type { LLMProvider, TurnInput, TurnOutput } from './providers/types.js';
+import type { ToolCall } from './types.js';
+
+/**
+ * A scripted provider: each entry in `script` is one turn's output. When it
+ * returns tool calls, the engine executes them and calls the provider again
+ * for the next scripted turn.
+ */
+function scriptedProvider(script: Array<{ text: string; toolCalls?: ToolCall[] }>): LLMProvider {
+  let turn = 0;
+  return {
+    name: 'scripted',
+    async runTurn(input: TurnInput): Promise<TurnOutput> {
+      const step = script[Math.min(turn, script.length - 1)];
+      turn += 1;
+      // stream the text so onToken paths are exercised
+      input.onToken?.(step.text);
+      return {
+        text: step.text,
+        rawContent: step.text,
+        toolCalls: step.toolCalls ?? [],
+        requestId: `req-${turn}`,
+      };
+    },
+  };
+}
+
+const balanceTool = {
+  name: 'get_balance',
+  description: 'Get the wallet balance in sats',
+  parameters: {},
+  handler: vi.fn(async () => ({ sats: 50_000 })),
+};
+
+const payTool = {
+  name: 'pay_invoice',
+  description: 'Pay a Lightning invoice',
+  parameters: {},
+  requiresConfirmation: true,
+  handler: vi.fn(async (args: Record<string, unknown>) => ({ paid: true, to: args.invoice })),
+};
+
+function freshTools() {
+  balanceTool.handler.mockClear();
+  payTool.handler.mockClear();
+  return new ToolRegistry([new InProcessToolSource('wallet', [balanceTool, payTool])]);
+}
+
+describe('Engine agentic loop', () => {
+  it('calls a read tool, feeds the result back, and returns a final answer', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // turn 1: call tool
+        { text: 'You have 50,000 sats.' }, // turn 2: final answer (sees the result)
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: "what's my balance?" }]);
+
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('You have 50,000 sats.');
+    expect(res.turns).toBe(2);
+    expect(res.toolCalls).toHaveLength(1);
+    expect(res.toolCalls[0].result).toEqual({ sats: 50_000 });
+  });
+
+  it('pauses money tools for confirmation and executes on approval', async () => {
+    const onConfirm = vi.fn(async () => ({ approved: true }));
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc1' } }] },
+        { text: 'Sent ✅' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
+
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(payTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('Sent ✅');
+    expect(res.toolCalls[0].result).toEqual({ paid: true, to: 'lnbc1' });
+  });
+
+  it('does NOT execute a money tool when the user declines', async () => {
+    const onConfirm = vi.fn(async () => ({ approved: false, reason: 'cancelled' }));
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc1' } }] },
+        { text: 'Okay, cancelled.' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
+
+    expect(payTool.handler).not.toHaveBeenCalled();
+    expect(res.toolCalls[0].result).toMatchObject({ declined: true, reason: 'cancelled' });
+    expect(res.text).toBe('Okay, cancelled.');
+  });
+
+  it('chains multiple tool calls across turns', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'get_balance', arguments: {} }] },
+        { text: '', toolCalls: [{ name: 'pay_invoice', arguments: { invoice: 'lnbc2' } }] },
+        { text: 'Checked balance, then paid.' },
+      ]),
+      tools: freshTools(),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'check then pay' }], {
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(payTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.turns).toBe(3);
+    expect(res.toolCalls.map((c) => c.name)).toEqual(['get_balance', 'pay_invoice']);
+  });
+
+  it('stops at maxTurns if the model never stops calling tools', async () => {
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // always calls a tool
+      ]),
+      tools: freshTools(),
+      defaultMaxTurns: 3,
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'go' }]);
+
+    expect(res.turns).toBe(3);
+    expect(balanceTool.handler).toHaveBeenCalledTimes(3);
+  });
+
+  it('surfaces a tool error as a result instead of throwing', async () => {
+    const boom = {
+      name: 'boom',
+      description: 'throws',
+      parameters: {},
+      handler: vi.fn(async () => {
+        throw new Error('kaboom');
+      }),
+    };
+    const engine = new Engine({
+      provider: scriptedProvider([
+        { text: '', toolCalls: [{ name: 'boom', arguments: {} }] },
+        { text: 'handled the error' },
+      ]),
+      tools: new ToolRegistry([new InProcessToolSource('x', [boom])]),
+    });
+
+    const res = await engine.runAgentic([{ role: 'user', content: 'go' }]);
+    expect(res.toolCalls[0].result).toMatchObject({ error: 'kaboom' });
+    expect(res.text).toBe('handled the error');
+  });
+});
+
+describe('ToolRegistry', () => {
+  it('merges tools from multiple sources and routes calls to the owner', async () => {
+    const a = new InProcessToolSource('a', [
+      { name: 'one', description: '', parameters: {}, handler: async () => 'from-a' },
+    ]);
+    const b = new InProcessToolSource('b', [
+      { name: 'two', description: '', parameters: {}, handler: async () => 'from-b' },
+    ]);
+    const reg = new ToolRegistry([a, b]);
+
+    const tools = await reg.listTools();
+    expect(tools.map((t) => t.name).sort()).toEqual(['one', 'two']);
+    expect(await reg.execute('one', {})).toBe('from-a');
+    expect(await reg.execute('two', {})).toBe('from-b');
+  });
+
+  it('first source wins on a name clash', async () => {
+    const a = new InProcessToolSource('a', [
+      { name: 'dup', description: 'A', parameters: {}, handler: async () => 'a' },
+    ]);
+    const b = new InProcessToolSource('b', [
+      { name: 'dup', description: 'B', parameters: {}, handler: async () => 'b' },
+    ]);
+    const reg = new ToolRegistry([a, b]);
+    const tools = await reg.listTools();
+    expect(tools).toHaveLength(1);
+    expect(await reg.execute('dup', {})).toBe('a');
+  });
+});

package/src/engine.ts

@@ -37,6 +37,11 @@ export interface AgenticOptions {
   onToolCall?: (call: { name: string; arguments: Record<string, unknown> }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
   onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  /**
+   * Restrict the tools exposed to the model this run (progressive disclosure).
+   * Typically the active skill's tool list — see SkillRegistry.compose().
+   */
+  allowedTools?: string[];
   signal?: AbortSignal;
 }
 
@@ -45,6 +50,10 @@ export interface AgenticResult {
   turns: number;
   toolCalls: ToolResult[];
   requestId?: string;
+  /** Full conversation incl. assistant/tool frames — for logging / datasets. */
+  messages: Message[];
+  /** Wall-clock duration of the whole agentic run, ms. */
+  latencyMs: number;
 }
 
 export class Engine {
@@ -65,8 +74,13 @@ export class Engine {
     const hasSystem = messages.some((m) => m.role === 'system');
     const system = hasSystem ? undefined : this.defaultSystem;
 
+    const startedAt = Date.now();
     const history: Message[] = [...messages];
-    const allTools = await this.registry.listTools();
+    const registryTools = await this.registry.listTools();
+    // Progressive disclosure: expose only the active skill's tools when set.
+    const allTools = opts.allowedTools
+      ? registryTools.filter((t) => opts.allowedTools!.includes(t.name))
+      : registryTools;
     const executed: ToolResult[] = [];
     let lastRequestId: string | undefined;
     let finalText = '';
@@ -124,7 +138,18 @@ export class Engine {
       }
     }
 
-    return { text: finalText, turns, toolCalls: executed, requestId: lastRequestId };
+    // Append the final answer so the returned conversation is complete (the
+    // loop breaks before pushing the no-tool-call turn).
+    if (finalText) history.push({ role: 'assistant', content: finalText });
+
+    return {
+      text: finalText,
+      turns,
+      toolCalls: executed,
+      requestId: lastRequestId,
+      messages: history,
+      latencyMs: Date.now() - startedAt,
+    };
   }
 
   async cancel(requestId: string): Promise<void> {

package/src/index.ts

@@ -23,9 +23,26 @@ export type { ToolSource } from './tools/source.js';
 export { InProcessToolSource } from './tools/in-process.js';
 export type { InProcessTool } from './tools/in-process.js';
 export { ToolRegistry } from './tools/registry.js';
+export {
+  createL402ToolSource,
+  parseL402Challenge,
+  bolt11AmountSats,
+} from './tools/l402.js';
+export type { L402Options, L402PayResult } from './tools/l402.js';
 
 export { Engine } from './engine.js';
 export type { EngineOptions, AgenticOptions, AgenticResult } from './engine.js';
 
+export {
+  SkillRegistry,
+  parseSkill,
+  keywordSelector,
+  READ_REFERENCE_TOOL,
+} from './skills/registry.js';
+export { createSkillReferenceToolSource } from './skills/reference-source.js';
+export { skillsFromBundle } from './skills/bundle.js';
+export type { SkillBundle, BundledSkill } from './skills/bundle.js';
+export type { Skill, SkillReference, SkillSelector } from './skills/types.js';
+
 export { TurnLogger, defaultMask } from './logger.js';
 export type { TurnLog, Device, LoggerIO, LoggerOptions } from './logger.js';

package/src/skills/bundle.ts

@@ -0,0 +1,42 @@
+/**
+ * Skill bundle — the RN-safe counterpart to the Node fs loader.
+ *
+ * React Native has no filesystem, so a skill folder can't be read at runtime.
+ * Instead a build step serialises the skills into a `SkillBundle` (plain JSON:
+ * each skill's raw SKILL.md text + its reference files), and the app rehydrates
+ * them here with `skillsFromBundle()`. Same skills, same SKILL.md authoring —
+ * just delivered as data instead of files.
+ *
+ * Pure, dependency-free, no fs/url imports — safe to import from the package's
+ * main entry on any host.
+ */
+
+import type { Skill, SkillReference } from './types.js';
+import { parseSkill } from './registry.js';
+
+/** One serialised skill: the SKILL.md text + its reference files. */
+export interface BundledSkill {
+  /** Folder name (informational; the real name comes from the frontmatter). */
+  dir?: string;
+  /** Raw SKILL.md contents. */
+  markdown: string;
+  /** references/*.md files. */
+  references?: SkillReference[];
+}
+
+/** A bundle of skills produced by the bundler script. */
+export interface SkillBundle {
+  version: 1;
+  skills: BundledSkill[];
+}
+
+/** Rehydrate Skills from a bundle (RN-safe — no filesystem). */
+export function skillsFromBundle(bundle: SkillBundle): Skill[] {
+  if (!bundle || bundle.version !== 1 || !Array.isArray(bundle.skills)) {
+    throw new Error('skillsFromBundle: not a valid v1 SkillBundle');
+  }
+  return bundle.skills.map((b) => ({
+    ...parseSkill(b.markdown, b.references),
+    dir: b.dir,
+  }));
+}

package/src/skills/loader.ts

@@ -0,0 +1,63 @@
+/**
+ * Skill loader — reads Claude-style Agent Skill folders from disk. NODE ONLY.
+ *
+ * Import from `@kaleidorg/mind/skills` on Node hosts (desktop sidecar,
+ * kaleidoagent). React Native has no filesystem — there, build skills with
+ * `SkillRegistry.addMarkdown(text, references)` from bundled strings instead.
+ *
+ * Layout (Anthropic Agent Skills spec, e.g. bitrefill/agents):
+ *
+ *   skills/
+ *     bitrefill/
+ *       SKILL.md
+ *       references/
+ *         mcp.md
+ *         cli.md
+ *         …
+ *
+ * `loadSkillsDir(root)` returns one Skill per SKILL.md found, with every
+ * reference markdown read into `skill.references` for progressive disclosure.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Skill, SkillReference } from './types.js';
+import { parseSkill } from './registry.js';
+
+/**
+ * Absolute path to the skills shipped inside this package
+ * (`@kaleidorg/mind/skills`). Resolves relative to the compiled loader, so it
+ * works from any host that installs the package. Override with an explicit dir
+ * when you keep skills elsewhere.
+ */
+export function packagedSkillsDir(): string {
+  // dist/skills/loader.js → ../../skills == <package root>/skills
+  return fileURLToPath(new URL('../../skills/', import.meta.url));
+}
+
+/** Load one skill folder containing a SKILL.md (+ optional references/). */
+export function loadSkillFromDir(dir: string): Skill {
+  const skillFile = join(dir, 'SKILL.md');
+  if (!existsSync(skillFile)) throw new Error(`No SKILL.md in ${dir}`);
+  const markdown = readFileSync(skillFile, 'utf8');
+
+  const refDir = join(dir, 'references');
+  const references: SkillReference[] = existsSync(refDir)
+    ? readdirSync(refDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((name) => ({ name, content: readFileSync(join(refDir, name), 'utf8') }))
+    : [];
+
+  return { ...parseSkill(markdown, references), dir };
+}
+
+/** Load every skill folder under `root` (each a dir with a SKILL.md). */
+export function loadSkillsDir(root: string): Skill[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(root, e.name, 'SKILL.md')))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((e) => loadSkillFromDir(join(root, e.name)));
+}

package/src/skills/reference-source.ts

@@ -0,0 +1,60 @@
+/**
+ * Skill reference tool source — the read-side of Agent-Skills progressive
+ * disclosure.
+ *
+ * Exposes one tool, `read_skill_reference({ file, skill? })`, that returns the
+ * contents of a `references/*.md` file bundled with a skill. The brain enters a
+ * skill (its SKILL.md playbook lists the reference files), then pulls in only
+ * the reference it needs for the current step — instead of every doc being in
+ * context at once.
+ *
+ * Pure in-process: it reads from the SkillRegistry's already-loaded reference
+ * strings, so it works on every host (React Native included) once the skills
+ * are loaded. No filesystem, no network.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from '../tools/source.js';
+import { SkillRegistry, READ_REFERENCE_TOOL } from './registry.js';
+
+export function createSkillReferenceToolSource(registry: SkillRegistry): ToolSource {
+  const tool: ToolDef = {
+    name: READ_REFERENCE_TOOL,
+    description:
+      'Read a reference document bundled with the active skill (its SKILL.md ' +
+      'lists the available files). Use this to pull in the detailed instructions ' +
+      'for a step — e.g. the MCP, CLI, or API guide — before acting.',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Reference filename, e.g. "mcp.md"' },
+        skill: { type: 'string', description: 'Optional skill name to scope the lookup' },
+      },
+      required: ['file'],
+    },
+  };
+
+  async function execute(_name: string, args: Record<string, unknown>): Promise<unknown> {
+    const file = String(args.file ?? '').trim();
+    if (!file) throw new Error('read_skill_reference: file is required');
+    const skill = args.skill ? String(args.skill) : undefined;
+    const ref = registry.reference(file, skill);
+    if (!ref) {
+      const available = registry
+        .references()
+        .map((r) => `${r.skill}/${r.name}`)
+        .join(', ');
+      throw new Error(
+        `read_skill_reference: "${file}" not found. Available: ${available || '(none)'}`,
+      );
+    }
+    return ref.content;
+  }
+
+  return {
+    id: 'skill-references',
+    listTools: () => [tool],
+    has: (name) => name === READ_REFERENCE_TOOL,
+    execute,
+  };
+}

package/src/skills/registry.ts

@@ -0,0 +1,183 @@
+/**
+ * SkillRegistry — holds skills, parses SKILL.md files, selects per query, and
+ * composes the system prompt for the selected skill.
+ *
+ * Selection is pluggable. The default is a fast keyword heuristic (no model
+ * call); a host can inject a model-driven or embedding selector instead.
+ */
+
+import type { Skill, SkillReference, SkillSelector } from './types.js';
+
+/** Tool name the reference source exposes for progressive disclosure. */
+export const READ_REFERENCE_TOOL = 'read_skill_reference';
+
+/**
+ * Parse a SKILL.md file: a YAML-ish frontmatter block (name/description/tools/
+ * triggers) followed by the instruction body.
+ *
+ *   ---
+ *   name: portfolio-manager
+ *   description: Rebalance BTC/USDT/XAUT to target allocations.
+ *   tools: get_balance, kaleidoswap_get_quote, kaleidoswap_place_order
+ *   triggers: rebalance, allocation, portfolio
+ *   ---
+ *   <instructions…>
+ */
+/** Strip wrapping single/double quotes from a frontmatter value. */
+function unquote(v: string): string {
+  const t = v.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+export function parseSkill(markdown: string, references?: SkillReference[]): Skill {
+  const fm = markdown.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  const meta: Record<string, string> = {};
+  let body = markdown;
+  if (fm) {
+    body = fm[2] ?? '';
+    for (const line of (fm[1] ?? '').split('\n')) {
+      // Flat `key: value` lines (incl. indented keys under a nested `metadata:`
+      // block, which fold into the same map — we don't need YAML nesting here).
+      const m = line.match(/^\s*([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/);
+      if (m && m[1]) meta[m[1].toLowerCase()] = unquote(m[2] ?? '');
+    }
+  }
+  const list = (v?: string) =>
+    v
+      ? v.split(',').map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  if (!meta.name) throw new Error('SKILL.md missing `name` in frontmatter');
+
+  // Everything that isn't a first-class field becomes metadata.
+  const KNOWN = new Set(['name', 'description', 'tools', 'triggers']);
+  const metadata: Record<string, string> = {};
+  for (const [k, v] of Object.entries(meta)) if (!KNOWN.has(k)) metadata[k] = v;
+
+  return {
+    name: meta.name,
+    description: meta.description ?? '',
+    instructions: body.trim(),
+    tools: list(meta.tools),
+    triggers: list(meta.triggers),
+    metadata: Object.keys(metadata).length ? metadata : undefined,
+    references: references && references.length ? references : undefined,
+  };
+}
+
+// Common words that shouldn't count toward a skill match.
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'you', 'your', 'what', 'this', 'that', 'with', 'from',
+  'have', 'has', 'are', 'was', 'can', 'will', 'please', 'today', 'now', 'get',
+  'show', 'tell', 'how', 'much', 'many', 'about', 'into', 'over',
+]);
+
+/** Default selector: score by meaningful keyword overlap; triggers weigh most. */
+export const keywordSelector: SkillSelector = {
+  select(query, skills) {
+    const q = query.toLowerCase();
+    const words = new Set(
+      q.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w)),
+    );
+    let best: Skill | null = null;
+    let bestScore = 0;
+    for (const skill of skills) {
+      const haystack = `${skill.description} ${(skill.triggers ?? []).join(' ')}`.toLowerCase();
+      const hayWords = haystack.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
+      let score = 0;
+      for (const w of hayWords) if (words.has(w)) score += 1;
+      // Strong boost for an explicit trigger appearing in the query.
+      for (const t of skill.triggers ?? []) if (q.includes(t.toLowerCase())) score += 3;
+      if (score > bestScore) {
+        bestScore = score;
+        best = skill;
+      }
+    }
+    // Require a real signal, not a single incidental word overlap.
+    return bestScore >= 2 ? best : null;
+  },
+};
+
+export class SkillRegistry {
+  private readonly skills: Skill[] = [];
+  private readonly selector: SkillSelector;
+
+  constructor(skills: Skill[] = [], selector: SkillSelector = keywordSelector) {
+    this.skills = [...skills];
+    this.selector = selector;
+  }
+
+  add(skill: Skill): this {
+    this.skills.push(skill);
+    return this;
+  }
+
+  /** Add a skill from raw SKILL.md text (+ optional reference files). */
+  addMarkdown(markdown: string, references?: SkillReference[]): this {
+    return this.add(parseSkill(markdown, references));
+  }
+
+  /** All reference files across skills, tagged with their owning skill. */
+  references(): Array<SkillReference & { skill: string }> {
+    return this.skills.flatMap((s) =>
+      (s.references ?? []).map((r) => ({ ...r, skill: s.name })),
+    );
+  }
+
+  /** Look up a reference file by name (optionally scoped to one skill). */
+  reference(file: string, skill?: string): SkillReference | undefined {
+    const base = file.replace(/^references\//, '');
+    for (const s of this.skills) {
+      if (skill && s.name !== skill) continue;
+      const hit = (s.references ?? []).find((r) => r.name === base || r.name === file);
+      if (hit) return hit;
+    }
+    return undefined;
+  }
+
+  list(): Skill[] {
+    return [...this.skills];
+  }
+
+  get(name: string): Skill | undefined {
+    return this.skills.find((s) => s.name === name);
+  }
+
+  /** Pick the most relevant skill for a query (null = none). */
+  select(query: string): Skill | null {
+    return this.selector.select(query, this.skills);
+  }
+
+  /**
+   * Compose the effective system prompt for a skill: the base prompt + the
+   * skill's playbook. The returned `allowedTools` should be passed to
+   * `engine.runAgentic(..., { allowedTools })` for progressive tool disclosure.
+   */
+  compose(base: string, skill: Skill | null): { system: string; allowedTools?: string[] } {
+    if (!skill) return { system: base };
+
+    let system = `${base}\n\n## Active skill: ${skill.name}\n${skill.instructions}`.trim();
+
+    // Progressive disclosure: tell the model the reference files exist and how
+    // to pull one in, rather than dumping them all into context.
+    const refs = skill.references ?? [];
+    if (refs.length) {
+      const names = refs.map((r) => r.name).join(', ');
+      system +=
+        `\n\n## Reference files\nThis skill has detailed reference docs: ${names}. ` +
+        `When you need the detail for a step, call \`${READ_REFERENCE_TOOL}\` with the ` +
+        `filename (e.g. {"file":"${refs[0]!.name}"}) to read it before acting.`;
+    }
+
+    // When the skill scopes tools, keep the reference reader reachable too.
+    const allowedTools = skill.tools
+      ? refs.length
+        ? [...skill.tools, READ_REFERENCE_TOOL]
+        : skill.tools
+      : undefined;
+    return { system, allowedTools };
+  }
+}