Set aside a workspace skill that will not load, instead of taking the list down with it

[mroops0111]

Closes #188

A SKILL.md the workspace owner wrote by hand could stop every skill and every run in that workspace, and say so only in the server log. FsSkillRegistry.readSkillFrontmatter threw and list() did not catch, so one bad file took out GET /skills and, through it, buildSessionDir for every run.

What changes

Rejection is scoped to the origin that can be fixed. A builtin or plugin skill that will not load still stops the boot, since nobody but its publisher can fix one. A workspace or extension file is set aside instead, and the rest of the list survives.

The reasons travel back. GET /workspaces/:id/skills now returns { items, unloadable }, and each item carries availability.

Studio names the file. The workspace details panel gains a Skill Files section listing what did not load with its path and reasons, and what cannot run here yet. It is absent entirely when there is nothing wrong.

Two new structure checks. A companion doc named by a relative path, which the agent's Read tool cannot resolve, so the file is never read. A pick input's default naming no option its static provider offers, which would preselect nothing and let a value the picker never listed reach $ARGUMENTS. Both meet the same bar as the checks already there: the file breaks at run time.

Heading case, dash choice, section order, and prompt length were all written and then removed. They are review matters, and a skill withheld over a capital letter costs its author more than the rule saves. Section order in particular was already settled the other way in the code.

A skill is checked at three moments, not two

Load reads the file alone, so its answer holds in every workspace. Availability reads it against one workspace, so the same file passes in one and fails in the next. Start reads it against the environment assembled for one run, the first moment the runner-injected variables exist at all.

readinessIssuesFor collapsed availability and start into one method, took the server's own environment as its env, and would have reported braid:ask as not-ready with six variables it never lacked. Each moment now has its own shape: SkillManifest.availabilityIssuesIn for availability, assertSkillCanStart for start, thrown rather than reported since a precondition for work about to begin has no reader to report to.

Two resource leaks this split turned up

assertSkillCanStart and the gateway preflight run after a run's token is issued, its output gate opened, and its agent credential leased. A failure there aborted start() before drain()'s finally ever ran, which was the only place any of those three, or the session directory buildSessionDir had already staged, got released. Both are now cleaned up on a preflight failure, the session directory only when this attempt built it fresh rather than reused one from a resumed run.

Separately, list() and listUnloadable() each triggered their own full scan(), so the skills-list route calling both walked the same directories twice per request. scan() now memoises its in-flight result per workspace, and its three independent root scans run together instead of one after another.

Structural commits

• The three checks took three different arguments and were spread inline, so a fourth meant editing the caller. They share one input now, with the body's fenced blocks stripped once, and hang off a list.
• SkillLoadIssue.kind reads as the fault then its subject, matching SkillAvailabilityIssue beside it. extension-target carried two faults under one name and is split.
• Splitting it turned up a latent bug: SkillId is any non-empty string, so an extension directory naming no skill at all parsed fine and was dropped in silence. splitSkillId defines that grammar and now checks it.
• The validator moves beside validateOutput under domain/skill. It owns no fs, git, or subprocess, and infrastructure is for the adapters that do.

Test fixtures

Several tests were quietly reinventing fixtures the repo already shares: a hand-rolled frontmatter() where makeSkillManifestData already does the job, a hardcoded copy of the required-section list where skillFixtures.ts already promises callers won't need one, and inline no-op AgentCredentialStore / SkillRegistry fakes where an inert fake and makeSingleSkillRegistry already exist. All four now go through the shared helper; skillFixtures.ts gained an omitSections option and test-utils gained inertAgentCredentialStore to make that possible. Also restores the category: generate + Output Files present passes case, dropped when SkillStructureValidator.test.ts was replaced and never carried over.

Review notes

• packages/server/src/infrastructure/skill/FsSkillRegistry.ts is the substance. scan() runs every origin in one pass and decides throw-or-set-aside by origin.
• packages/server/test/infrastructure/skill/shippedSkills.test.ts is new, and holds this repo's own six prompts to the contract rather than only the fixtures.
• The misleading precedence comment on list() is gone. It claimed builtin < plugin < workspace, later wins, but the namespace derives from the origin so a workspace skill is always workspace:<verb> and that branch never ran. The replacement comment says what actually holds: a plugin's own skillNamespace is unconstrained, so a collision there still resolves by insertion order, silently.
• extensionTargetId's first-hyphen convention (ddd-extract targets ddd:extract) predates this PR and carries the same limit it always had: a namespace containing a hyphen is not addressable this way. Documented rather than redesigned, since the fix needs a real decision about the directory grammar that is out of scope here.

Not fixed here

Route-level skills.test.ts was not extended to exercise the new unloadable / availability response shape end to end, and the three new zod schemas (SkillLoadIssue, UnloadableSkill, SkillAvailabilityIssue) have no dedicated schema-level test. Both are coverage gaps, not fixture duplication, and are left for a follow-up.

Checks

pnpm lint and pnpm typecheck clean. core 528, server 708, schema 337, studio 302 pass.

🤖 Generated with Claude Code