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>
This commit is contained in:
cliffhall 2026-09-07 18:10:37 -04:00
commit 9a8488681e

View file

@ -603,11 +603,15 @@ export interface ServerConfig {
* `skills/get` plus the `skill://` files those entries name. The fixture set
* deliberately includes non-conforming skills — see `skills.ts`.
*
* There is deliberately **no `directoryRead` option**. The flag would
* advertise `resources/directory/read`, which nothing here serves, so a
* config could produce exactly the false capability this fixture exists to
* help catch — Connection Info reporting "supported" for a method that
* answers `-32601`. It comes back in phase 3 (#2248) with the handler.
* Turning this on also declares **`directoryRead: true`** and serves
* `resources/directory/read` over the same `skill://` tree (#2248). The two
* are one switch rather than two on purpose: the sub-flag's whole hazard is
* advertising a method nothing answers — Connection Info reporting
* "Supported" for a call that returns `-32601` — and a config that cannot
* express the declaration without the handler cannot reach it. A fixture for
* the *undeclared* case is still available and is the more useful one:
* any config without `skills` at all, against which the Inspector must
* refuse to send the call locally.
*/
skills?: boolean;
/**
@ -878,13 +882,14 @@ export function createMcpServer(config: ServerConfig): McpServer {
};
}
// Skills extension (SEP-2640): a server-declared extension, advertised bare.
// See `ServerConfig.skills` for why there is no `directoryRead` sub-option
// to turn on.
// Skills extension (SEP-2640): a server-declared extension. `directoryRead`
// is declared because `wireSkillsHandlers` registers the handler for it in
// the same `config.skills` branch below — see `ServerConfig.skills` for why
// the declaration and the handler are one switch.
if (config.skills) {
capabilities.extensions = {
...(capabilities.extensions ?? {}),
[SKILLS_EXTENSION_KEY]: {},
[SKILLS_EXTENSION_KEY]: { directoryRead: true },
};
// Skill files are fetched through ordinary `resources/read`, so the
// resources capability has to be advertised even when the config registers