@bevel-software/platform-core-backend 0.1.0

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -0,0 +1,176 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { SkillService } from '../skills.service.js';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import { readFile as fsReadFile } from 'node:fs/promises';
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+const RFI_SKILL = `---
+name: rfi
+version: 1.4.0
+description: |
+  Specialist RFI responder. Runs KB-only: every answer is
+  grounded in a real knowledge-graph node.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /rfi: Specialist RFI Responder
+
+You answer RFIs.
+`;
+
+describe('SkillService', () => {
+  let root: string;
+
+  // WorkspaceService stub: default-branch workspace lives at <root>/<wsId>, the
+  // KB clone at <root>/<wsId>/<KB_DIR>.
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+    readFile: async (id: string, rel: string) => fsReadFile(join(root, id, rel), 'utf-8'),
+  } as unknown as WorkspaceService;
+
+  const allowAll: IAccessControl = {
+    canRead: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+
+  const svc = (access: IAccessControl = allowAll) =>
+    new SkillService(workspaceService, access, KB_DIR);
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'skills-'));
+    const skills = join(root, wsId, KB_DIR, 'Skills');
+    await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
+    await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
+    await writeFile(join(skills, 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx")\n');
+    // A folder with no SKILL.md is not a skill.
+    await mkdir(join(skills, 'not-a-skill'), { recursive: true });
+    await writeFile(join(skills, 'not-a-skill', 'README.md'), '# nope\n');
+    // A skill nested in a category subfolder (Skills/Development/coding-guidelines).
+    await mkdir(join(skills, 'Development', 'coding-guidelines'), { recursive: true });
+    await writeFile(
+      join(skills, 'Development', 'coding-guidelines', 'SKILL.md'),
+      '---\nname: coding-guidelines\ndescription: Coding guidelines.\n---\n\n# Guidelines\n',
+    );
+    await writeFile(join(skills, 'Development', 'access.md'), '---\nwrite:\n  - Developer\n---\n');
+  });
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  test('lists skills with a block-scalar description parsed correctly', async () => {
+    const skills = await svc().listSkills();
+    expect(skills).toHaveLength(2);
+    const rfi = skills.find((s) => s.name === 'rfi')!;
+    expect(rfi).toBeDefined();
+    expect(rfi.path).toBe('Skills/rfi');
+    expect(rfi.version).toBe('1.4.0');
+    expect(rfi.description).not.toBe('|');
+    expect(rfi.description).toContain('Specialist RFI responder');
+    expect(rfi.description).toContain('grounded in a real knowledge-graph node');
+  });
+
+  test('discovers a skill nested in a category subfolder', async () => {
+    const skills = await svc().listSkills();
+    const cg = skills.find((s) => s.name === 'coding-guidelines')!;
+    expect(cg).toBeDefined();
+    expect(cg.path).toBe('Skills/Development/coding-guidelines');
+    expect(cg.description).toBe('Coding guidelines.');
+
+    const res = await svc().getSkill('user@x.eu', 'coding-guidelines');
+    expect(res.ok).toBe(true);
+    if (res.ok && res.kind === 'skill') {
+      expect(res.skill.path).toBe('Skills/Development/coding-guidelines');
+      expect(res.skill.body).toContain('# Guidelines');
+    }
+  });
+
+  test('refuses a colliding id (no auto-suffix) — the shared dedup rule', async () => {
+    const skills = join(root, wsId, KB_DIR, 'Skills');
+    // Two skills resolve to the same id `dup` (no frontmatter id/name → folder name).
+    await mkdir(join(skills, 'Zeta', 'dup'), { recursive: true });
+    await writeFile(join(skills, 'Zeta', 'dup', 'SKILL.md'), '---\ndescription: zeta dup\n---\n\n# Z\n');
+    await mkdir(join(skills, 'Alpha', 'dup'), { recursive: true });
+    await writeFile(join(skills, 'Alpha', 'dup', 'SKILL.md'), '---\ndescription: alpha dup\n---\n\n# A\n');
+
+    const list = await svc().listSkills();
+    // Only the first (smallest path) survives; the duplicate is dropped, not suffixed.
+    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Skills/Alpha/dup']);
+    expect(list.find((s) => s.name === 'dup2')).toBeUndefined();
+
+    const a = await svc().getSkill('user@x.eu', 'dup');
+    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Skills/Alpha/dup');
+  });
+
+  test('frontmatter `id`/`name` overrides the folder name for identity', async () => {
+    const skills = join(root, wsId, KB_DIR, 'Skills');
+    await mkdir(join(skills, 'folderx'), { recursive: true });
+    await writeFile(join(skills, 'folderx', 'SKILL.md'), '---\nid: my_skill\ndescription: d\n---\n\n# X\n');
+    const list = await svc().listSkills();
+    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Skills/folderx');
+  });
+
+  test('getSkill returns body, folder path, files and allowed-tools', async () => {
+    const res = await svc().getSkill('user@x.eu', 'rfi');
+    expect(res.ok).toBe(true);
+    if (res.ok && res.kind === 'skill') {
+      expect(res.skill.path).toBe('Skills/rfi');
+      expect(res.skill.body).toContain('# /rfi: Specialist RFI Responder');
+      expect(res.skill.files).toEqual(['Skills/rfi/scripts/build_xlsx.py']);
+      expect(res.skill.allowedTools).toEqual(['Bash', 'Read']);
+    }
+  });
+
+  test('getSkill with a `file` returns that bundled file content', async () => {
+    const res = await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py');
+    expect(res.ok).toBe(true);
+    if (res.ok && res.kind === 'file') {
+      expect(res.file.path).toBe('Skills/rfi/scripts/build_xlsx.py');
+      expect(res.file.content).toContain('print("xlsx")');
+    }
+  });
+
+  test('getSkill rejects an unknown skill and path-traversal file', async () => {
+    expect(await svc().getSkill('user@x.eu', 'nope')).toEqual({ ok: false, error: 'not_found' });
+    const trav = await svc().getSkill('user@x.eu', 'rfi', '../../etc/passwd');
+    expect(trav).toEqual({ ok: false, error: 'invalid_file' });
+  });
+
+  test('listSkills filters by canRead for a given user', async () => {
+    const denyRfi: IAccessControl = {
+      canRead: async () => false,
+      canReadBatch: async (_w: string, _e: string, paths: string[]) =>
+        new Map(paths.map((p) => [p, false])),
+    } as unknown as IAccessControl;
+    expect(await svc(denyRfi).listSkills('user@x.eu')).toHaveLength(0);
+    // No email → global set, unfiltered.
+    expect(await svc(denyRfi).listSkills()).toHaveLength(2);
+  });
+
+  test('listSkills fails CLOSED: a path the checker gave no verdict for is hidden', async () => {
+    // A checker that "skips" every path (returns an empty map) must hide
+    // everything — a missing answer is a denial, never an exposure.
+    const noVerdicts: IAccessControl = {
+      canRead: async () => false,
+      canReadBatch: async () => new Map<string, boolean>(),
+    } as unknown as IAccessControl;
+    expect(await svc(noVerdicts).listSkills('user@x.eu')).toHaveLength(0);
+  });
+
+  test('getSkill is forbidden when the user cannot read it', async () => {
+    const denyRfi = {
+      canRead: async () => false,
+      canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+    } as unknown as IAccessControl;
+    expect(await svc(denyRfi).getSkill('user@x.eu', 'rfi')).toEqual({ ok: false, error: 'forbidden' });
+  });
+});

package/src/modules/skills/index.ts

@@ -0,0 +1,10 @@
+export { SkillService } from './skills.service.js';
+export { registerSkillsTools } from './skills.tools.js';
+export { createSkillsRoutes } from './skills.routes.js';
+export type {
+  ISkillService,
+  Skill,
+  SkillSummary,
+  SkillFileContent,
+  GetSkillResult,
+} from './skills.contract.js';

package/src/modules/skills/skills.contract.ts

@@ -0,0 +1,54 @@
+/**
+ * Skills are reusable specialist instructions living under `Skills/<name>/SKILL.md`
+ * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
+ * is a single global, released set (a skill on a draft isn't discoverable until
+ * merged). Progressive disclosure: `listSkills` = name + description (level 1),
+ * `getSkill` = full body + bundled-file paths (level 2), `getSkill(file)` = a
+ * bundled file's content (level 3).
+ */
+
+export interface SkillSummary {
+  /** Canonical id = the skill's folder name (e.g. `rfi`). */
+  name: string;
+  description: string;
+  version?: string;
+  /** Repo-root-relative skill folder, e.g. `Skills/rfi`. */
+  path: string;
+}
+
+export interface Skill extends SkillSummary {
+  /** The SKILL.md markdown body (instructions to follow). */
+  body: string;
+  /** Pre-approved tools from the `allowed-tools` frontmatter, if declared. */
+  allowedTools?: string[];
+  /** Repo-root-relative bundled file paths, e.g. `Skills/rfi/scripts/build_xlsx.py`. */
+  files: string[];
+}
+
+export interface SkillFileContent {
+  /** The skill name. */
+  name: string;
+  /** The bundled file, relative to the skill folder (e.g. `scripts/build_xlsx.py`). */
+  file: string;
+  /** Repo-root-relative path of the file. */
+  path: string;
+  content: string;
+}
+
+export type GetSkillResult =
+  | { ok: true; kind: 'skill'; skill: Skill }
+  | { ok: true; kind: 'file'; file: SkillFileContent }
+  | { ok: false; error: 'not_found' | 'forbidden' | 'invalid_file' };
+
+export interface ISkillService {
+  /**
+   * The default-branch skill catalog. When `userEmail` is given, filtered to
+   * skills that user may read (`canRead`); omit it for the global set (used to
+   * compose the tool descriptions in the manual).
+   */
+  listSkills(userEmail?: string): Promise<SkillSummary[]>;
+  /** Load a skill's body (+ files), or a bundled file's content when `file` is given. */
+  getSkill(userEmail: string, name: string, file?: string): Promise<GetSkillResult>;
+  /** Drop the cached catalog (call after a merge to the default branch). */
+  invalidate(): void;
+}

package/src/modules/skills/skills.routes.ts

@@ -0,0 +1,38 @@
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import type { ISkillService } from './skills.contract.js';
+
+/**
+ * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
+ * `authMiddleware`. Backed by the SAME `SkillService` as the agent tool surface,
+ * so discovery, default-branch pinning, and per-user `canRead` filtering live
+ * ONCE — the frontend never re-implements skill discovery or bypasses access.
+ *
+ *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills/:name      → GetSkillResult               (body + files)
+ *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
+ */
+export function createSkillsRoutes(skillService: ISkillService): express.Router {
+  const router = express.Router();
+
+  router.get('/skills', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    res.json({ skills: await skillService.listSkills(email) });
+  });
+
+  router.get('/skills/:name', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    const file = typeof req.query.file === 'string' ? req.query.file : undefined;
+    res.json(await skillService.getSkill(email, req.params.name, file));
+  });
+
+  return router;
+}

package/src/modules/skills/skills.service.ts

@@ -0,0 +1,245 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseDocument } from 'yaml';
+import { DEFAULT_BRANCH, SKILLS_DIR } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
+import { walkFiles } from '../../shared/fs-walk.js';
+import { TtlCache } from '../../shared/ttl-cache.js';
+import type {
+  ISkillService,
+  GetSkillResult,
+  Skill,
+  SkillSummary,
+} from './skills.contract.js';
+
+const CACHE_TTL_MS = 60_000;
+
+interface ParsedSkill {
+  summary: SkillSummary;
+  body: string;
+  allowedTools?: string[];
+  files: string[];
+}
+
+/**
+ * Reads skills from the DEFAULT-branch workspace (never the caller's branch), so
+ * the catalog is one global, released set. Results are cached briefly and on a
+ * merge to default the cache should be dropped via `invalidate()`.
+ */
+export class SkillService implements ISkillService {
+  private readonly cache: TtlCache<ParsedSkill[]>;
+
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly accessControl: IAccessControl,
+    private readonly kbDirName: string,
+    now: () => number = Date.now,
+  ) {
+    this.cache = new TtlCache(CACHE_TTL_MS, now);
+  }
+
+  invalidate(): void {
+    this.cache.invalidate();
+  }
+
+  async listSkills(userEmail?: string): Promise<SkillSummary[]> {
+    const skills = await this.scan();
+    const summaries = skills.map((s) => s.summary);
+    if (!userEmail) return summaries;
+    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const allowed = await this.accessControl.canReadBatch(
+      wsId,
+      userEmail,
+      summaries.map((s) => `${s.path}/SKILL.md`),
+    );
+    // Fail closed: keep a skill only on an explicit `true` verdict — a missing
+    // entry counts as denied, matching the KB's default-deny read model (and the
+    // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
+    // the checker skips a path.
+    return summaries.filter((s) => allowed.get(`${s.path}/SKILL.md`) === true);
+  }
+
+  async getSkill(userEmail: string, name: string, file?: string): Promise<GetSkillResult> {
+    if (!isSafeName(name)) return { ok: false, error: 'not_found' };
+    const found = (await this.scan()).find((s) => s.summary.name === name);
+    if (!found) return { ok: false, error: 'not_found' };
+
+    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    if (!(await this.accessControl.canRead(wsId, userEmail, `${found.summary.path}/SKILL.md`))) {
+      return { ok: false, error: 'forbidden' };
+    }
+
+    if (file !== undefined) {
+      if (!isSafeRelFile(file)) return { ok: false, error: 'invalid_file' };
+      const repoPath = `${found.summary.path}/${file}`;
+      try {
+        const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
+        return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
+      } catch {
+        return { ok: false, error: 'not_found' };
+      }
+    }
+
+    const skill: Skill = {
+      ...found.summary,
+      body: found.body,
+      allowedTools: found.allowedTools,
+      files: found.files,
+    };
+    return { ok: true, kind: 'skill', skill };
+  }
+
+  // --- internal ---------------------------------------------------------------
+
+  private async scan(): Promise<ParsedSkill[]> {
+    const cached = this.cache.get();
+    if (cached) return cached;
+    const skills = await this.scanDisk();
+    this.cache.set(skills);
+    return skills;
+  }
+
+  private async scanDisk(): Promise<ParsedSkill[]> {
+    // Ensure the default-branch clone exists, then scan its Skills/ dir. Any
+    // failure (no workspace, no Skills/ dir) degrades to an empty catalog — the
+    // manual/tools must never break because skills can't be read.
+    let wsId: string;
+    try {
+      wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+    } catch {
+      return [];
+    }
+    const root = path.join(
+      await this.workspaceService.getWorkspacePath(wsId),
+      this.kbDirName,
+      SKILLS_DIR,
+    );
+
+    // Skills may be grouped in category subfolders (each carrying its own
+    // access.md), so a SKILL.md can live at any depth under Skills/. Walk the
+    // tree and treat every folder that directly contains a SKILL.md as a skill;
+    // don't descend past it — its inner files are bundled assets, not nested
+    // skills. The skill name is the leaf folder name; its path is the full
+    // Skills-relative folder (e.g. `Skills/Development/coding-guidelines`).
+    const out: ParsedSkill[] = [];
+    const walk = async (dir: string, relFolder: string): Promise<void> => {
+      let entries: import('node:fs').Dirent[];
+      try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+        let raw: string;
+        try {
+          raw = await fs.readFile(path.join(dir, 'SKILL.md'), 'utf-8');
+        } catch {
+          return;
+        }
+        const fm = parseSkillFrontmatter(raw);
+        // Identity via the shared rule: frontmatter `id` → `name` → folder name.
+        // `getSkill()` refuses unsafe names (path separators, `.`/`..`), so a
+        // declared id that fails the same check would list but never fetch —
+        // fall back to the folder name (a readdir entry, safe by construction)
+        // to keep listing and lookup consistent.
+        const declared = resolveDeclaredId(fm.frontmatter, path.basename(dir));
+        const name = isSafeName(declared) ? declared : path.basename(dir);
+        out.push({
+          summary: { name, description: fm.description, version: fm.version, path: relFolder },
+          body: fm.body,
+          allowedTools: fm.allowedTools,
+          files: await listBundledFiles(dir, relFolder),
+        });
+        return; // a skill folder is a leaf — its subfolders hold assets, not skills
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
+      }
+    };
+    await walk(root, SKILLS_DIR);
+    // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
+    // resolves it, so it must be unique. Sort by (name, path) for a deterministic
+    // winner, then REFUSE later duplicates via the shared dedup — the same rule
+    // tools use (no silent auto-suffix that would rebind an id under the caller).
+    out.sort(
+      (a, b) =>
+        a.summary.name.localeCompare(b.summary.name) ||
+        a.summary.path.localeCompare(b.summary.path),
+    );
+    return dedupeById(out, (s) => s.summary.name, (s, id) =>
+      console.warn(
+        `[skills] skipping "${s.summary.path}": id "${id}" is already used by another skill — ` +
+          'give it a unique `id`/`name` in its SKILL.md frontmatter.',
+      ),
+    );
+  }
+}
+
+// --- helpers ------------------------------------------------------------------
+
+/** Skill names are folder names; reject anything that could escape the folder. */
+function isSafeName(name: string): boolean {
+  return name.length > 0 && !name.includes('/') && !name.includes('\\') && name !== '.' && name !== '..';
+}
+
+/** A bundled-file path must stay inside the skill folder. */
+function isSafeRelFile(file: string): boolean {
+  if (!file || file.includes('\\') || path.isAbsolute(file)) return false;
+  return file.split('/').every((seg) => seg.length > 0 && seg !== '..');
+}
+
+function scalarToString(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return undefined;
+}
+
+function parseSkillFrontmatter(raw: string): {
+  description: string;
+  version?: string;
+  allowedTools?: string[];
+  body: string;
+  /** The parsed frontmatter object (for shared id resolution: `id`/`name`). */
+  frontmatter: Record<string, unknown>;
+} {
+  const fm = extractFrontmatter(raw);
+  if (!fm) return { description: '', body: raw.trimStart(), frontmatter: {} };
+
+  const body = fm.body.trimStart();
+  let data: Record<string, unknown> = {};
+  try {
+    // Resilient: `toJS` returns the best-effort value even if some entry is
+    // malformed, so one bad field never drops the rest.
+    const parsed = parseDocument(fm.frontmatter).toJS();
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      data = parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* keep empty metadata */
+  }
+
+  const description = typeof data.description === 'string' ? data.description.trim() : '';
+  const metadata = (data.metadata ?? {}) as Record<string, unknown>;
+  const version = scalarToString(data.version) ?? scalarToString(metadata.version);
+
+  // `allowed-tools` is a space-separated string (agentskills) or a YAML list.
+  const at = data['allowed-tools'];
+  const allowedTools = Array.isArray(at)
+    ? at.map((t) => String(t))
+    : typeof at === 'string'
+      ? at.split(/\s+/).filter(Boolean)
+      : undefined;
+
+  return { description, version, allowedTools, body, frontmatter: data };
+}
+
+/** Repo-root-relative paths of every bundled file under a skill folder (excludes SKILL.md). */
+async function listBundledFiles(dir: string, relFolder: string): Promise<string[]> {
+  return (await walkFiles(dir, () => true))
+    .filter((rel) => rel !== 'SKILL.md')
+    .map((rel) => `${relFolder}/${rel}`);
+}

package/src/modules/skills/skills.tools.ts

@@ -0,0 +1,121 @@
+import type { Router, RequestHandler } from 'express';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { ISkillService } from './skills.contract.js';
+
+/**
+ * Registers the two skill tools (both surfaces) and hosts their endpoints.
+ *
+ * The defs are registered as PROVIDERS (resolved at manual-build time) so each
+ * tool's description can name the currently-available skills — the agent sees
+ * what exists right in the tool catalog, no `list_skills` round-trip needed, and
+ * it auto-updates as the default-branch catalog changes. The hosted routes are
+ * static; only the description text is dynamic.
+ */
+export function registerSkillsTools(
+  registry: IToolRegistry,
+  router: Router,
+  toolAuth: RequestHandler,
+  toolHandler: ToolHandlerFactory,
+  skillService: ISkillService,
+): void {
+  registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+  registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+  registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+  registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+
+  router.post(
+    '/agent/tools/list_skills',
+    toolAuth,
+    toolHandler(async (_args, ctx: ToolContext) => ({
+      skills: await skillService.listSkills(ctx.user.email),
+    })),
+  );
+
+  router.post(
+    '/agent/tools/get_skill',
+    toolAuth,
+    toolHandler(async (args, ctx: ToolContext) => {
+      const name = typeof args.name === 'string' ? args.name : '';
+      const file = typeof args.file === 'string' ? args.file : undefined;
+      if (!name) return { error: 'missing_name' };
+      return skillService.getSkill(ctx.user.email, name, file);
+    }),
+  );
+}
+
+/** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
+async function availableSkillsLine(skillService: ISkillService, userEmail?: string): Promise<string> {
+  const skills = await skillService.listSkills(userEmail);
+  if (skills.length === 0) return 'No skills are currently available.';
+  return `Currently available skills: ${skills.map((s) => `\`${s.name}\``).join(', ')}.`;
+}
+
+async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+  return toolDef({
+    name: 'list_skills',
+    description:
+      'List the available skills (reusable specialist instructions) with their names and descriptions. ' +
+      'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
+      (await availableSkillsLine(skillService, userEmail)),
+    path: '/api/agent/tools/list_skills',
+    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    outputs: {
+      type: 'object',
+      properties: {
+        skills: {
+          type: 'array',
+          description: 'Available skills.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              description: { type: 'string' },
+              version: { type: 'string' },
+              path: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+    tags: ['skills'],
+  });
+}
+
+async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+  return toolDef({
+    name: 'get_skill',
+    description:
+      'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
+      'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
+      '(e.g. a script) instead of the body. ' +
+      (await availableSkillsLine(skillService, userEmail)),
+    path: '/api/agent/tools/get_skill',
+    inputs: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+        file: {
+          type: 'string',
+          description:
+            'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
+            'fetch its content instead of the body.',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',
+      properties: {
+        skill: { type: 'object', description: 'The loaded skill: name, description, body, files, ….' },
+        file: { type: 'object', description: 'A bundled file: name, file, path, content.' },
+        error: { type: 'string', description: 'Error code: `not_found`, `forbidden`, `invalid_file`, `missing_name`.' },
+      },
+    },
+    tags: ['skills'],
+  });
+}