@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/normalise/mcp-servers.ts

@@ -0,0 +1,427 @@
+/**
+ * MCP server entries, from every configuration source, into the two shapes
+ * `McpServerSpec` takes.
+ *
+ * The open format and the vendor dialects differ on strictness and the
+ * source's dialect decides: an open `mcp.json` requires `type` and closes
+ * each transport's field set (an unknown field refuses the entry), while a
+ * vendor `.mcp.json` infers the transport from `command` or `url` and
+ * carries fields Stigmer does not read as warnings (Cursor's undocumented
+ * `auth` block has its own, because OAuth on Stigmer has its own home in the
+ * `ai.stigmer/` overlay). `streamable-http` and `http` are one transport;
+ * the legacy `sse` maps to it with a warning, because the runner connects
+ * both with Streamable HTTP and its adapter falls back to SSE when the
+ * server rejects that.
+ *
+ * Four refusals are facts about the runner, not preferences: it mounts no
+ * plugin files (so a `./`-relative command, any plugin-root placeholder,
+ * and any `cwd` can never resolve); it sends a server's `url` as written
+ * (so a `${VAR}` there would be sent literally); and it hands a stdio
+ * subprocess exactly the variables the spec declares, by name (so an `env`
+ * entry is representable only as `KEY: "${KEY}"`).
+ *
+ * Every `${VAR}` in a header, an argument, an `env` value or an `auth` value
+ * is a reference to the caller's Environment, listed on the server's `env`;
+ * the variables module declares the undeclared ones. Claude's
+ * `${user_config.KEY}` is rewritten to `${KEY}` before anything is scanned.
+ */
+
+import type { McpConfigSource } from "../dialects/manifest.js";
+import {
+  describeValue,
+  fields,
+  isJsonObject,
+  isStringArray,
+  isStringRecord,
+  type JsonObject,
+  parseJsonObject,
+  readText,
+} from "../documents.js";
+import type { PluginFileIndex } from "../files.js";
+import { AGENT_PLUGINS_MCP_SCHEMA, type Findings } from "../messages.js";
+import {
+  findPluginRootPlaceholder,
+  PLUGIN_ROOT_ENV_NAMES,
+  referencedVariables,
+  rewriteUserConfig,
+  singlePlaceholderName,
+  VARIABLE_NAME_PATTERN,
+} from "../placeholders.js";
+import type { PluginMcpServer } from "../types.js";
+
+const OPEN_CONFIG_FIELDS: ReadonlySet<string> = new Set(["$schema", "mcpServers"]);
+const OPEN_STDIO_FIELDS: ReadonlySet<string> = new Set(["type", "command", "args", "env", "cwd"]);
+const OPEN_HTTP_FIELDS: ReadonlySet<string> = new Set(["type", "url", "headers"]);
+const VENDOR_STDIO_FIELDS: ReadonlySet<string> = new Set(["type", "command", "args", "env", "cwd"]);
+const VENDOR_HTTP_FIELDS: ReadonlySet<string> = new Set(["type", "url", "headers"]);
+
+// RFC 9110 token characters, the set a header field name may use.
+const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+type Transport = "stdio" | "http";
+
+export interface McpServersResult {
+  readonly servers: readonly PluginMcpServer[];
+  /**
+   * How many entries were refused. The variables stage reads it: a refused
+   * server's references are unknown, so "declared but unreferenced" would be
+   * a consequence of the refusal rather than advice, and is not warned.
+   */
+  readonly refused: number;
+  /**
+   * Every server name the sources declared, accepted or refused. The overlay
+   * checks against this, so a refused server's overlay is not a second refusal.
+   */
+  readonly declaredNames: ReadonlySet<string>;
+}
+
+export function normaliseMcpServers(index: PluginFileIndex, sources: readonly McpConfigSource[], findings: Findings): McpServersResult {
+  const servers: PluginMcpServer[] = [];
+  const seen = new Set<string>();
+  let refused = 0;
+  for (const source of sources) {
+    const entries = readSource(index, source, findings);
+    if (entries === undefined) {
+      refused++;
+      continue;
+    }
+    for (const [name, raw] of fields(entries.servers)) {
+      if (seen.has(name)) {
+        findings.error("mcp-server-name-duplicate", { subject: name, path: entries.path });
+        refused++;
+        continue;
+      }
+      seen.add(name);
+      const server = readServer(name, raw, entries.path, source.dialect === "agent-plugins", findings);
+      if (server !== undefined) servers.push(server);
+      else refused++;
+    }
+  }
+  return { servers, refused, declaredNames: seen };
+}
+
+interface ServerEntries {
+  readonly path: string;
+  readonly servers: JsonObject;
+}
+
+function readSource(index: PluginFileIndex, source: McpConfigSource, findings: Findings): ServerEntries | undefined {
+  const open = source.dialect === "agent-plugins";
+  if (source.kind === "inline") {
+    // An inline value is either the whole configuration shape or the
+    // server map itself; both are seen in the wild and both mean one thing.
+    const wrapped = isJsonObject(source.servers) ? source.servers["mcpServers"] : undefined;
+    const servers = isJsonObject(wrapped) ? wrapped : source.servers;
+    if (!isJsonObject(servers)) {
+      findings.error("mcp-config-shape", { path: source.manifest });
+      return undefined;
+    }
+    return { path: source.manifest, servers };
+  }
+
+  if (!index.has(source.path)) {
+    findings.warn("path-missing", { path: source.manifest, subject: `./${source.path}` });
+    return undefined;
+  }
+  const text = readText(index, source.path, "mcpConfig", findings);
+  if (text === undefined) return undefined;
+  const object = parseJsonObject(text, source.path, "mcp-config-unreadable", findings);
+  if (object === undefined) return undefined;
+
+  if (open) {
+    const schema = object["$schema"];
+    if (schema === undefined) {
+      findings.error("mcp-config-schema-missing", { path: source.path });
+    } else if (schema !== AGENT_PLUGINS_MCP_SCHEMA) {
+      findings.error("mcp-config-schema-unsupported", { path: source.path, detail: describeValue(schema) });
+    }
+  }
+  for (const [name] of fields(object)) {
+    if (OPEN_CONFIG_FIELDS.has(name)) continue;
+    if (open) findings.error("mcp-config-field-unknown", { path: source.path, subject: name });
+    else findings.warn("mcp-config-field-ignored", { path: source.path, subject: name });
+  }
+  const servers = object["mcpServers"];
+  if (!isJsonObject(servers)) {
+    findings.error("mcp-config-shape", { path: source.path });
+    return undefined;
+  }
+  return { path: source.path, servers };
+}
+
+function readServer(name: string, raw: unknown, path: string, open: boolean, findings: Findings): PluginMcpServer | undefined {
+  const ctx = { subject: name, path };
+  if (!isJsonObject(raw)) {
+    findings.error("mcp-server-shape", ctx);
+    return undefined;
+  }
+  const transport = resolveTransport(raw, ctx, open, findings);
+  if (transport === undefined) return undefined;
+
+  const known = transport === "stdio" ? (open ? OPEN_STDIO_FIELDS : VENDOR_STDIO_FIELDS) : open ? OPEN_HTTP_FIELDS : VENDOR_HTTP_FIELDS;
+  const references = new Set<string>();
+  let valid = true;
+  for (const [field, value] of fields(raw)) {
+    if (known.has(field)) continue;
+    if (open) {
+      findings.error("mcp-server-field-unknown", { ...ctx, detail: field });
+      valid = false;
+    } else if (field === "auth") {
+      findings.warn("mcp-server-auth-ignored", ctx);
+      for (const text of stringsWithin(value)) collectReferences(text, references);
+    } else {
+      findings.warn("mcp-server-field-ignored", { ...ctx, detail: field });
+    }
+  }
+  if (!valid) return undefined;
+
+  return transport === "stdio" ? readStdio(name, raw, ctx, references, findings) : readHttp(name, raw, ctx, references, findings);
+}
+
+interface Ctx {
+  readonly subject: string;
+  readonly path: string;
+}
+
+function resolveTransport(raw: JsonObject, ctx: Ctx, open: boolean, findings: Findings): Transport | undefined {
+  const type = raw["type"];
+  if (type !== undefined && typeof type !== "string") {
+    findings.error("mcp-server-field-type", { ...ctx, detail: "type" });
+    return undefined;
+  }
+  if (type === undefined) {
+    if (open) {
+      findings.error("mcp-server-type-missing", ctx);
+      return undefined;
+    }
+    const hasCommand = raw["command"] !== undefined;
+    const hasUrl = raw["url"] !== undefined;
+    if (hasCommand && hasUrl) {
+      findings.error("mcp-server-type-ambiguous", ctx);
+      return undefined;
+    }
+    if (hasCommand) return "stdio";
+    if (hasUrl) return "http";
+    findings.error("mcp-server-transport-unknown", ctx);
+    return undefined;
+  }
+  switch (type) {
+    case "stdio":
+      return "stdio";
+    case "streamable-http":
+      return "http";
+    case "http":
+      if (open) {
+        findings.error("mcp-server-type-unknown", { ...ctx, detail: type });
+        return undefined;
+      }
+      return "http";
+    case "sse":
+      findings.warn("mcp-server-sse-mapped", ctx);
+      return "http";
+    default:
+      findings.error("mcp-server-type-unknown", { ...ctx, detail: type });
+      return undefined;
+  }
+}
+
+function readStdio(name: string, raw: JsonObject, ctx: Ctx, references: Set<string>, findings: Findings): PluginMcpServer | undefined {
+  let valid = true;
+  const fail = (): void => {
+    valid = false;
+  };
+
+  const command = raw["command"];
+  if (command === undefined) {
+    findings.error("mcp-server-command-missing", ctx);
+    fail();
+  } else if (typeof command !== "string") {
+    findings.error("mcp-server-field-type", { ...ctx, detail: "command" });
+    fail();
+  } else {
+    const root = findPluginRootPlaceholder(command);
+    if (root !== undefined) {
+      findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: root });
+      fail();
+    } else if (command.startsWith("./")) {
+      findings.error("mcp-server-command-relative", { ...ctx, detail: command });
+      fail();
+    } else if (command === "" || /\s/.test(command) || command.includes("/")) {
+      findings.error("mcp-server-command-invalid", ctx);
+      fail();
+    }
+  }
+
+  const args: string[] = [];
+  const rawArgs = raw["args"];
+  if (rawArgs !== undefined) {
+    if (!isStringArray(rawArgs)) {
+      findings.error("mcp-server-field-type", { ...ctx, detail: "args" });
+      fail();
+    } else {
+      for (const arg of rawArgs) {
+        const rewritten = rewriteUserConfig(arg);
+        const root = findPluginRootPlaceholder(rewritten);
+        if (root !== undefined) {
+          findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: root });
+          fail();
+          continue;
+        }
+        collectReferences(rewritten, references);
+        args.push(rewritten);
+      }
+    }
+  }
+
+  const rawEnv = raw["env"];
+  if (rawEnv !== undefined) {
+    if (!isStringRecord(rawEnv)) {
+      findings.error("mcp-server-field-type", { ...ctx, detail: "env" });
+      fail();
+    } else {
+      for (const [key, value] of Object.entries(rawEnv)) {
+        if (PLUGIN_ROOT_ENV_NAMES.has(key)) {
+          findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: key });
+          fail();
+          continue;
+        }
+        if (!VARIABLE_NAME_PATTERN.test(key)) {
+          findings.error("variable-name-invalid", { subject: key, path: ctx.path });
+          fail();
+          continue;
+        }
+        const rewritten = rewriteUserConfig(value);
+        const root = findPluginRootPlaceholder(rewritten);
+        if (root !== undefined) {
+          findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: root });
+          fail();
+          continue;
+        }
+        const referenced = singlePlaceholderName(rewritten);
+        if (referenced === undefined) {
+          findings.error("mcp-server-env-literal", { ...ctx, detail: key });
+          fail();
+        } else if (referenced !== key) {
+          findings.error("mcp-server-env-rename", { ...ctx, detail: key });
+          fail();
+        } else {
+          references.add(key);
+        }
+      }
+    }
+  }
+
+  if (raw["cwd"] !== undefined) {
+    findings.error("mcp-server-cwd-unsupported", ctx);
+    fail();
+  }
+
+  if (!valid || typeof command !== "string") return undefined;
+  return { name, transport: "stdio", command, args, env: [...references].sort() };
+}
+
+function readHttp(name: string, raw: JsonObject, ctx: Ctx, references: Set<string>, findings: Findings): PluginMcpServer | undefined {
+  let valid = true;
+  const fail = (): void => {
+    valid = false;
+  };
+
+  let url: string | undefined;
+  const rawUrl = raw["url"];
+  if (rawUrl === undefined) {
+    findings.error("mcp-server-url-missing", ctx);
+    fail();
+  } else if (typeof rawUrl !== "string") {
+    findings.error("mcp-server-field-type", { ...ctx, detail: "url" });
+    fail();
+  } else {
+    url = rewriteUserConfig(rawUrl);
+    const root = findPluginRootPlaceholder(url);
+    if (root !== undefined) {
+      findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: root });
+      fail();
+    } else if (referencedVariables(url).length > 0) {
+      findings.error("mcp-server-url-variable", ctx);
+      fail();
+    } else if (!isAcceptableServerUrl(url)) {
+      findings.error("mcp-server-url-invalid", { ...ctx, detail: url });
+      fail();
+    }
+  }
+
+  // Collected as pairs and materialised with `Object.fromEntries`, which
+  // defines own properties: a header literally named `__proto__` (a valid
+  // token) must become a key, never a prototype assignment.
+  const headers: [string, string][] = [];
+  const rawHeaders = raw["headers"];
+  if (rawHeaders !== undefined) {
+    if (!isStringRecord(rawHeaders)) {
+      findings.error("mcp-server-field-type", { ...ctx, detail: "headers" });
+      fail();
+    } else {
+      const lowered = new Set<string>();
+      for (const [header, value] of Object.entries(rawHeaders)) {
+        if (!HEADER_NAME_PATTERN.test(header)) {
+          findings.error("mcp-server-header-invalid", { ...ctx, detail: header });
+          fail();
+          continue;
+        }
+        const key = header.toLowerCase();
+        if (lowered.has(key)) {
+          findings.error("mcp-server-header-duplicate", { ...ctx, detail: header });
+          fail();
+          continue;
+        }
+        lowered.add(key);
+        const rewritten = rewriteUserConfig(value);
+        const root = findPluginRootPlaceholder(rewritten);
+        if (root !== undefined) {
+          findings.error("mcp-server-plugin-root-reference", { ...ctx, detail: root });
+          fail();
+          continue;
+        }
+        collectReferences(rewritten, references);
+        headers.push([header, rewritten]);
+      }
+    }
+  }
+
+  if (!valid || url === undefined) return undefined;
+  return { name, transport: "http", url, headers: Object.fromEntries(headers), env: [...references].sort() };
+}
+
+/**
+ * The open format's URL rule: absolute HTTP(S), no user information, no
+ * fragment, HTTPS unless the host is loopback. Applied in every dialect
+ * because the runner's `HttpServerConfig.url` must be a URI and a plugin
+ * that fails here would fail there.
+ */
+function isAcceptableServerUrl(value: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.username !== "" || url.password !== "" || url.hash !== "") return false;
+  if (url.protocol === "https:") return true;
+  if (url.protocol !== "http:") return false;
+  return isLoopbackHost(url.hostname);
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  if (hostname === "localhost" || hostname === "[::1]" || hostname === "::1") return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+}
+
+function collectReferences(text: string, into: Set<string>): void {
+  for (const name of referencedVariables(text)) into.add(name);
+}
+
+/** Every string nested anywhere in a JSON value (the `auth` block's values). */
+function stringsWithin(value: unknown): readonly string[] {
+  if (typeof value === "string") return [rewriteUserConfig(value)];
+  if (Array.isArray(value)) return value.flatMap(stringsWithin);
+  if (isJsonObject(value)) return Object.values(value).flatMap(stringsWithin);
+  return [];
+}

package/src/normalise/overlay.ts

@@ -0,0 +1,71 @@
+/**
+ * Stigmer's own extension folder, `ai.stigmer/`: located and checked here,
+ * parsed by the installer.
+ *
+ * The open format gives each client a reverse-domain directory other clients
+ * ignore; Stigmer's carries what no portable component can say: a full
+ * `Agent` that replaces the composed default (`agent.yaml`), `Workflow`s
+ * (`workflows/<name>.yaml`), and the richer `McpServer` overlay for a
+ * declared server (`mcp-servers/<server>.yaml`: auth, scope hints, default
+ * tools). The library hands these over as bytes with their paths and keeps
+ * no knowledge of the resource schemas; the installer parses them where
+ * the protos live.
+ *
+ * Two checks are the library's because they are about the plugin, not the
+ * resources: an overlay for a server the plugin does not declare is refused
+ * (an overlay that silently applies to nothing is the drift the model
+ * exists to prevent), and a file under `ai.stigmer/` that is none of the
+ * three document shapes is refused for the same reason (`agent.yml` would
+ * otherwise be a typo that installs the composed default).
+ */
+
+import { readBytes } from "../documents.js";
+import { basename, dirname, type PluginFileIndex } from "../files.js";
+import type { Findings } from "../messages.js";
+import type { OverlayNamedDocument, OverlayServerDocument, StigmerOverlay } from "../types.js";
+
+export const OVERLAY_DIR = "ai.stigmer";
+const AGENT_DOCUMENT = `${OVERLAY_DIR}/agent.yaml`;
+const WORKFLOWS_DIR = `${OVERLAY_DIR}/workflows`;
+const MCP_SERVERS_DIR = `${OVERLAY_DIR}/mcp-servers`;
+
+/** `serverNames` is every server the plugin DECLARED, refused ones included, so a refused server's overlay is not blamed twice. */
+export function normaliseOverlay(index: PluginFileIndex, serverNames: ReadonlySet<string>, findings: Findings): StigmerOverlay {
+  const overlay: { -readonly [K in keyof StigmerOverlay]: StigmerOverlay[K] } = { workflows: [], mcpServers: [] };
+  const workflows: OverlayNamedDocument[] = [];
+  const mcpServers: OverlayServerDocument[] = [];
+
+  for (const path of index.filesUnder(OVERLAY_DIR)) {
+    if (path === AGENT_DOCUMENT) {
+      const bytes = readBytes(index, path, "overlay", findings);
+      if (bytes !== undefined) overlay.agent = { path, bytes };
+      continue;
+    }
+    const name = yamlStem(path);
+    if (name !== undefined && dirname(path) === WORKFLOWS_DIR) {
+      const bytes = readBytes(index, path, "overlay", findings);
+      if (bytes !== undefined) workflows.push({ path, bytes, name });
+      continue;
+    }
+    if (name !== undefined && dirname(path) === MCP_SERVERS_DIR) {
+      if (!serverNames.has(name)) {
+        findings.error("overlay-server-unknown", { path, subject: name });
+        continue;
+      }
+      const bytes = readBytes(index, path, "overlay", findings);
+      if (bytes !== undefined) mcpServers.push({ path, bytes, server: name });
+      continue;
+    }
+    findings.error("overlay-document-unknown", { path });
+  }
+
+  overlay.workflows = workflows;
+  overlay.mcpServers = mcpServers;
+  return overlay;
+}
+
+/** The file stem of a `.yaml` document, or `undefined` for any other file. */
+function yamlStem(path: string): string | undefined {
+  const name = basename(path);
+  return name.endsWith(".yaml") && name.length > ".yaml".length ? name.slice(0, -".yaml".length) : undefined;
+}

package/src/normalise/skills.ts

@@ -0,0 +1,126 @@
+/**
+ * Skill discovery and the `SKILL.md` frontmatter check.
+ *
+ * Discovery follows the union of the dialects' rules: the immediate child
+ * directories of `skills/` that hold a `SKILL.md` (the open format's fixed
+ * location, no recursion), plus every path a manifest declared (Claude adds
+ * to the default; Cursor's value is the default in practice), where a
+ * declared path is a skill when it holds `SKILL.md` directly and a directory
+ * of skills otherwise, plus Claude's single-skill layout (a root `SKILL.md`
+ * with no `skills/` and no declaration). A declared path that names nothing
+ * is a warning: Cursor's own tooling does not refuse it, and refusing would
+ * turn a stale manifest line into a failed install.
+ *
+ * The frontmatter check is a discovery check, not the push gate: it asks
+ * that the block be present and closed, that it parse, and that `name`
+ * satisfy `SKILL_NAME_PATTERN`. A missing `name` falls back to the directory
+ * name (Claude's rule) with a warning; the Agent Skills rules Stigmer relaxes
+ * (`name` equal to the directory, `description` present) are warnings.
+ * Optional frontmatter (`license`, `compatibility`, `metadata`,
+ * `allowed-tools`) and vendor keys ride inside the skill untouched. Every
+ * file under the skill directory is listed for the installer's per-skill
+ * archive; only `SKILL.md` is ever read.
+ */
+
+import type { ManifestSet } from "../detect.js";
+import { readText } from "../documents.js";
+import { basename, comparePaths, joinPath, type PluginFileIndex } from "../files.js";
+import { extractFrontmatter, parseFrontmatter, SKILL_NAME_PATTERN } from "../frontmatter.js";
+import type { Findings } from "../messages.js";
+import type { PluginSkill } from "../types.js";
+
+export const SKILL_FILE = "SKILL.md";
+export const DEFAULT_SKILLS_DIR = "skills";
+
+export function normaliseSkills(index: PluginFileIndex, set: ManifestSet, findings: Findings): readonly PluginSkill[] {
+  const skills: PluginSkill[] = [];
+  const seenNames = new Map<string, string>();
+
+  for (const dir of discoverSkillDirs(index, set, findings)) {
+    const skill = readSkill(index, dir, set, findings);
+    if (skill === undefined) continue;
+    const previous = seenNames.get(skill.name);
+    if (previous !== undefined) {
+      findings.error("skill-name-duplicate", { subject: skill.name, path: joinPath(dir, SKILL_FILE) });
+      continue;
+    }
+    seenNames.set(skill.name, dir);
+    skills.push(skill);
+  }
+  return skills;
+}
+
+/** Skill directories, deduplicated, in path order; the root skill is `""`. */
+function discoverSkillDirs(index: PluginFileIndex, set: ManifestSet, findings: Findings): readonly string[] {
+  const dirs = new Set<string>();
+  const addSkillsUnder = (parent: string): void => {
+    for (const child of index.childDirectories(parent)) {
+      const dir = joinPath(parent, child);
+      if (index.has(joinPath(dir, SKILL_FILE))) dirs.add(dir);
+    }
+  };
+
+  addSkillsUnder(DEFAULT_SKILLS_DIR);
+
+  const declared = set.manifests.flatMap((m) => m.skillPaths);
+  for (const { path, manifest } of declared) {
+    if (index.has(joinPath(path, SKILL_FILE))) {
+      dirs.add(path);
+    } else if (index.isDirectory(path)) {
+      addSkillsUnder(path);
+    } else {
+      findings.warn("path-missing", { path: manifest, subject: path === "" ? "." : `./${path}` });
+    }
+  }
+
+  if (declared.length === 0 && !index.isDirectory(DEFAULT_SKILLS_DIR) && index.has(SKILL_FILE)) {
+    dirs.add("");
+  }
+
+  return [...dirs].sort(comparePaths);
+}
+
+function readSkill(index: PluginFileIndex, dir: string, set: ManifestSet, findings: Findings): PluginSkill | undefined {
+  const path = joinPath(dir, SKILL_FILE);
+  const text = readText(index, path, "skillMd", findings);
+  if (text === undefined) return undefined;
+
+  const extracted = extractFrontmatter(text);
+  if (!extracted.ok) {
+    findings.error(extracted.reason === "missing" ? "skill-frontmatter-missing" : "skill-frontmatter-unclosed", { path });
+    return undefined;
+  }
+  const parsed = parseFrontmatter(extracted.yaml);
+  if (!parsed.ok) {
+    findings.error("skill-frontmatter-unreadable", { path, detail: parsed.detail });
+    return undefined;
+  }
+
+  const directoryName = dir === "" ? (set.name ?? "skill") : basename(dir);
+  let name: string;
+  if (typeof parsed.fields["name"] === "string" && parsed.fields["name"] !== "") {
+    name = parsed.fields["name"];
+  } else {
+    name = directoryName;
+    findings.warn("skill-name-defaulted", { path, subject: name });
+  }
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    findings.error("skill-name-invalid", { path, subject: name });
+    return undefined;
+  }
+  if (dir !== "" && name !== directoryName) {
+    findings.warn("skill-name-differs-from-directory", { path, subject: name, detail: directoryName });
+  }
+
+  const description = parsed.fields["description"];
+  if (typeof description !== "string" || description === "") {
+    findings.warn("skill-description-missing", { path, subject: name });
+  }
+
+  return {
+    name,
+    ...(typeof description === "string" && description !== "" && { description }),
+    dir,
+    files: index.filesUnder(dir),
+  };
+}