DESIGN, NOT BUILT. No registry, no API, nothing to call. Written down now
because the name and the boundary are the parts that get expensive later, and
because a plugin author who invents a different word for this is hard to merge
with afterwards.
An affordance is what the surface on the other end offers the agent — declared
by the code that implements it, read at runtime. Not what the agent can do;
what the client will honour.
The worked example is images. Officer's chat DOES render markdown images, but
an <img> carries no bearer token, so it can only load what the browser can
fetch unauthenticated. A fresh agent knows none of that: it writes
, nothing renders, and nothing says why. That knowledge
currently lives as prose in a hand-written CLAUDE.md on one machine, phrased as
a workaround ("use a public URL") rather than as the constraint — with nothing
keeping the two in sync.
Prose is the wrong container for three reasons: it drifts from the code, it is
per-machine, and a plugin cannot contribute to it. The last one is the point —
a plugin IS a new surface arriving at runtime, and no agent learns it exists.
The rule that makes it worth building: an affordance is declared where it is
implemented, like permissions/registry.ts. A list maintained elsewhere is the
CLAUDE.md problem again with a better name.
`capability` and `skill` were both already taken here, twice in skill's case.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5
7a9e576ee6