xitto-kernel 0.3.5 → 0.3.8

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.3.8
+
+- **技能自我維護（用量戳記 + 漂移偵測）**：結晶後不再靜止,技能庫會自我體檢。
+  - **A 用量戳記**：`skill` 載入時記 `usedCount` / `lastUsedAt`（寫進 frontmatter,不動 body）
+  - **B 漂移偵測**：新增 `skills_check` 工具 + `api.skills.check()`——重跑每個技能存的 verify,
+    仍 exit 0 標 `ok`、失效標 `stale`（清/設 frontmatter）；無 verify 區塊的技能回 `no-verify`(不誤判)
+  - prompt 與 `/skills` 清單顯示用量與 `⚠ 已失效待修`；`/skills check` 觸發複查
+  - frontmatter 簡易解析/patch（splitFront/joinFront/extractVerify）；複用 v0.3.7 存下的 verify
+  - 4 個新測試（用量累加 / ok→stale→修復 / no-verify 不誤判 / api.skills.check）+ 真實 verify 端到端
+    （載入計次、刪檔→stale、復原→ok）。測試 143/143。
+
+## 0.3.7
+
+- **技能結晶政策閘門（驗證才算數）**：每個自寫技能新增時必須有明確目標 + 通過的驗證,否則不落地。
+  - `skill_save` 新增必填 `goal`（明確目標）與 `verify`（驗證指令）
+  - **verify 在沙箱實際執行,exit 0 才新增**；未過則拒絕並回傳輸出供 agent 修正
+  - 危險驗證指令一律擋（複用 `dangerousReason`/`sandboxViolation`）；開沙箱時 Seatbelt 包執行
+  - 落地檔記 `goal`/`verified: true`/`verifiedAt` + `## 驗證（已通過）` 區塊（為日後重驗/衰減鋪路）
+  - kernel 新增 `runVerify`（注入 createSkills）；確保結晶的是「已驗證的成功」而非「宣稱的成功」
+  - 7 個測試 + 真實 runVerify 端到端（通過→新增 / 失敗→拒絕 / 危險→擋 / 缺 goal→拒）
+
+## 0.3.6
+
+- **自我結晶技能（結晶層）**：agent 摸出可重複流程時自己寫成技能,跨任務/跨 session 複用。
+  - 新增 kernel 內建工具 `skill_save`（把流程結晶成 `.xitto-kernel/<pack>/skills/<name>.md`,含 frontmatter description）
+  - `skill` 載入改為**熱掃描**：本 session 剛結晶的技能即時可載；未來 session 自動列入「可用技能」
+  - `skill`/`skill_save` **永遠可用**（即使尚無技能,才能結晶第一個）；name slug 化防路徑穿越,同名覆蓋
+  - 漸進揭露不變：prompt 只列名稱+簡述,需要時才載全文
+  - `/skills`（查看）、`/skills forget <名>`；`api.skills.{list,remove,reload,path}`
+  - 6 個測試 + 真實 model 端到端閉環（結晶 → 落地 → 新 session 列出並載入全文）
+  - 至此「執行中沉澱經驗」反射/程序/結晶三層皆落地（事實/情節層待後續）
+
 ## 0.3.5
 
 - **執行中沉澱經驗 — 專案手冊（程序層）**：agent 摸清專案「做事方法」時自己記下來,跨 session 自動載入。

package/README.md

@@ -54,6 +54,8 @@ xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
 
 **執行中沉澱經驗（專案手冊）**：agent 摸清「這個專案怎麼做事」(建置/測試/部署指令、慣例、必經步驟、踩過的坑與修法)時,會用 `playbook_update` 按 topic 記進 `.xitto-kernel/<pack>/playbook.md`(同 topic 覆蓋,天然去重)；**下次 session 自動載入系統提示,不必重新摸索**。因檔案綁 cwd,手冊天然只對這個專案生效。`/playbook` 查看、`/playbook forget <主題>`、`/playbook clear`。分工:`memory` 存事實/偏好/決策(扁平),`playbook` 存可重複的程序知識(按主題)。
 
+**自我結晶技能（結晶層，須驗證）**：摸出一套可重複的操作流程/SOP 時,agent 用 `skill_save` 把它**寫成新技能**(markdown)存進 `.xitto-kernel/<pack>/skills/`。**政策閘門:每個技能新增時必須附 (1) `goal` 明確目標 (2) `verify` 一條驗證指令——verify 會在沙箱實際執行,通過(exit 0)才落地**,否則拒絕並回傳輸出讓 agent 修正(危險指令一律擋下)。確保結晶的是「已驗證的成功」而非「宣稱的成功」。**本 session 立即可用 `skill` 按名載入(熱掃描),未來 session 自動列入「可用技能」**(漸進揭露:prompt 只列名稱+簡述,需要時才載全文)。**自我維護**:載入會記用量(`usedCount`);`skills_check`/`/skills check` 重跑每個技能存的 verify 偵測**漂移**——專案變動後失效的標 `⚠ stale` 浮上來讓你修或刪,保持技能庫可信(失效的在 prompt 標注、別誤用)。`/skills` 查看(含用量/失效)、`/skills forget <名>` 移除。分工:`playbook` 是專案事實性 know-how,`skill` 是可跨任務複用且**已驗證**的操作流程。這層讓 agent 像 Voyager 一樣**長出自己的技能庫**——但每條都經驗證、會自我體檢,且跑在 kernel 的沙箱 + 漸進信任治理裡。
+
 **通用自主 agent（給目標、自己做到完成）**
 ```bash
 xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫進 summary.txt"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

package/src/app/cli.js

@@ -176,6 +176,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           '  /trust [forget <項>|clear]  已信任的工具/命令（漸進放權,跨 session）',
           '  /memory          顯示跨 session 記憶',
           '  /playbook [forget <主題>|clear]  專案手冊（agent 沉澱的程序知識,跨 session）',
+          '  /skills [check|forget <名>]  已結晶技能（用量/失效標示；check 重跑 verify 偵測漂移）',
           '  /sessions        列出已保存的對話',
           '  /resume [id]     續接對話（不給 id=最近一次）',
           '  /clear           清除歷史（開新 session）',
@@ -202,6 +203,28 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         if (kernel.playbook.path) out(c.gray(`  ↳ ${kernel.playbook.path}（清除：/playbook forget <主題>）\n`));
         return true;
       }
+      case '/skills': {
+        const rest = input.trim().slice(cmd.length).trim();
+        if (rest.startsWith('forget ')) {
+          const n = rest.slice('forget '.length).trim();
+          const r = kernel.skills.remove(n);
+          out(r.removed ? c.gray(`（已移除技能「${r.removed}」）\n`) : c.yellow(`找不到技能「${n}」\n`));
+          return true;
+        }
+        if (rest === 'check') {
+          out(c.gray('複查中（重跑各技能 verify）…\n'));
+          kernel.skills.check().then((res) => {
+            if (!res.length) { out(c.gray('（尚無技能可複查）\n')); return; }
+            out(res.map((r) => (r.status === 'ok' ? c.green('  ✓ ') : r.status === 'stale' ? c.red('  ✗ ') : c.gray('  - ')) + r.name + c.gray(`（${r.status}）`)).join('\n') + '\n');
+          });
+          return true;
+        }
+        const sk = kernel.skills.list();
+        if (!sk.length) { out(c.gray('（尚無技能；agent 摸出可重複流程時會用 skill_save 結晶）\n')); return true; }
+        out(sk.map((s) => (s.stale ? c.red('  ⚠ ') : c.cyan('  • ')) + s.name + c.gray(`：${s.desc}${s.used ? ` · 用過 ${s.used} 次` : ''}${s.stale ? ' · 已失效待修' : ''}`)).join('\n') + '\n');
+        if (kernel.skills.path) out(c.gray(`  ↳ ${kernel.skills.path}（複查：/skills check · 移除：/skills forget <名>）\n`));
+        return true;
+      }
       case '/trust': {
         const rest = input.trim().slice(cmd.length).trim();
         if (rest === 'clear') { kernel.permissions.clear(); out(c.gray('（已清除全部信任）\n')); return true; }
@@ -267,7 +290,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   // 斜線指令 tab 補全
-  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/trust', '/memory', '/playbook', '/sessions', '/resume', '/clear', '/exit'];
+  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/trust', '/memory', '/playbook', '/skills', '/sessions', '/resume', '/clear', '/exit'];
   const completer = (line) => {
     if (!line.startsWith('/')) return [[], line];
     const hits = SLASH.filter((s) => s.startsWith(line));

package/src/kernel/index.js

@@ -9,7 +9,9 @@ import { createToolRegistry, deriveMutatingTools, isSandboxable } from './tool-r
 import { composeGuards } from './guard-chain.js';
 import { createPermissionStep } from './security/permission-step.js';
 import { fileAllowStore, memoryAllowStore } from './security/allow-store.js';
-import { normalizeSandbox, wrapWithSeatbelt } from './security/sandbox.js';
+import { normalizeSandbox, wrapWithSeatbelt, sandboxViolation } from './security/sandbox.js';
+import { dangerousReason } from './security/danger.js';
+import { spawnSync } from 'node:child_process';
 import { createMemory } from './memory.js';
 import { createPlaybook } from './playbook.js';
 import { createTodo } from './todo.js';
@@ -109,13 +111,31 @@ export function createKernel(pack, config = {}) {
   const todo = createTodo();
   const sessionsDir = join(dataDir, 'sessions');
   const hooks = loadHooks(join(dataDir, 'settings.json')); // PreToolUse/PostToolUse
-  const skills = createSkills(join(dataDir, 'skills'));     // 漸進揭露技能
 
   // 沙箱策略：config.sandbox > pack.permissionPolicy.sandbox > 預設（關）。
   const sandboxCfg = normalizeSandbox(config.sandbox ?? pack.permissionPolicy?.sandbox);
   const getSandbox = config.getSandbox || (() => !!sandboxCfg.enabled);
   const getSandboxConfig = () => sandboxCfg;
 
+  // 技能驗證器：結晶新技能前，先在沙箱跑一條驗證指令，須 exit 0 才准新增（結晶=已驗證的成功）。
+  // 靜態安全：危險指令一律擋；開沙箱時併查靜態策略，再用 Seatbelt 包執行。
+  const runVerify = (command, { timeoutMs = 60000 } = {}) => {
+    const cmd = String(command || '').trim();
+    if (!cmd) return { ok: false, blocked: true, reason: 'verify 指令為空' };
+    const danger = dangerousReason(cmd);
+    if (danger) return { ok: false, blocked: true, reason: `驗證指令危險（${danger}），拒絕執行` };
+    if (getSandbox()) {
+      const v = sandboxViolation(cmd, getSandboxConfig());
+      if (v) return { ok: false, blocked: true, reason: `驗證指令違反沙箱策略（${v}）` };
+    }
+    const finalCmd = (getSandbox() ? wrapWithSeatbelt(cmd, { cwd, cfg: getSandboxConfig() }) : null) || cmd;
+    const r = spawnSync(finalCmd, { shell: true, cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024 });
+    const output = ((r.stdout || '') + (r.stderr || '')).trim().slice(0, 4000);
+    if (r.error) return { ok: false, code: null, output: (output + ' ' + r.error.message).trim() };
+    return { ok: r.status === 0, code: r.status, output: output || '(no output)' };
+  };
+  const skills = createSkills(join(dataDir, 'skills'), { verifyRunner: runVerify }); // 漸進揭露 + 結晶（須驗證）
+
   // 工具：pack 工具（sandboxable 包 Seatbelt、mutating+path 加 undo 快照）+ kernel 內建記憶工具 + spawn_agent。
   const undoStack = [];
   const baseTools = [
@@ -123,7 +143,7 @@ export function createKernel(pack, config = {}) {
     ...memory.tools,
     ...playbook.tools,
     todo.tool,
-    ...(skills.tool ? [skills.tool] : []),
+    ...skills.tools,
     ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
   ];
   // spawn_agent：派唯讀子 agent。其可用工具 = 所有唯讀工具（不含 spawn_agent 自己，避免遞迴）。
@@ -199,6 +219,8 @@ export function createKernel(pack, config = {}) {
     memory,
     // 專案手冊（程序層沉澱）：列出 / 更新 / 移除 / 全清；path 為落地檔。
     playbook: { list: playbook.list, update: playbook.update, remove: playbook.remove, clear: playbook.clear, load: playbook.load, path: join(dataDir, 'playbook.md') },
+    // 技能（結晶層 + 自我維護）：列出 / 移除 / 重掃 / 漂移複查；path 為技能資料夾。
+    skills: { list: skills.list, remove: skills.remove, reload: skills.reload, check: skills.check, path: join(dataDir, 'skills') },
     todo: { get: todo.get },
     /** 撤銷上一次檔案改動（write/edit）：還原內容，新建的檔則刪除。 */
     undo: () => {

package/src/kernel/skills.js

@@ -1,37 +1,161 @@
-// Skills（漸進揭露）— kernel 內建。.xitto-kernel/<pack>/skills/*.md 每檔一個技能。
+// Skills（漸進揭露 + 結晶層 + 自我維護）— kernel 內建。.xitto-kernel/<pack>/skills/*.md 每檔一個技能。
 // system prompt 只列「名稱 + 簡述」；agent 用 skill 工具按名載入完整步驟。對標 xitto-code skills。
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+// 結晶層：agent 把重複流程用 skill_save 寫成新技能（須附 goal + 通過 verify 才落地）。
+// 自我維護：載入時記使用戳記（usedCount/lastUsedAt）；skills_check 重跑各技能 verify 偵測漂移（stale）。
+// 技能是 markdown 指令(非可執行碼),自寫安全——名稱 slug 化防穿越,內容只是日後注入的提示文字。
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 
 const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
 
+// 簡易 frontmatter（key: value 行）解析/序列化 + 不動 body 的 patch。
+function splitFront(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { fm: {}, body: md };
+  const fm = {};
+  for (const line of m[1].split('\n')) { const i = line.indexOf(':'); if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim(); }
+  return { fm, body: m[2] };
+}
+function joinFront(fm, body) {
+  const keys = Object.keys(fm);
+  if (!keys.length) return body;
+  return '---\n' + keys.map((k) => `${k}: ${fm[k]}`).join('\n') + '\n---\n\n' + body.replace(/^\n+/, '');
+}
+// verify 指令取自 `## 驗證…` 的 fenced sh 區塊（skill_save 寫入的格式；保留原樣含多行）。
+function extractVerify(md) {
+  const m = md.match(/##\s*驗證[^\n]*\n```(?:sh|bash)?\n([\s\S]*?)\n```/);
+  return m ? m[1].trim() : null;
+}
+
 const firstDesc = (body) => {
   const fm = body.match(/^description:\s*(.+)$/mi);
   if (fm) return fm[1].trim();
   return (body.split('\n').map((l) => l.replace(/^#+\s*/, '').trim()).find(Boolean)) || '';
 };
 
-export function createSkills(dir) {
-  const skills = [];
-  if (existsSync(dir)) {
-    for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
-      try { const body = readFileSync(join(dir, f), 'utf8'); skills.push({ name: f.replace(/\.md$/, ''), desc: firstDesc(body), body }); } catch { /* 略 */ }
+const slug = (s) => String(s || '').trim().toLowerCase()
+  .replace(/[^a-z0-9一-龥_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+
+export function createSkills(dir, { verifyRunner } = {}) {
+  const fileOf = (name) => join(dir, `${name}.md`);
+  const readAll = () => {
+    const out = [];
+    if (existsSync(dir)) {
+      for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+        try {
+          const md = readFileSync(join(dir, f), 'utf8');
+          const { fm } = splitFront(md);
+          out.push({ name: f.replace(/\.md$/, ''), desc: firstDesc(md), body: md, used: Number(fm.usedCount) || 0, stale: fm.stale === 'true' });
+        } catch { /* 略 */ }
+      }
     }
-  }
+    return out;
+  };
+  const patch = (name, p) => {
+    const file = fileOf(name);
+    if (!existsSync(file)) return false;
+    try { const { fm, body } = splitFront(readFileSync(file, 'utf8')); Object.assign(fm, p); writeFileSync(file, joinFront(fm, body)); return true; } catch { return false; }
+  };
+
+  let skills = readAll(); // 啟動快照（供 system prompt 列名用）
+  const label = (s) => `- ${s.name}：${s.desc}${s.used ? `（用過 ${s.used} 次）` : ''}${s.stale ? ' ⚠ 已失效待修' : ''}`;
 
   const promptSection = () => (skills.length
-    ? '\n\n# 可用技能（需要時用 skill 工具按名載入完整步驟）\n' + skills.map((s) => `- ${s.name}：${s.desc}`).join('\n')
-    : '');
+    ? '\n\n# 可用技能（需要時用 skill 按名載入全文；摸出可重複流程可用 skill_save 結晶；⚠ 失效的先別用,可 skills_check 複查）\n' + skills.map(label).join('\n')
+    : '\n\n# 技能\n尚無已存技能。摸出一套可重複的流程時，用 skill_save 把它結晶成技能（須附 goal + 通過 verify），之後即可按名複用。');
 
-  const tool = skills.length ? {
+  // 載入技能：rescan → 找到剛存的；記使用戳記（A）
+  const loadTool = {
     name: 'skill', label: '載入技能', readOnly: true,
     description: '按名載入一個技能的完整步驟（漸進揭露：prompt 只列名稱+簡述，需要時才載全文）。',
     parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
     execute: async (_id, { name }) => {
-      const s = skills.find((x) => x.name === name);
-      return txt(s ? s.body : { error: '找不到技能', name, available: skills.map((x) => x.name) });
+      skills = readAll();
+      const s = skills.find((x) => x.name === name) || skills.find((x) => x.name === slug(name));
+      if (!s) return txt({ error: '找不到技能', name, available: skills.map((x) => x.name) });
+      patch(s.name, { usedCount: s.used + 1, lastUsedAt: new Date().toISOString() });
+      skills = readAll();
+      return txt(s.body);
+    },
+  };
+
+  // 結晶層：把可重複流程寫成新技能。政策——須附 goal + 通過的 verify 才落地（verify 在沙箱實跑）。
+  const saveTool = {
+    name: 'skill_save', label: '結晶技能', readOnly: true,
+    description: '把一套你摸出來、會重複用到的流程「結晶」成可複用技能。政策：每個技能必須附 (1) goal 明確目標 (2) verify 一條可驗證它有效的指令——verify 會被實際執行,通過(exit 0)才會新增,否則拒絕並回傳輸出讓你修正。確保結晶的是「已驗證的成功」。與 playbook 的差別：playbook 是專案事實性 know-how，skill 是可複用且已驗證的操作流程/SOP。',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: '技能短名（會 slug 化為檔名）' },
+        goal: { type: 'string', description: '這個技能要達成的明確目標（一句話）' },
+        body: { type: 'string', description: '完整步驟內容（markdown）' },
+        verify: { type: 'string', description: '一條能驗證此技能/成果有效的 shell 指令（須 exit 0；如 `npm test`、`test -f dist/app.js`）。會被實際執行。' },
+        description: { type: 'string', description: '可選；省略則用 goal 當簡述' },
+      },
+      required: ['name', 'goal', 'body', 'verify'],
+    },
+    execute: async (_id, { name, goal, body, verify, description }) => {
+      const nm = slug(name);
+      if (!nm) return txt({ error: 'name 不合法（需含中英數）' });
+      if (!goal || !String(goal).trim()) return txt({ error: '缺 goal：每個技能必須有明確目標' });
+      if (!body || !String(body).trim()) return txt({ error: 'body 不可為空' });
+      if (!verify || !String(verify).trim()) return txt({ error: '缺 verify：必須提供可驗證有效的指令（測試完成才能新增）' });
+      if (typeof verifyRunner !== 'function') return txt({ error: '此環境不支援技能驗證，無法新增（須在 kernel 內執行）' });
+
+      const vr = await verifyRunner(String(verify).trim());
+      if (vr.blocked) return txt({ error: '驗證被安全策略擋下，未新增', reason: vr.reason, verify });
+      if (!vr.ok) return txt({ error: '驗證未通過，未新增技能。請修正步驟或指令後重試。', exitCode: vr.code, output: vr.output, verify });
+
+      const now = new Date().toISOString();
+      const desc = (String(description || goal)).replace(/\s+/g, ' ').trim().slice(0, 120);
+      const content =
+        `---\ndescription: ${desc}\ngoal: ${String(goal).replace(/\s+/g, ' ').trim()}\nverified: true\nverifiedAt: ${now}\n---\n\n` +
+        `## 目標\n${String(goal).trim()}\n\n${String(body).trim()}\n\n## 驗證（已通過 exit 0）\n\`\`\`sh\n${String(verify).trim()}\n\`\`\`\n`;
+      try {
+        mkdirSync(dir, { recursive: true });
+        const existed = existsSync(fileOf(nm));
+        writeFileSync(fileOf(nm), content);
+        skills = readAll();
+        return txt({ [existed ? 'updated' : 'saved']: nm, verified: true, verifyOutput: vr.output, hint: '驗證通過,已結晶為技能；本 session 可用 skill 按名載入，下次 session 自動列入。' });
+      } catch (e) { return txt({ error: e.message }); }
     },
-  } : null;
+  };
+
+  // 漂移偵測（B）：重跑每個技能存的 verify → 標 ✓ 仍有效 / ✗ 已失效(stale)。
+  const check = async () => {
+    const now = new Date().toISOString();
+    const results = [];
+    for (const s of readAll()) {
+      const verify = extractVerify(s.body);
+      if (!verify) { results.push({ name: s.name, status: 'no-verify' }); continue; }
+      if (typeof verifyRunner !== 'function') { results.push({ name: s.name, status: 'unchecked' }); continue; }
+      const vr = await verifyRunner(verify);
+      const ok = vr.ok && !vr.blocked;
+      patch(s.name, ok ? { stale: 'false', lastCheckedAt: now } : { stale: 'true', staleSince: now });
+      results.push({ name: s.name, status: vr.blocked ? 'blocked' : ok ? 'ok' : 'stale', exitCode: vr.code });
+    }
+    skills = readAll();
+    return results;
+  };
+  const checkTool = {
+    name: 'skills_check', label: '複查技能', readOnly: true,
+    description: '重新驗證所有已結晶技能（重跑各自的 verify），回報哪些仍有效、哪些已失效(stale)。專案變動後用來清理過時技能,避免誤用。',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => txt({ checked: await check() }),
+  };
+
+  const remove = (name) => {
+    const nm = slug(name); const file = fileOf(nm);
+    if (!existsSync(file)) return { error: '找不到技能', name };
+    try { unlinkSync(file); skills = readAll(); return { removed: nm }; } catch (e) { return { error: e.message }; }
+  };
 
-  return { skills, promptSection, tool };
+  return {
+    skills, promptSection,
+    tool: loadTool,
+    tools: [loadTool, saveTool, checkTool],
+    list: () => readAll().map(({ name, desc, used, stale }) => ({ name, desc, used, stale })),
+    check, remove,
+    reload: () => { skills = readAll(); return skills; },
+  };
 }