opencode-idea 0.0.8 → 0.0.10

package/src/plugin.js

@@ -1,22 +1,31 @@
 // opencode-idea — OpenCode plugin entry.
 //
-// For a JetBrains project this plugin:
+// For a project the user opted into IDEA this plugin:
 //   1. injects the IDE integrated-terminal environment (JAVA_HOME / GOROOT /
 //      Node / Maven / ...) into every OpenCode shell;
 //   2. registers the IDE MCP server with OpenCode (scoped to the project via the
 //      IJ_MCP_SERVER_PROJECT_PATH header), injects direct-call guidance for
 //      IDEA MCP tools, and updates only IDEA MCP tool descriptions;
 //   3. registers the `/open-in-idea` command, which opens the current project
-//      in IntelliJ IDEA (reusing a running instance) and then loads the IDE
-//      capabilities immediately;
-//   4. registers the `idea-run-config` skill (JetBrains projects only),
-//      which teaches the model how to manage `.run/*.run.xml` run
-//      configurations — a capability the IDE MCP server does not expose.
+//      in IntelliJ IDEA (reusing a running instance), loads the IDE
+//      capabilities immediately, and marks the project as an IDEA project;
+//      `/close-in-idea` clears that mark;
+//   4. registers the `idea-run-config` skill (marked projects only), which
+//      teaches the model how to manage `.run/*.run.xml` run configurations — a
+//      capability the IDE MCP server does not expose.
 //
-// Non-JetBrains projects are left untouched. Everything is manual: setup does
-// NOT probe or connect the IDE (only the IDE-terminal env is read when a probe
-// is requested). `/open-in-idea` probes, opens the IDE, and loads the IDE MCP +
-// guidance on demand.
+// A project that was never marked is left untouched. Everything is manual:
+// setup does NOT probe or connect the IDE (only the IDE-terminal env is read
+// when a probe is requested). `/open-in-idea` probes, opens the IDE, and loads
+// the IDE MCP + guidance on demand.
+//
+// Once the user runs `/open-in-idea` in a project, that project is marked as an
+// IDEA project. The mark is persisted through `ctx.storage` (durable across
+// restarts) and cleared by `/close-in-idea`. While a project is marked, every
+// user message assumes the IDE is still up: the plugin asks OpenCode for the
+// `idea` MCP server's status and, when it is not connected, re-runs the open
+// flow before the request is built. Detection is by MCP status, never by tool
+// errors, so a normal business error can never look like a dropped connection.
 //
 // `Plugin.define` from `@opencode/plugin` is an identity function, so a plain
 // `{ id, setup }` object is the whole plugin contract. Exporting it directly
@@ -27,9 +36,9 @@ import {
   IDEA_SERVER_NAME,
   findIdePort,
   serverConfig,
-} from './idea-mcp.js';
-import { readIdeTerminalEnv } from './ide-env.js';
-import { currentProjectPath, hasIdeaDirectory } from './project.js';
+} from './mcp/idea.js';
+import { readIdeTerminalEnv } from './mcp/ide-env.js';
+import { currentProjectPath } from './project.js';
 import { applyEnv, mergeEnv } from './env.js';
 import {
   createLaunchGuard,
@@ -40,7 +49,7 @@ import {
   appendIdeGuidance,
   appendIdeRecoveryGuidance,
 } from './ide-guidance.js';
-import { runConfigSkill } from './ide-run-config-skill.js';
+import { readSkills } from './skill/loader.js';
 
 const DEFAULT_LAUNCH_COOLDOWN_MS = 120000;
 const DEFAULT_LAUNCH_MAX_ATTEMPTS = 5;
@@ -86,7 +95,7 @@ export const HIDDEN_IDEA_TOOLS = [
   // Router
   'idea_execute_tool',
   // Terminal: the plugin reads the IDE env through its own direct MCP call
-  // (`src/ide-env.js`), so the model never needs this tool. Measured value for
+  // (`src/mcp/ide-env.js`), so the model never needs this tool. Measured value for
   // the agent is nil: ~60s hard cutoff with no way to read the terminal buffer,
   // and the native shell already keeps the output tail plus a full-output file.
   'idea_execute_terminal_command',
@@ -149,10 +158,11 @@ function toolIds(tools) {
 
 /**
  * @typedef {{
- *   status: 'connected' | 'tools-loading' | 'mcp-unavailable' | 'launch-failed' | 'disabled',
+ *   status: 'connected' | 'tools-loading' | 'mcp-unavailable' | 'launch-failed' | 'disabled' | 'closed',
  *   port?: number,
  *   opened?: boolean,
- *   unavailableNoticeSent?: boolean
+ *   unavailableNoticeSent?: boolean,
+ *   autoRecovered?: boolean
  * }} IdeCommandResult
  */
 
@@ -172,6 +182,9 @@ const asPositiveNumber = (value, fallback) =>
 /** User-facing status text for a `/open-in-idea` result. */
 /** @param {IdeCommandResult} result */
 export function ideFeedback(result) {
+  if (result?.autoRecovered) {
+    return '检测到 IDE MCP 连接已断开,已自动重新连接并恢复 IDEA 原生工具。';
+  }
   switch (result?.status) {
     case 'connected':
       return 'IDE MCP 已连接;IDEA 原生工具已注册并可用于后续请求。';
@@ -185,6 +198,8 @@ export function ideFeedback(result) {
       return '无法拉起 IntelliJ IDEA(未找到应用或启动失败)。请确认已安装 IDEA,或手动打开后重试 /open-in-idea。';
     case 'disabled':
       return '插件已通过 openInIde: false 关闭 IDE 启动。请手动打开 IntelliJ IDEA,在 Settings → MCP Server 开启 MCP 服务并启用 Brave Mode,然后重试 /open-in-idea。';
+    case 'closed':
+      return '已关闭当前项目的 IDEA 接入标记;IDE MCP 断开后将不再自动重连。如需重新接入,请再次执行 /open-in-idea。';
     default:
       return '已处理 /open-in-idea。';
   }
@@ -232,8 +247,9 @@ export default {
    *     transform: (cb: (editor: { add: (definition: {
    *       id: string,
    *       name: string,
-   *       description: string,
-   *       location: string,
+   *       description?: string,
+   *       autoinvoke?: boolean,
+   *       path: string,
    *       content: string,
    *     }) => void }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
    *   },
@@ -244,6 +260,8 @@ export default {
    *       agent?: string,
    *       system?: unknown[],
    *       tools?: Record<string, unknown>,
+   *       prompt?: { text?: string },
+   *       metadata?: Record<string, unknown>,
    *     }) => void | Promise<void>) => Promise<{ dispose: () => Promise<void> | void }>,
    *   },
    *   tool?: {
@@ -253,18 +271,19 @@ export default {
    *   mcp: {
    *     transform: (cb: (editor: { set: (name: string, config: unknown) => void }) => void) => Promise<{ dispose: () => Promise<void> | void }>,
    *     reload?: () => Promise<void>,
+   *     list?: () => Promise<{ data?: ReadonlyArray<{ name?: string, status?: { status?: string } }> }>,
    *   },
    *   shell: { hook: (name: string, cb: (input: { env: Record<string, string | undefined> }) => void) => Promise<{ dispose: () => Promise<void> | void }> },
+   *   storage?: {
+   *     get: (key: string) => Promise<unknown>,
+   *     set: (key: string, value: unknown) => Promise<void>,
+   *     remove: (key: string) => Promise<void>,
+   *   },
    * }} ctx
    */
   async setup(ctx) {
     const projectPath = currentProjectPath(ctx.location);
     if (!projectPath) return;
-    // Where IDEA tools can exist at all. Computed once: the recovery guidance is
-    // injected per model request, so it must not cost a filesystem check each
-    // time, and unrelated projects must not receive IDEA prompts they can never
-    // use.
-    const isIdeaProject = hasIdeaDirectory(projectPath);
 
     const options = ctx.options || {};
     const ports = asArray(options.ports, DEFAULT_PORTS);
@@ -291,11 +310,68 @@ export default {
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let sessionRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
+    let promptRegistration;
+    /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let commandRegistration;
     /** @type {{ dispose: () => Promise<void> | void } | undefined} */
     let skillRegistration;
+    let skillsRegistered = false;
     let disposed = false;
 
+    // Project-level mark: has the user opted this project into IDEA via
+    // `/open-in-idea`? One plugin instance serves one project (OpenCode
+    // activates plugins per Location), so a single boolean is the whole cache.
+    // The durable copy lives in `ctx.storage` under `project/<projectPath>`.
+    // The commands are the only writers: they persist first, then invalidate
+    // this cache so the next read comes back from storage.
+    const storage = ctx.storage;
+    const markKey = `project/${projectPath}`;
+    /** @type {boolean | undefined} undefined = a storage read is due */
+    let markCache;
+    // One auto-recovery run per project at a time; overlapping prompts share it.
+    /** @type {Promise<void> | undefined} */
+    let autoRecovering;
+
+    /** Read the durable mark into the cache; at most one storage read per invalidation. */
+    const readMark = async () => {
+      if (markCache !== undefined) return markCache;
+      if (!storage || typeof storage.get !== 'function') {
+        markCache = false;
+        return markCache;
+      }
+      try {
+        markCache = (await storage.get(markKey)) === true;
+      } catch {
+        // storage is best effort; fall back to unmarked
+        markCache = false;
+      }
+      return markCache;
+    };
+
+    /**
+     * Persist the mark, then invalidate the cache so the next reader re-reads
+     * storage. Best effort: an in-memory invalidation still applies if the write
+     * fails.
+     * @param {boolean} marked
+     */
+    const setMark = async (marked) => {
+      try {
+        if (marked) await storage?.set?.(markKey, true);
+        else await storage?.remove?.(markKey);
+      } catch {
+        // best effort
+      }
+      markCache = undefined;
+      // The skill lifecycle follows the mark: marking the project registers the
+      // IDEA skills, clearing the mark removes them again. Same semantics as the
+      // reconnect behavior, so the two can never disagree.
+      if (marked) await ensureSkills();
+      else await removeSkills();
+    };
+
+    // Resolve the mark once, so the request hooks can read it synchronously.
+    await readMark();
+
     const deactivateIde = async () => {
       const current = registrations.slice();
       registrations.length = 0;
@@ -364,7 +440,7 @@ export default {
       // Manual: only `/open-in-idea` probes the IDE. Setup calls this with
       // `probeIde: false` so it never connects until the command asks.
       const port = probeIde ? await findIdePort(ports, { timeoutMs: mcpProbeTimeoutMs }) : undefined;
-      const isJetBrains = isIdeaProject || port !== undefined;
+      const isJetBrains = markCache === true || port !== undefined;
       if (!isJetBrains) {
         currentEnv = { env: {}, prependPath: [] };
         await deactivateIde();
@@ -484,6 +560,30 @@ export default {
       return run;
     };
 
+    /**
+     * The whole `/open-in-idea` flow, shared by the command and the auto-recovery
+     * path: ensure an IDE MCP endpoint, then register it and load capabilities.
+     *
+     * @param {{ onUnavailable?: (result: IdeCommandResult) => Promise<boolean> }} [options]
+     * @returns {Promise<IdeCommandResult>}
+     */
+    const runOpenInIdea = async ({ onUnavailable } = {}) => {
+      const result = await ensureIde({ onUnavailable });
+      const { port } = result;
+      let toolsReady = false;
+      try {
+        // Do not repeat the expensive probe when the preflight already found no
+        // MCP endpoint. The command will retry after the user enables MCP +
+        // Brave Mode.
+        toolsReady = (await reconcile({ probeIde: port !== undefined })) === true;
+      } catch {
+        // capability load is best effort; feedback still matters
+      }
+      return result.status === 'connected' && !toolsReady
+        ? { ...result, status: 'tools-loading' }
+        : result;
+    };
+
     // Setup never probes or connects the IDE — everything is on `/open-in-idea`.
     await reconcile({ probeIde: false });
 
@@ -504,66 +604,153 @@ export default {
       }
     };
 
-    // The run-configuration skill is static knowledge — where `.run/*.run.xml`
-    // live, how to bootstrap a schema from a real example, and how to verify a
-    // write. JetBrains projects only, and independent of `/open-in-idea`.
+    /**
+     * Is the plugin's `idea` MCP server connected right now? OpenCode tracks
+     * every server's status in memory, and this is the authoritative "the IDE
+     * MCP is down" signal: it reflects the transport, not the result of any
+     * single tool call, so a business error can never look like a disconnect.
+     * `pending` means "still connecting" and is treated as healthy, so a server
+     * that is merely starting up is left alone.
+     *
+     * @returns {Promise<boolean>}
+     */
+    const isIdeaConnected = async () => {
+      if (typeof ctx.mcp?.list !== 'function') return false;
+      try {
+        const result = await ctx.mcp.list();
+        const servers = Array.isArray(result) ? result : (result?.data ?? []);
+        return servers.some((server) => {
+          const status = server?.status?.status;
+          return server?.name === IDEA_SERVER_NAME && (status === 'connected' || status === 'pending');
+        });
+      } catch {
+        return false;
+      }
+    };
+
+    /**
+     * Marked-project recovery: while the project is marked (the user ran
+     * `/open-in-idea`), treat the IDE as expected and rebuild the connection
+     * whenever its MCP server is not connected. Runs before the prompt's request
+     * is built, so a successful recovery makes its `idea_*` tools available to
+     * that very message.
+     *
+     * Only a confirmed reconnect is announced. A failed recovery stays silent:
+     * the per-request recovery guidance already tells the model what to say, and
+     * a notice per failed message would be noise (the launch guard, shared with
+     * the command, keeps it from re-spawning on every message).
+     *
+     * @param {string} sessionID the notice target; the mark itself is per-project
+     */
+    const autoReconnect = (sessionID) => {
+      if (autoRecovering) return autoRecovering;
+      const run = (async () => {
+        try {
+          if (disposed) return;
+          if (await isIdeaConnected()) return;
+          const result = await runOpenInIdea();
+          // A found endpoint is what counts as recovered, even if its tool
+          // catalog is still registering (`tools-loading`).
+          if (result.port === undefined) return;
+          // Queue the notice so it is delivered after the user's own message,
+          // never mixed into the same model turn as it.
+          await sendFeedback(
+            { sessionID, prompt: { text: '' }, delivery: 'queue' },
+            { status: 'connected', autoRecovered: true },
+          );
+        } catch {
+          // auto-recovery is best effort
+        }
+      })();
+      autoRecovering = run;
+      void run.finally(() => {
+        if (autoRecovering === run) autoRecovering = undefined;
+      });
+      return run;
+    };
+
+    // The shipped skills are static knowledge (`skills/<id>/SKILL.md`), e.g. the
+    // run-configuration workflow: where `.run/*.run.xml` live, how to bootstrap a
+    // schema from a real example, and how to verify a write. Registered only for
+    // a project that has been marked as an IDEA project, so unrelated projects
+    // never see an IDEA-specific skill.
     //
-    // Deliberately NOT wrapped in a catch: this is a core feature of the plugin,
+    // Deliberately NOT wrapped in a catch: these are core features of the plugin,
     // so a rejected definition must fail loudly. Swallowing it would ship a
     // silently incomplete plugin — which is exactly how 0.0.6 lost
     // `/open-in-idea` without anyone noticing until the command was gone.
-    if (isIdeaProject && typeof ctx.skill?.transform === 'function') {
-      // Read the document before the transform: callbacks must stay synchronous.
-      const runConfigSkillDefinition = runConfigSkill();
+    const ensureSkills = async () => {
+      if (skillsRegistered || typeof ctx.skill?.transform !== 'function') return;
+      skillsRegistered = true;
+      // Read the documents before the transform: callbacks must stay synchronous.
+      const skills = readSkills();
       skillRegistration = await ctx.skill.transform((editor) => {
-        editor.add(runConfigSkillDefinition);
+        for (const skill of skills) editor.add(skill);
       });
-    }
+    };
+    /** Remove the IDEA skills again when the project is unmarked. */
+    const removeSkills = async () => {
+      if (!skillsRegistered || !skillRegistration) return;
+      skillsRegistered = false;
+      const registration = skillRegistration;
+      skillRegistration = undefined;
+      try {
+        await registration.dispose();
+      } catch {
+        // best effort
+      }
+    };
+    // A project marked in an earlier run gets its skills at setup; a project
+    // marked for the first time gets them when `/open-in-idea` runs (both paths
+    // go through `setMark` / this setup hook).
+    if (markCache === true) await ensureSkills();
 
     // `/open-in-idea`: manual, re-entrant trigger that also loads the IDE
-    // capabilities immediately.
+    // capabilities immediately, and marks the project so later messages keep the
+    // IDE alive. `/close-in-idea` removes that mark. Both persist through
+    // `ctx.storage` and invalidate the in-memory cache.
     if (typeof ctx.command?.transform === 'function') {
       commandRegistration = await ctx.command.transform((editor) => {
         editor.add({
           name: 'open-in-idea',
           description: '用 IntelliJ IDEA 打开当前项目,并即时加载 IDE MCP 与项目 SDK 环境',
           execute: async (input) => {
+            // Mark the project before running: the mark means "this is an IDEA
+            // project", so it is persisted as soon as the user asks, whether or
+            // not the IDE happens to be reachable right now. `setMark` also
+            // registers the IDEA skills.
+            await setMark(true);
             /** @type {boolean} */
             let unavailableNoticeSent = false;
-            const result = await ensureIde({
+            const result = await runOpenInIdea({
               onUnavailable: async (notice) => {
                 unavailableNoticeSent = await sendFeedback(input, notice);
                 return unavailableNoticeSent;
               },
             });
-            const { port } = result;
-            let toolsReady = false;
-            try {
-              // Do not repeat the expensive probe when the preflight already
-              // found no MCP endpoint. The command will retry after the user
-              // enables MCP + Brave Mode.
-              toolsReady = (await reconcile({ probeIde: port !== undefined })) === true;
-            } catch {
-              // capability load is best effort; feedback still matters
-            }
-            const finalResult = result.status === 'connected' && !toolsReady
-              ? { ...result, status: 'tools-loading' }
-              : result;
             // The unavailable notice is the final result for this command. If
             // it was already delivered, do not show the same warning twice.
             const unavailableAlreadySent = unavailableNoticeSent || result.unavailableNoticeSent;
-            if (!unavailableAlreadySent || finalResult.status !== 'mcp-unavailable') {
-              await sendFeedback(input, finalResult);
+            if (!unavailableAlreadySent || result.status !== 'mcp-unavailable') {
+              await sendFeedback(input, result);
             }
           },
         });
+        editor.add({
+          name: 'close-in-idea',
+          description: '取消当前项目的 IDEA 接入标记,断开后不再自动重连',
+          execute: async (input) => {
+            await setMark(false);
+            await sendFeedback(input, { status: 'closed' });
+          },
+        });
       });
     }
 
     // Hide the tools the model must not see, and point it at the rest. This hook
     // runs for every agent-loop step (including tool-driven continuations), so
-    // it is deliberately a pure function of the request: no I/O, no cached
-    // connection state, and no action of its own.
+    // it stays a cheap, I/O-free function of the request: it checks the cached
+    // project mark and this request's own tool snapshot, and takes no action.
     //
     // `event.tools` is this request's tool snapshot, and OpenCode's own registry
     // adds IDEA tools when the server connects and drops them when it stops
@@ -575,13 +762,36 @@ export default {
         const tools = event?.tools;
         const serving = tools !== undefined && Object.keys(tools).some((name) => name.startsWith('idea_'));
         if (serving) removeIdeaToolDefinitions(tools, HIDDEN_IDEA_TOOLS);
-        if (isIdeaProject || serving) appendIdeRecoveryGuidance(event?.system);
+        if (markCache === true || serving) appendIdeRecoveryGuidance(event?.system);
         if (!injectGuidance) return;
         // Guidance promises tools the model can call, so it only goes out when
         // they are actually in this request.
         if (!serving) return;
         appendIdeGuidance(event?.system, projectPath);
       });
+
+      // Project-level auto-recovery. The only self-initiated action in the
+      // plugin, and only for a marked project. It belongs to the `prompt` hook
+      // (not `context`) because the tool catalog for a request is already fixed
+      // by the time `context` runs: a `prompt`-time reconnect is what lets the
+      // message that triggered it use `idea_*` tools.
+      //
+      // The returned promise is awaited by OpenCode before the request is built,
+      // so a slow cold start delays that message — the accepted cost of treating
+      // a marked project's IDE as always up.
+      promptRegistration = await ctx.session.hook('prompt', async (event) => {
+        const sessionID = event?.sessionID;
+        if (typeof sessionID !== 'string') return;
+        // Never react to the plugin's own notices, or auto-recovery would feed
+        // on itself. Notices carry `metadata.displayText`; the prefix guards
+        // against an older notice shape.
+        const displayText = event?.metadata?.displayText;
+        if (typeof displayText === 'string') return;
+        const text = event?.prompt?.text;
+        if (typeof text === 'string' && text.startsWith('【插件通知】')) return;
+        if (!(await readMark())) return;
+        return autoReconnect(sessionID);
+      });
     }
 
     return async () => {
@@ -600,6 +810,13 @@ export default {
           // best effort
         }
       }
+      if (promptRegistration) {
+        try {
+          await promptRegistration.dispose();
+        } catch {
+          // best effort
+        }
+      }
       if (commandRegistration) {
         try {
           await commandRegistration.dispose();

package/src/project.js

@@ -1,8 +1,5 @@
 // Pure helpers for locating the current OpenCode project.
 
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-
 /**
  * Resolve the absolute project root for the current plugin location.
  * OpenCode exposes a `Location.Info` on the plugin context.
@@ -15,15 +12,3 @@ export function currentProjectPath(location) {
   const projectDirectory = location.project && location.project.directory;
   return projectDirectory || location.directory || undefined;
 }
-
-/**
- * True when the directory looks like a JetBrains project (has a `.idea` folder).
- * This is a convenience signal only; the plugin does not require it, because an
- * IDE may have created the project entry without writing `.idea` yet.
- *
- * @param {string | undefined} directory
- * @returns {boolean}
- */
-export function hasIdeaDirectory(directory) {
-  return typeof directory === 'string' && existsSync(path.join(directory, '.idea'));
-}

package/src/skill/loader.js

@@ -0,0 +1,105 @@
+// The skills this plugin ships, loaded from `skills/<id>/SKILL.md`.
+//
+// This directory holds the *code* (singular `src/skill/`); the documents live in
+// the package-root `skills/` (plural), so reviewing the feature means two clearly
+// named places: the loader here, the content there.
+//
+// The layout mirrors the convention OpenCode itself reads: one directory per
+// skill, the document named `SKILL.md`, `name`/`description` in YAML
+// frontmatter, and the directory as the base for any relative asset the skill
+// ships next to it. Adding a skill is therefore a directory, not a code change.
+//
+// Three contract details are enforced deliberately:
+//   * `description` is required. OpenCode drops a skill without one from the
+//     model-facing list, so a missing description would silently disable the
+//     skill instead of failing.
+//   * the returned definition must satisfy `Skill.Info` exactly (`id` / `name` /
+//     `description` / `path` / `content`). A rejected definition fails the skill
+//     transform, and a transform failure disables the whole plugin.
+//   * `content` is the document body only. The frontmatter is metadata and must
+//     not leak into the model prompt.
+//
+// The frontmatter reader below handles only the flat `key: value` form this
+// package writes. It is not a YAML engine and must not grow into one.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/** Package-root `skills/`: one sub-directory per skill, next to `src/`. */
+const SKILLS_DIR = new URL('../../skills/', import.meta.url);
+
+/** Document name inside each skill directory. */
+export const SKILL_FILE_NAME = 'SKILL.md';
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n)?/;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function unquote(value) {
+  const quote = value[0];
+  if (value.length >= 2 && (quote === '"' || quote === "'") && value.endsWith(quote)) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Read the flat `key: value` frontmatter block a `SKILL.md` must start with.
+ *
+ * @param {string} text
+ * @param {string} source Used in error messages.
+ * @returns {Record<string, string>}
+ */
+export function parseSkillFrontmatter(text, source) {
+  const match = FRONTMATTER.exec(text);
+  if (!match) throw new Error(`${source}: ${SKILL_FILE_NAME} must start with a YAML frontmatter block`);
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const raw of match[1].split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const entry = /^([A-Za-z0-9_/-]+):[ \t]*(.*)$/.exec(line);
+    if (!entry) throw new Error(`${source}: unsupported frontmatter line: ${line}`);
+    fields[entry[1]] = unquote(entry[2].trim());
+  }
+  return fields;
+}
+
+/**
+ * Load one skill directory into a `Skill.Info`-shaped definition.
+ *
+ * @param {string} id Directory name, used as the skill id.
+ * @returns {{ id: string, name: string, description: string, path: string, content: string }}
+ */
+export function readSkill(id) {
+  const file = new URL(`${id}/${SKILL_FILE_NAME}`, SKILLS_DIR);
+  const source = `skills/${id}/${SKILL_FILE_NAME}`;
+  const text = readFileSync(file, 'utf8');
+  const fields = parseSkillFrontmatter(text, source);
+  const description = fields.description;
+  if (!description) {
+    throw new Error(`${source}: frontmatter needs a "description", otherwise the skill is never offered`);
+  }
+  return {
+    id,
+    name: fields.name || id,
+    description,
+    path: fileURLToPath(file),
+    content: text.replace(FRONTMATTER, '').replace(/^\s+/, '').trimEnd(),
+  };
+}
+
+/**
+ * Every shipped skill, sorted by id.
+ *
+ * @returns {Array<{ id: string, name: string, description: string, path: string, content: string }>}
+ */
+export function readSkills() {
+  return readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((id) => readSkill(id));
+}