[benbrandt]

Implements the Agent Skills RFD (#2818) in the v2 schema, behind a new unstable_agent_skills feature. v1 and the stable v2 schema are unchanged.

What it adds

A skill entry in availableCommands:

{
  "type": "skill",
  "name": "pdf-processing",
  "description": "Extract text and tables from PDF files",
  "path": "/home/alice/.agents/skills/pdf-processing/SKILL.md"
}

A skill content block that invokes it:

{ "type": "skill", "name": "pdf-processing" }

Two capabilities:

• Client: session.commands.skill. Agents must not send skill entries without it.
• Agent: session.prompt.skill for one block at the start of a prompt, and session.prompt.skill.inline for any number of blocks at any position.

Changes

• AvailableCommand::Skill(Skill) with name, description, path and _meta. An invalid path or _meta is treated as absent. An entry missing name or description is skipped in a command list and is never kept as an unknown type.
• ContentBlock::Skill(SkillReference) with a required name. It is strict, because the Agent acts on it.
• CommandsCapabilities and CommandsSkillCapabilities under the Client's session capability group. That group now compiles under either this feature or unstable_prompt_suggestions.
• PromptSkillCapabilities and PromptSkillInlineCapabilities under PromptCapabilities.
• skill is a known discriminator for both unions when the feature is on, in the deserializers and in the generated fallback schemas.
• Draft v2 docs: a Skills section on the slash commands page, a skill reference section on the content page, both capabilities on the initialization page, and a row in the extensibility negotiation table.

Change to the RFD

The merged RFD gave skill entries the optional input hint that command entries have. This PR removes it. The Agent Skills specification defines no arguments for a skill, and only Claude Code adds them as its own extension. The RFD has a new FAQ entry for this and a revision history entry. It also drops three sentences that suggested _meta as a place for fields the RFD leaves out.

Things to check in review

• Type names. Skill follows Command, and SkillReference follows ResourceLink. The capability types follow the PromptImageCapabilities pattern.
• Position rules are prose only. "One block, first in the prompt" without inline is in the docs and doc comments. The schema can't express it, so the Agent enforces it.
• Prompt suggestions can't carry skill blocks. The Client's session.promptSuggestions capability has no skill field, so the existing rule excludes them. That can be a follow-up.

Compatibility

A receiver built without the feature parses a skill entry or block as the unknown-type fallback and round-trips it unchanged. tests/experimental_compatibility.rs covers both.

Testing

npm run check passes. New tests cover the wire format of the entry and the block, lenient and strict fields, malformed entries in a command list, both capabilities at each level, and the fallback schemas with the feature on and off.

I compiled these feature combinations by hand, with and without schemars: the feature with v2, with v2 and prompt suggestions, and without v2. I did not run the full cargo hack powerset locally. The docs site is not rendered locally, so the new anchors are unverified.