Repository navigation
2026 11 12 plugin agents design
History. Shipped in #126. What it asked for now lives in the living spec: plugin. The folder and its packaging (Rulings 3, 4 and 8, the one mapping) are PLG-2 to PLG-7; the extension, its gate and its declaration (Rulings 6 and 7) are PLG-30 and PLG-31; loading, names and the duplicate rule (Ruling 8) are PLG-33 to PLG-35; the
_metashape (Ruling 2) is PLG-40; the route (Ruling 5) is the cluster's and has no requirement. Ruling 9, the README sentence, is not a requirement. Overtaken:
plugin/agents/exists: the explorer shipped, so the empty-list case is only what an empty folder gives (PLG-30).- The status banner and the Next round section describe the pull request, not the code.
Status: SPEC OF RECORD, 2026-11-13, pull request #126 (issue #119, parent
#115). Dr K approved the draft on #119 on 2026-11-13. This is that draft,
finished by the pull request's agent after checking it against the code. The
Rulings are Dr K's. Anything marked (call) is an agent's: the spec agent's
calls were accepted in Rulings 6 and 8, and the ones this round added are listed
under Checked against the code. The plan is
plans/2026-11-12-plugin-agents.md.
#115, by Claude for Dr K: selenium-flow ships its own skill and prompts and serves
them itself, so a client needs nothing but this server. It has no agents. A main
agent that wants a website explored either drives the browser itself, filling
its context with every page, or writes a subagent by hand that knows nothing
of flows. What it ships also sits in two unrelated top-level folders, skills/
and prompts/, rather than as one plugin.
#115 was split in two (Dr K, 2026-11-12). This spec is the groundwork:
- the folder move;
- the
io.modelcontextprotocol/agentsextension.
The first agent, the explorer, is its own sub-issue and builds after #114's URL
hints land. Until then plugin/agents/ does not exist, so the extension is
declared with an empty agents/list (Ruling 7) and is tested against agents
written by the tests.
The wire shape is mcp-kb's draft. mcp-kb implements the agents extension in
its docs/superpowers/specs/agents.md: agents-wg proposal 0000 at 137d88b,
targeting MCP 2026-07-28, experimental. There is no shared library. As in
skill_extension.py, this is a small ServerExtension of our own. In the
draft, the server serves definitions and the host builds and runs the agents.
-
Declaration.
{"listChanged": false}, inserver/discoverand in a legacyinitialize. Nonotifications/agents/list_changed. Both methods answer any caller, whether or not it declared the extension. -
agents/list. Its only parameter is an optionalcursor. Any cursor fails with-32602Invalid agents cursor. The result is one card per agent, in name order, of the form{name, description, capabilities}. -
agents/get {name}. It returns{agent, instructions, modelRoutingHint, tools: [], _meta}.agentis the name.instructionsis the Markdown body, omitted when blank. An unknown agent fails with-32602Agent not found,data: {"reason": "agent_not_found"}. -
model→modelRoutingHint. Lowercase the value and split it into words at every run of characters that are not letters or digits. The family is the first word that isopus,sonnetorhaiku, whethermodelis an alias or a full id:-
opus→{"role": "large", "vision": false} -
sonnet→{"role": "medium", "vision": false} -
haiku→{"role": "small", "vision": false}
The hint is omitted for
inherit, for a missing or non-string value, and for a value naming none of the three. -
-
Results.
resultType: "complete",ttlMs: 0,cacheScope: "private", which is whatskill_extension._result()already returns. -
The file. YAML frontmatter, then a Markdown body.
- The frontmatter must be a non-empty mapping with string keys, and must survive conversion to JSON.
-
nameanddescriptionmust be non-empty strings. -
namehas no whitespace, control or invisible characters,/or@. - A file that fails is skipped and never fails the boot.
FastMCP's legacy handshake drops extensions. add_extension declares one in
server/discover only, with the value its settings() method returns ({} by
default). That is why AdvertiseSkills exists (skills-extension spec,
2026-10-05), and agents need the same.
The gateway refuses the methods. agentgateway 1.6 answers skills/list
with unsupported method (agentgateway#3579), and the kb-agents mod's README
says the same of agents/*. In-cluster, the server answers them.
The wheel and the image are guarded by tests that compare strings.
-
tests/test_packaging.py,test_everything_in_the_wheel_rebuilds_the_image, requires<package-dir value>/**inimage.yml's paths filter, as an exact string. -
test_a_data_directory_is_packaged_beside_the_module_that_reads_itmaps each module to the directory beside it (DATA_DIRS). -
tests/test_skill.py,test_every_skill_file_is_covered_by_package_data, checks files against the patterns withfnmatch. Infnmatch,*matches a leading dot, so that test cannot see a dot-folder that setuptools leaves out.tests/test_prompts.py,test_every_prompt_file_is_covered_by_package_data, only asks whether some pattern ends in*.mdor is*.
No test builds a wheel. package.yml installs the built wheel and imports it,
and that is all.
Setuptools skips dot-folders: settled. The draft left this unverified.
setuptools/command/build_py.py expands package-data with the stdlib's
from glob import glob, as glob(pattern, recursive=True) joined onto the
mapped root, and passes no include_hidden. The stdlib's * and ** match no
name that starts with a dot, so **/* misses .claude-plugin/plugin.json, and
only a pattern that spells the dot, .claude-plugin/*, matches it. A file can
still reach the wheel another way: with include_package_data (on by default
for a pyproject.toml build), the files setuptools_scm finds in git are added as
well. That is exactly why a built wheel cannot prove the pattern is right, and
why the test models the pattern expansion instead.
-
Split (Dr K, 2026-11-12, #115). The folder move and the extension come first. The explorer is a sibling issue, built after #114.
-
One
_metashape, not tied to a server (Dr K, 2026-11-12, #115)."io.kubed/agent": {"frontmatter": …, "skills": {…}}, named for the shape:-
frontmatteris exactly as written; -
skillsmaps each skill to itsSKILL.mdURI on the server that answered.
A server-specific extra goes under the server's own key (
io.kubed.selenium-flow/agent), and only if something needs it.Neither of the following is part of this issue:
- mcp-kb adds
io.kubed/agentbesideio.kubed.mcp-kb/agent, in a later change of its own; - claude-control's
kb-agentsmod reads the one shape from either server and learns a secondurl.
-
-
plugin/prompts/, notcommands/(Dr K, 2026-11-12, #115). The files are in the skills-mcp format (arguments:,{{ }}), which gives MCP prompts their typed arguments. They are not Claude commands.plugin.jsondoes not declarecommands. Nothing harvests this plugin. If something ever does, the format question comes up then. -
The wheel test proves the dot-folder ships (Dr K, 2026-11-12, #115).
-
The route is the cluster's (Dr K, 2026-11-12, #119). This spec only states what the server answers. In-cluster clients call the Service directly, the way
kb-agentsreaches kb. They use the same OIDC token the server already verifies, passed through by the gateway, so nothing about authentication changes. The gateway stays the route for tools and resources. If agentgateway ever answersagents/*, that is a change in kubed-io/selenium. Nothing is built for it here. -
The three calls are accepted (Dr K, 2026-11-12, #119):
- names have no prefix;
- the agents are gated on the skill's setting;
-
plugin.jsonhas noversion.
-
Declared from now on, with an empty
agents/list(Dr K, 2026-11-12, #119). A hidden extension cannot be checked live until the explorer lands. Declaring it now gives a client one consistent capability across both PRs. This PR gets a CHANGELOG line, and the explorer's issue adds its agent. -
The draft's later calls are accepted (Dr K, 2026-11-12, #119):
- one
pluginmapping and oneplugin/**trigger; - the wheel test expands the patterns the way setuptools does, or reads the built wheel;
- the code is in
mcp/agents.py; - on a duplicate name, the first wins;
- no server-specific key yet.
Dr K puts the
image.ymledit on the branch himself once the PR is open. - one
-
The README sentence waits for the explorer (Dr K, 2026-11-13, #119). This PR says nothing in the README about discovering agents.
What the draft said that the code changed, 2026-11-13:
-
The dot-folder question is settled (see Research). The test models
setuptools' expansion with the stdlib
globand reads no wheel. A wheel is built once by hand, as a check, and is not a test. -
The extension's value comes from
ServerExtension.settings(), which returns{"listChanged": False}.AdvertiseAgentscopies the same value into a legacyinitialize. -
agents/getcarries nocapabilities. The draft's Design said "every entry field except name and description", which would have putcapabilitiesin it. Research and the issue both give the result as{agent, instructions, modelRoutingHint, tools: [], _meta}. This spec follows that list:capabilitiesis on the card only. -
The README names neither folder, so the move changes nothing in it.
Its only nearby line, on
skills/list, is a method name, not a path. -
Both package-data tests go, not only the skill's (call).
test_every_prompt_file_is_covered_by_package_dataasks the same question less well, and the new test covers every file underplugin/, prompts included. -
The shared frontmatter parse is a module of its own,
mcp/frontmatter.py(call). The draft said to share it either way. Ifagents.pyimported it fromskill_extension.py, then deleting that module once FastMCP ships its own (#5016) would break the agents. So both import the new module. -
Two middlewares, not one (call), for the same reason:
AdvertiseSkillsgoes whenskill_extension.pydoes, andAdvertiseAgentsstays. Each one adds its own key and keeps the keys already there. -
The skills a file can resolve are the served skill's own name, read from
self.skill.skill_info.name, not a constant. -
The comments in
pyproject.tomlthat explain theskills/andprompts/mappings (:148-152,:160-162,:166-171) become one comment on thepluginmapping.
The repository ships one plugin folder. A client that speaks the agents extension can list this server's agents and fetch one, with its instructions, a routing hint, and the skills it relies on as URIs on this server.
- Any agent. The explorer is the sibling issue.
- The gateway or any route (Ruling 5). The same goes for mcp-kb and claude-control (Ruling 2). These are listed under Outside this repo.
- Changing a skill URI, a prompt, the Skills extension,
_manifest, or the mirror tools. A client that ignores the agents extension sees no difference. - Pagination,
listChanged, or reloading agents at runtime. They are package data, built once with the server, as the skill entry is. - Claude command format for the prompts (Ruling 3).
- Serving
toolsinagents/get. It is always[], as in kb. The frontmatter'stoolsreaches a host through_meta. - A README sentence on agents (Ruling 9).
plugin/
.claude-plugin/plugin.json # {"name": "selenium-flow", "description": "…"}; no version
skills/selenium-flow/ # today's skills/selenium-flow, moved unchanged
prompts/ # today's prompts/, moved unchanged
agents/ # created by the explorer's issue, not this one
-
One mapping (call, Ruling 8):
"kubed.selenium_flow.mcp.plugin" = "plugin"in[tool.setuptools.package-dir]. It replaces…mcp.skillsand…mcp.prompts, both inpackagesand inpackage-dir. With one mapping, the image trigger is one string,plugin/**, and the packaging tests keep their shape. -
Package-data for
kubed.selenium_flow.mcp.plugin:"*","**/*", and".claude-plugin/*". The third is what shipsplugin.json(see Research). -
The skill's URI does not move.
SkillProvidernames the skill after its own folder,selenium-flow, so it staysskill://selenium-flow/…. -
The modules find it the same way they do today. First the packaged
location,
Path(__file__).parent / "plugin" / …; then the source tree,parents[3] / "plugin" / ….-
mcp/skill.py: the skill isplugin/skills/selenium-flow. -
mcp/prompts.py: the prompts areplugin/prompts. -
mcp/agents.py: the agents areplugin/agents. - Each module keeps its own lookup, with
PLUGIN_DIR = "plugin"beside its own folder name.
-
-
plugin.jsoncarriesname: selenium-flowand a one-linedescription. It declares nothing else: the default folder names already say where things are, andprompts/is not a folder a Claude plugin reads (Ruling 3). No server reads this file. It exists so that something could.
This is a new module, kubed/selenium_flow/mcp/agents.py (call), beside
skill_extension.py. It holds both the loading and the extension, because no
FastMCP provider serves agents.
-
EXTENSION_ID = "io.modelcontextprotocol/agents". -
agents_path():plugin/agents, packaged first, then the source tree. If the folder is missing, there are no agents andagents/listis empty. Git keeps no empty folder, so until the explorer lands the folder is missing. -
load(base=None, skills=()). It reads every*.mddirectly in the folder, not in subfolders (call), sorted by file name, and builds one agent per conforming file. A file that does not conform, or cannot be read as UTF-8, is logged with the reason and skipped. Each agent holds:- its card for
agents/list:name,descriptionwith whitespace collapsed, andcapabilities, the frontmatter list if it is a list of strings, else[]; - its detail for
agents/get:agent(the name);instructions, the body stripped, absent when blank;modelRoutingHint, frommodelas in Research, absent when it does not apply;tools: []; and_meta,{"io.kubed/agent": {"frontmatter": <as parsed>, "skills": {…}}}.
- its card for
-
skills. The frontmatter'sskillsis a list of skill names. Each name inload'sskillsmaps toskill://<name>/SKILL.md. Today that is onlyselenium-flow, and only when the skill is served. Any other name is left out, and the value is{}when none resolve. Askillsthat is not a list of strings counts as none. A bare string is not read as a list of its letters. -
No
io.kubed.selenium-flow/agentkey (call, Ruling 8). Nothing needs the file's path yet (Ruling 2 says only if needed). -
Two files with one name. The first, in file-name order, is kept; the second is logged and skipped (call, Ruling 8). One plugin has nothing to rename with, unlike kb's
@<plugin>. -
Frontmatter parsing is
mcp/frontmatter.py, shared withskill_extension.py(see Checked against the code): the header parse that_frontmatterdoes today, which also returns the body now, and the JSON round-trip check from_problem. The name rules (non-empty, no whitespace, control or invisible characters,/,@) are the agents' own. A skill's name has to equal its folder name instead. -
AgentsExtension(ServerExtension)declaressettings() == {"listChanged": False}and binds two methods:-
agents/list(PaginatedRequestParams) returns the cards; -
agents/get(GetAgentParams, aRequestParamswith a required, non-emptyname) returns the detail.
Each result is a deep copy, as in
SkillsExtension. -
-
AdvertiseAgents(Middleware):on_initializeadds{EXTENSION_ID: {"listChanged": False}}and keeps any extensions already there, so it andAdvertiseSkillssurvive each other in either order. -
register(mcp, agents) -> None. It always adds the extension and the middleware, even with no agents (Ruling 7). An empty list is a valid answer:agents/listreturnsagents: [], andagents/getreturnsAgent not foundfor every name.
In server.py, beside skill.register (:303-304): when self.skill is not None, load the agents with the skill's name as the only one that resolves, and
register them (Ruling 6, the gate). With the skill served, the extension is
declared whatever the folder holds (Ruling 7), and whether or not the skill
itself conforms to the Skills extension. With mcp.skill off, there are no
agents and no declaration, and agents/list returns Method not found. The
same is true when the skill fails to load, because self.skill is then None.
config.py, mcp.skill's description: "Serve the agent skill: resources, the
Skills extension, and the agents that use it." docs/Configuration.md is then
regenerated with scripts/generate_wiki.py.
Nothing new. The methods arrive on /mcp like any request, behind the same
token or JWT check (Ruling 5).
Unit-marked and modelled on tests/test_skills_extension.py. It uses the
in-memory Client and client.session.send_request. The agents are written into
tmp_path by the test, and agents_path is pointed at them.
-
Declared in both modes,
autoandlegacy, with{"listChanged": false}. The Skills extension is still declared beside it. -
The listing. The cards are in name order, with the result's three fields.
descriptionhas its whitespace collapsed, andcapabilitiesdefaults to[]. -
agents/getreturnsagent,instructions,modelRoutingHint,tools == []and_meta["io.kubed/agent"], and nocapabilities.frontmatterequals the file's header. -
The routing hint.
-
opus,claude-opus-4-1,sonnetandhaikumap as in Research. -
inherit,gpt-5, a missing model and a non-string model give no key.
-
-
The skills map.
-
skills: [selenium-flow, nope]gives{"selenium-flow": "skill://selenium-flow/SKILL.md"}. - That URI is one
resources/readserves. -
skills: selenium-flow, a bare string, gives{}.
-
-
Refusals.
- An unknown name is
INVALID_PARAMSAgent not found, withdata.reason == "agent_not_found". - A missing or empty name is
INVALID_PARAMS. - A cursor is
INVALID_PARAMSInvalid agents cursor.
- An unknown name is
-
A blank body has no
instructionskey. -
Skipped, never fatal. The server boots and serves the rest when the folder also holds:
- no frontmatter;
- a non-mapping;
- a name with a space, a
/or an@, or a name that is not a string; - an empty description;
- a YAML-only value;
- a duplicate name;
- a file that is not UTF-8.
A
.mdfile in a subfolder and a file that is not.mdare not read. -
Gates.
-
mcp={"skill": False}: no declaration, andagents/listisMethod not found. - No
plugin/agents/folder, which is the shipped state until the explorer lands: still declared,agents/listreturnsagents: []with the result's three fields, andagents/getreturnsAgent not found. - On a server with no Skills extension, the agents declaration stands alone.
-
-
Isolation. Mutating a returned result does not change the next one.
-
tests/test_packaging.py,DATA_DIRS:skill.py,prompts.pyandagents.pyall map to"plugin". -
tests/test_skill.pyandtests/test_prompts.pylose their package-data tests (see Checked against the code).
This is a new test in tests/test_packaging.py. Every file under plugin/,
.claude-plugin/plugin.json included, must be matched by the package-data
patterns as setuptools expands them: the stdlib glob.glob(pattern, root_dir=plugin, recursive=True), files only. With .claude-plugin/* taken
out of the patterns, the same expansion must miss plugin.json, so that the
test is proved able to fail. A second test pins plugin.json: it is JSON, its
name is the skill's name, and it has no version and no commands.
The PR's own CI fails until these are on the branch, because
test_everything_in_the_wheel_rebuilds_the_image reads image.yml. Dr K
pushes them to the branch himself, between turns, once the PR is open
(Ruling 8). The PR's agent never edits .github/:
-
workflows/image.yml:49-50:skills/**andprompts/**become one line,plugin/**. -
workflows/package.yml:10and:162: the comments that nameskills/becomeplugin/. -
copilot-instructions.md:16:skills/selenium-flow/becomesplugin/skills/selenium-flow/. -
copilot-instructions.md:120: "skills/,prompts/andjs/" becomes "plugin/andjs/".
-
AGENTS.md.-
The embedded skill: the paths become
plugin/skills/selenium-flow/and the mapping isplugin/. The package-data sentence names the new test and says why.claude-plugin/*is spelt out. - A short paragraph on the agents extension covers:
- the module;
-
io.kubed/agentis the shared shape, and a server's own key holds only extras; - it is gated on the skill;
- it is declared even with no agents, answering an empty list;
- the gateway refuses it, and in-cluster clients call the Service (Ruling 5).
-
The embedded skill: the paths become
-
CONTRIBUTING.md:63(the table row) and:127: the new paths. -
README.md: no change (Ruling 9, and Checked against the code). -
kubed/selenium_flow/core/js.py:11: "the same way it mapsplugin/". -
CHANGELOG.md[Unreleased]. One line (Ruling 7): "selenium-flow declares the agents extension (agents/list,agents/get); no agents yet." The explorer's issue adds its own line for the agent.
-
kubed-io/selenium, the cluster repo. In-cluster clients reach
agents/*on the Service directly. The gateway stays the route for tools and resources. If agentgateway answersagents/*one day, the change is there (Ruling 5). -
mcp-kb: add
io.kubed/agentbesideio.kubed.mcp-kb/agent(Ruling 2). -
claude-control
kb-agents: readio.kubed/agentand learn selenium-flow's in-clusterurlas a second server (Ruling 2).
Run in-cluster, from the pod, because the gateway refuses the methods (Ruling 5):
- a legacy
initializecarriesio.modelcontextprotocol/agentswith{"listChanged": false}, beside the Skills extension; -
agents/listreturnsagents: [], withresultType,ttlMsandcacheScope; -
agents/getfor any name returnsAgent not found; -
skill://selenium-flow/SKILL.md, the prompts andskills/listanswer exactly as before the move.
The explorer's issue repeats the check with its agent in the list.
- The explorer (#115's sibling) adds
plugin/agents/explorer.md, its own changelog line and the README sentence. - When FastMCP or the agents-wg draft moves: re-read the draft and check that
the shape still matches mcp-kb's,
agents/get's fields first.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network