feat: Skills extension phase 3 — CLI, TUI, directory reads, frontmatter check

Closes #2248.

Completes SEP-2640 support across all three clients, and closes the one
obligation #2234 deliberately left open.

- `checkSkillFrontmatterMatch` compares a served SKILL.md's own YAML
  frontmatter against the entry the listing advertised, field by field. No
  digest can cover this: a digest is taken over the bytes the server served,
  so it proves the file was not altered in transit and says nothing about
  whether the listing described it honestly. Needs a real YAML parser; `yaml`
  was already a root dependency, so this adds no package — but it does newly
  put it on core/'s import graph, hence the three bundler `external` lists.

- `resources/directory/read`: result schemas defined against the normative
  text, `InspectorClient.readResourceDirectory`, a Directory section on the
  Skills screen, and `--method resources/directory/read` in the CLI. The
  client refuses the call locally when the server did not declare
  `directoryRead`, which is the SEP's MUST NOT. A child the directory lists
  but the entry does not is marked `not listed` rather than merged into the
  manifest — the SEP calls a directory result a live observation and forbids
  treating it as extending the manifest.

- CLI: `skills/list`, `skills/get` and `resources/directory/read`, plus
  `--verify` — one NDJSON report per skill, a summary on stderr, exit 7 on a
  violation. Reads are sequential; a conforming manifest may declare 512
  entries.

- TUI: a Skills pane, shown only when the server declares the extension. Each
  row carries its conformance verdict as a glyph as well as a colour, since
  the pane is read over ssh and through script(1). Enter verifies.

- `verifySkills` re-throws `AuthRecoveryRequiredError` rather than recording
  it per file: it says the session's authorization expired, so absorbing it
  would report N identical read failures and swallow the error the TUI and
  the web commands key off to reauthorize.

Two open questions settled, both in code comments where they will be found:
`skills/get` carries no caching attributes because SEP-2640 leaves the
question open in as many words, so requiring them would fail a conforming
server; and there is no `PagedSkillsState` because every consumer of this
list is a whole-catalog verdict — computed over page one of three, "this
server's skills conform" is not merely partial but wrong.

The fixture grows two skills, both for checks that were otherwise
undemonstrable: `lying-listing` (listing and file disagree, digest still
verifies) and `stale-manifest` (serves a file its manifest does not declare).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ND46Ci64DC3tzBy9aG81Nc
Signed-off-by: cliffhall <cliff@futurescale.com>

clients/cli/src/cli.ts

@@ -679,7 +679,14 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
       parseKeyValuePair,
       {},
     )
-    .option("--uri <uri>", "URI of the resource (for resources/read method)")
+    .option(
+      "--uri <uri>",
+      "URI of the resource (resources/read, resources/directory/read) or of the skill (skills/get)",
+    )
+    .option(
+      "--cursor <cursor>",
+      "Opaque pagination cursor (for resources/directory/read; pass back the nextCursor from the previous page).",
+    )
     .option(
       "--prompt-name <promptName>",
       "Name of the prompt (for prompts/get method)",
@@ -743,6 +750,10 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
       "--strict",
       "Report tool-schema portability problems in full (path, issue, suggested fix) on stderr, and exit 6 if any is error-severity. Use with --method tools/list. Without it, a one-line count is printed instead.",
     )
+    .option(
+      "--verify",
+      "Run the SEP-2640 conformance and digest checks over the skills returned, emit one JSON report per skill on stdout, and exit 7 if any fails. Use with --method skills/list or --method skills/get.",
+    )
     .option(
       "--connect-timeout <ms>",
       `Connection timeout in ms (default ${DEFAULT_CONNECT_TIMEOUT_MS} for ad-hoc --server-url / target invocations; 0 = no timeout).`,
@@ -848,6 +859,8 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     header?: Record<string, string>;
     appInfo?: boolean;
     strict?: boolean;
+    verify?: boolean;
+    cursor?: string;
     connectTimeout?: number;
     format?: OutputFormat;
     toolArgsJson?: string;
@@ -919,6 +932,18 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     }
   }
 
+  // `--verify` is checked here for exactly the reason `--strict` is: the
+  // short-circuit returns below never reach `runMethod`, so validating further
+  // down would let `--verify --method servers/list` succeed while silently
+  // ignoring a flag documented as skills-only.
+  if (options.verify) {
+    if (options.method !== "skills/list" && options.method !== "skills/get") {
+      throw new Error(
+        "--verify requires --method skills/list or --method skills/get.",
+      );
+    }
+  }
+
   // State-path precedence (getStateFilePath): MCP_INSPECTOR_OAUTH_STATE_PATH →
   // <MCP_STORAGE_DIR>/oauth.json → ~/.mcp-inspector/storage/oauth.json — the
   // same file the web backend writes, so tokens are shared across surfaces.
@@ -1147,6 +1172,8 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     toolMeta: options.toolMetadata,
     appInfo: options.appInfo === true,
     strict: options.strict === true,
+    verify: options.verify === true,
+    cursor: options.cursor,
     format: options.format,
   };
 

clients/cli/src/error-handler.ts

@@ -25,6 +25,16 @@ export const EXIT_CODES = {
   UNREACHABLE: 4,
   TOOL_ERROR: 5,
   SCHEMA_UNPORTABLE: 6,
+  /**
+   * `--verify` found a SEP-2640 violation: a conformance error, a digest or
+   * size mismatch, or a manifest file that could not be read (#2248).
+   *
+   * Its own code rather than reusing `SCHEMA_UNPORTABLE`, for the reason that
+   * one exists at all: a CI job that fails on an unportable tool schema and a
+   * CI job that fails on a tampered skill digest are different jobs, and
+   * collapsing them would make `if [ $? -eq 6 ]` ambiguous.
+   */
+  SKILL_NONCONFORMANT: 7,
 } as const;
 
 /** Machine-readable error envelope written as one JSON line on stderr. */

clients/cli/src/handlers/consume-outcome.ts

@@ -1,4 +1,5 @@
-import { awaitableLog } from "../utils/awaitable-log.js";
+import { awaitableError, awaitableLog } from "../utils/awaitable-log.js";
+import { CliExitCodeError } from "../error-handler.js";
 import { emitResult } from "./emit-result.js";
 import type { MethodArgs, MethodOutcome } from "./method-types.js";
 
@@ -21,6 +22,17 @@ export async function consumeMethodOutcome(
     for (const line of outcome.lines) {
       await awaitableLog(JSON.stringify(line) + "\n");
     }
+    // Summary on **stderr**, after the report, so it cannot contaminate the
+    // NDJSON a consumer is parsing on stdout.
+    if (outcome.summary) await awaitableError(`${outcome.summary}\n`);
+    // Thrown rather than returned so it routes through the CLI's single exit
+    // path — the report has already been written, which is why this is the
+    // last thing that happens.
+    if (outcome.exitCode) {
+      throw new CliExitCodeError(outcome.exitCode, outcome.summary ?? "", {
+        code: "skills_nonconformant",
+      });
+    }
     return;
   }
 

clients/cli/src/handlers/method-types.ts

@@ -34,6 +34,18 @@ export type MethodArgs = {
   taskId?: string;
   /** When true, tools/call uses callToolStream (task-augmented). */
   task?: boolean;
+  /**
+   * `--verify`: run the SEP-2640 conformance and digest checks over the skills
+   * a `skills/list` / `skills/get` returned, emit one NDJSON report per skill,
+   * and exit non-zero when any fails (#2248).
+   */
+  verify?: boolean;
+  /**
+   * Opaque pagination cursor. Used by `resources/directory/read`, whose result
+   * pages exactly as `resources/list` does — and where the caller descends the
+   * tree itself, so there is no store to walk it.
+   */
+  cursor?: string;
   /** roots/set payload (JSON array of {uri, name?}). */
   rootsJson?: string;
   /** prompts/complete: argument name / value / ref. */
@@ -53,7 +65,18 @@ export type McpResponse = Record<string, unknown>;
 export type MethodOutcome =
   | { kind: "result"; result: McpResponse; appInfo?: CliAppInfo }
   /** One JSON object per line (e.g. tools/list --app-info). Caller writes stdout. */
-  | { kind: "ndjson"; lines: unknown[] }
+  | {
+      kind: "ndjson";
+      lines: unknown[];
+      /**
+       * A line for **stderr**, written after the NDJSON. `--verify` uses it for
+       * its one-line summary, so a reader who piped stdout into `jq` still sees
+       * the verdict; `--app-info` sets nothing and behaves as before.
+       */
+      summary?: string;
+      /** Non-zero when the emitted report is itself a failure (`--verify`). */
+      exitCode?: number;
+    }
   | {
       kind: "stream";
       /** Human label for errors. */
@@ -76,6 +99,7 @@ export const SESSION_RPC_METHODS = [
   "resources/list",
   "resources/read",
   "resources/templates/list",
+  "resources/directory/read",
   "resources/subscribe",
   "resources/unsubscribe",
   "prompts/list",
@@ -89,6 +113,8 @@ export const SESSION_RPC_METHODS = [
   "tasks/result",
   "roots/list",
   "roots/set",
+  "skills/list",
+  "skills/get",
 ] as const;
 
 export type SessionRpcMethod = (typeof SESSION_RPC_METHODS)[number];
@@ -109,6 +135,12 @@ export const ONE_SHOT_METHODS = [
   "prompts/list",
   "prompts/get",
   "logging/setLevel",
+  // SEP-2640. All three are ordinary one-shot request/response calls — no
+  // stream, no long-lived subscription — so they belong here alongside the
+  // other list verbs rather than being reachable only from the session CLI.
+  "skills/list",
+  "skills/get",
+  "resources/directory/read",
 ] as const;
 
 export type OneShotMethod = (typeof ONE_SHOT_METHODS)[number];

clients/cli/src/handlers/run-method.ts

@@ -6,10 +6,17 @@ import {
   ManagedResourceTemplatesState,
   ManagedPromptsState,
   ManagedRequestorTasksState,
+  ManagedSkillsState,
   MessageLogState,
 } from "@inspector/core/mcp/state/index.js";
+import { SKILLS_EXTENSION_KEY } from "@inspector/core/mcp/skillsSchemas.js";
 import { CliExitCodeError, EXIT_CODES } from "../error-handler.js";
 import { collectAppInfo } from "./collect-app-info.js";
+import { summarizeSkillVerification } from "./skills-verify.js";
+import {
+  allSkillsVerified,
+  verifySkills,
+} from "@inspector/core/mcp/skillsVerification.js";
 import type {
   CliAppInfo,
   McpResponse,
@@ -35,6 +42,7 @@ export async function runMethod(
     null;
   let managedPromptsState: ManagedPromptsState | null = null;
   let managedTasksState: ManagedRequestorTasksState | null = null;
+  let managedSkillsState: ManagedSkillsState | null = null;
 
   try {
     let result: McpResponse;
@@ -283,6 +291,81 @@ export async function runMethod(
       result = (await inspectorClient.getRequestorTaskResult(
         args.taskId,
       )) as McpResponse;
+    } else if (args.method === "skills/list") {
+      // The store's cursor walk is reused rather than re-implemented — it
+      // carries the repeated-cursor and page-cap guards, and a second copy of
+      // a pagination walk is how the two come to disagree. What the CLI adds
+      // is the check below: the store answers "no extension" with an empty
+      // list, which is right for a UI that must render *something*, and wrong
+      // for a CLI where "this server has no skills" and "this server does not
+      // serve skills at all" are different answers a script has to tell apart.
+      if (!inspectorClient.getSkillsExtension()) {
+        throw new CliExitCodeError(
+          EXIT_CODES.USAGE,
+          `Server does not declare the ${SKILLS_EXTENSION_KEY} extension, so ${args.method} is not available.`,
+          { code: "skills_unsupported" },
+        );
+      }
+      managedSkillsState = new ManagedSkillsState(inspectorClient);
+      const skills = await managedSkillsState.refresh(args.metadata);
+      if (args.verify) {
+        const reports = await verifySkills(
+          inspectorClient,
+          skills,
+          args.metadata,
+        );
+        return {
+          kind: "ndjson",
+          lines: reports,
+          summary: summarizeSkillVerification(reports),
+          ...(allSkillsVerified(reports)
+            ? {}
+            : { exitCode: EXIT_CODES.SKILL_NONCONFORMANT }),
+        };
+      }
+      result = { skills };
+    } else if (args.method === "skills/get") {
+      if (!args.uri) {
+        throw new Error(
+          "URI is required for skills/get method. Use --uri to specify the skill URI.",
+        );
+      }
+      const skill = await inspectorClient.getSkill(args.uri, args.metadata);
+      if (args.verify) {
+        const reports = await verifySkills(
+          inspectorClient,
+          [skill],
+          args.metadata,
+        );
+        return {
+          kind: "ndjson",
+          lines: reports,
+          summary: summarizeSkillVerification(reports),
+          ...(allSkillsVerified(reports)
+            ? {}
+            : { exitCode: EXIT_CODES.SKILL_NONCONFORMANT }),
+        };
+      }
+      // The `{ skill }` envelope is restored here because it is what the wire
+      // carries: `GetSkillResultSchema` unwraps it for callers that want the
+      // entry, and a CLI whose contract is "print the result" must not quietly
+      // reshape one.
+      result = { skill };
+    } else if (args.method === "resources/directory/read") {
+      if (!args.uri) {
+        throw new Error(
+          "URI is required for resources/directory/read. Use --uri to specify the directory URI.",
+        );
+      }
+      // One page, not a walk. SEP-2640 says the listing is not recursive and
+      // clients descend by calling again on a child, so aggregating pages here
+      // would present a subtree as a directory — and the cursor is exposed as
+      // `--cursor` precisely so a script can do the descending.
+      result = await inspectorClient.readResourceDirectory(
+        args.uri,
+        args.cursor,
+        args.metadata,
+      );
     } else if (args.method === "roots/list") {
       result = { roots: inspectorClient.getRoots() };
     } else if (args.method === "roots/set") {
@@ -318,6 +401,7 @@ export async function runMethod(
     managedResourcesState?.destroy();
     managedResourceTemplatesState?.destroy();
     managedPromptsState?.destroy();
+    managedSkillsState?.destroy();
     managedTasksState?.destroy();
   }
 }

clients/cli/src/handlers/skills-verify.ts

@@ -0,0 +1,36 @@
+/**
+ * `--verify`: the scriptable SEP-2640 conformance report (#2248).
+ *
+ * The Skills screen in the web client can verify a skill, but only by hand, one
+ * file at a time, in a browser. A server author wants the same verdict in CI,
+ * over the whole catalog, with an exit code — which is exactly the argument
+ * `--strict` makes for the tool-schema lint, so this follows that handler's
+ * shape rather than inventing a second one.
+ *
+ * The walk itself is `core/mcp/skillsVerification.ts`, shared with the TUI's
+ * Skills pane. What is left here is presentation: the one-line stderr summary,
+ * which is a CLI concern and nothing else's.
+ */
+
+import type { SkillVerifyReport } from "@inspector/core/mcp/skillsVerification.js";
+
+/**
+ * A one-line human summary for stderr, so a reader who piped stdout to `jq`
+ * still learns the verdict.
+ */
+export function summarizeSkillVerification(
+  reports: readonly SkillVerifyReport[],
+): string {
+  const failed = reports.filter((report) => !report.ok).length;
+  const files = reports.reduce((sum, report) => sum + report.files.length, 0);
+  const mismatched = reports.reduce(
+    (sum, report) =>
+      sum + report.files.filter((file) => file.status === "mismatch").length,
+    0,
+  );
+  const skillWord = reports.length === 1 ? "skill" : "skills";
+  const fileWord = files === 1 ? "file" : "files";
+  return failed === 0
+    ? `Verified ${reports.length} ${skillWord} and ${files} ${fileWord}: no conformance errors.`
+    : `${failed} of ${reports.length} ${skillWord} failed verification (${mismatched} digest/size mismatch across ${files} ${fileWord}).`;
+}