Capability authoring guide and add-fred-capability Skill (thin v1)

[florian-muller]

Parent

#1961 — Agent Capability RFC (CAPAB-01, RFC §14)

What to build

The deliberately-thin v1 of the authoring surface, shipped once the pilot exists so the pilot doubles as the reference example from day one.

• docs/swift/capabilities/AUTHORING.md (~1 page): the mental model (capability = manifest + middleware), the four typed models and when each applies, the three authoring lanes (MCP server → zero Fred code; full-vertical package; first-party), and a pointer to the Port document-access toolkit additions (tree + summarize tools, rename) from Kea to Swift #1906 document-access capability as the canonical in-tree worked example. Hard rule: link, don't duplicate — the SDK definitions are the spec, the doc is the map. Tier-tag anything not yet landed.
• An add-fred-capability Skill — the model-facing artifact: which lane fits a request, which middleware hook maps to which runtime need (RFC §5.1 table), the registration line(s) per side, and the hard should-nots (never hand-edit the union/registry hotspots, never put capability code in control-plane, never persist asset blobs in tuning_json, keep runtime info out of LLM-exposed tool signatures).

Acceptance criteria

• AUTHORING.md merged, ~1 page, linking to live SDK types and the pilot capability rather than restating them
• add-fred-capability Skill available and pointing at the live reference capability
• Both artifacts tier-tagged; doc-update checklist gains the "authoring surface changed" row

Blocked by

• Port document-access toolkit additions (tree + summarize tools, rename) from Kea to Swift #1906 — the pilot is the worked example

[dimitri-tombroff]

Closing as delivered. docs/swift/capabilities/AUTHORING.md and the .claude/skills/add-fred-capability skill are present and point to the live capability implementation.