Skip to content

2026 11 12 plugin agents design

Dr K edited this page Nov 14, 2026 · 3 revisions

One plugin/ folder, and the agents extension: agents/list and agents/get

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 _meta shape (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.

Brief

#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/agents extension.

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.

Research that shaped it

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}, in server/discover and in a legacy initialize. No notifications/agents/list_changed. Both methods answer any caller, whether or not it declared the extension.

  • agents/list. Its only parameter is an optional cursor. Any cursor fails with -32602 Invalid 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}. agent is the name. instructions is the Markdown body, omitted when blank. An unknown agent fails with -32602 Agent 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 is opus, sonnet or haiku, whether model is 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 what skill_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.
    • name and description must be non-empty strings.
    • name has 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>/** in image.yml's paths filter, as an exact string.
  • test_a_data_directory_is_packaged_beside_the_module_that_reads_it maps 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 with fnmatch. In fnmatch, * 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 *.md or 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.

Rulings

  1. Split (Dr K, 2026-11-12, #115). The folder move and the extension come first. The explorer is a sibling issue, built after #114.

  2. One _meta shape, not tied to a server (Dr K, 2026-11-12, #115). "io.kubed/agent": {"frontmatter": …, "skills": {…}}, named for the shape:

    • frontmatter is exactly as written;
    • skills maps each skill to its SKILL.md URI 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/agent beside io.kubed.mcp-kb/agent, in a later change of its own;
    • claude-control's kb-agents mod reads the one shape from either server and learns a second url.
  3. plugin/prompts/, not commands/ (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.json does not declare commands. Nothing harvests this plugin. If something ever does, the format question comes up then.

  4. The wheel test proves the dot-folder ships (Dr K, 2026-11-12, #115).

  5. 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-agents reaches 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 answers agents/*, that is a change in kubed-io/selenium. Nothing is built for it here.

  6. 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.json has no version.
  7. 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.

  8. The draft's later calls are accepted (Dr K, 2026-11-12, #119):

    • one plugin mapping and one plugin/** 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.yml edit on the branch himself once the PR is open.

  9. The README sentence waits for the explorer (Dr K, 2026-11-13, #119). This PR says nothing in the README about discovering agents.

Checked against the code

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 glob and 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}. AdvertiseAgents copies the same value into a legacy initialize.
  • agents/get carries no capabilities. The draft's Design said "every entry field except name and description", which would have put capabilities in it. Research and the issue both give the result as {agent, instructions, modelRoutingHint, tools: [], _meta}. This spec follows that list: capabilities is 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_data asks the same question less well, and the new test covers every file under plugin/, prompts included.
  • The shared frontmatter parse is a module of its own, mcp/frontmatter.py (call). The draft said to share it either way. If agents.py imported it from skill_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: AdvertiseSkills goes when skill_extension.py does, and AdvertiseAgents stays. 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.toml that explain the skills/ and prompts/ mappings (:148-152, :160-162, :166-171) become one comment on the plugin mapping.

Goal

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.

Non-goals

  • 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 tools in agents/get. It is always [], as in kb. The frontmatter's tools reaches a host through _meta.
  • A README sentence on agents (Ruling 9).

The design

The folder

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.skills and …mcp.prompts, both in packages and in package-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 ships plugin.json (see Research).
  • The skill's URI does not move. SkillProvider names the skill after its own folder, selenium-flow, so it stays skill://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 is plugin/skills/selenium-flow.
    • mcp/prompts.py: the prompts are plugin/prompts.
    • mcp/agents.py: the agents are plugin/agents.
    • Each module keeps its own lookup, with PLUGIN_DIR = "plugin" beside its own folder name.
  • plugin.json carries name: selenium-flow and a one-line description. It declares nothing else: the default folder names already say where things are, and prompts/ is not a folder a Claude plugin reads (Ruling 3). No server reads this file. It exists so that something could.

The extension

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 and agents/list is empty. Git keeps no empty folder, so until the explorer lands the folder is missing.

  • load(base=None, skills=()). It reads every *.md directly 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, description with whitespace collapsed, and capabilities, 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, from model as in Research, absent when it does not apply; tools: []; and _meta, {"io.kubed/agent": {"frontmatter": <as parsed>, "skills": {…}}}.
  • skills. The frontmatter's skills is a list of skill names. Each name in load's skills maps to skill://<name>/SKILL.md. Today that is only selenium-flow, and only when the skill is served. Any other name is left out, and the value is {} when none resolve. A skills that 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/agent key (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 with skill_extension.py (see Checked against the code): the header parse that _frontmatter does 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) declares settings() == {"listChanged": False} and binds two methods:

    • agents/list (PaginatedRequestParams) returns the cards;
    • agents/get (GetAgentParams, a RequestParams with a required, non-empty name) returns the detail.

    Each result is a deep copy, as in SkillsExtension.

  • AdvertiseAgents(Middleware): on_initialize adds {EXTENSION_ID: {"listChanged": False}} and keeps any extensions already there, so it and AdvertiseSkills survive 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/list returns agents: [], and agents/get returns Agent not found for every name.

Wiring

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.

Authentication

Nothing new. The methods arrive on /mcp like any request, behind the same token or JWT check (Ruling 5).

Testing

tests/test_agents_extension.py

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.

  1. Declared in both modes, auto and legacy, with {"listChanged": false}. The Skills extension is still declared beside it.

  2. The listing. The cards are in name order, with the result's three fields. description has its whitespace collapsed, and capabilities defaults to [].

  3. agents/get returns agent, instructions, modelRoutingHint, tools == [] and _meta["io.kubed/agent"], and no capabilities. frontmatter equals the file's header.

  4. The routing hint.

    • opus, claude-opus-4-1, sonnet and haiku map as in Research.
    • inherit, gpt-5, a missing model and a non-string model give no key.
  5. The skills map.

    • skills: [selenium-flow, nope] gives {"selenium-flow": "skill://selenium-flow/SKILL.md"}.
    • That URI is one resources/read serves.
    • skills: selenium-flow, a bare string, gives {}.
  6. Refusals.

    • An unknown name is INVALID_PARAMS Agent not found, with data.reason == "agent_not_found".
    • A missing or empty name is INVALID_PARAMS.
    • A cursor is INVALID_PARAMS Invalid agents cursor.
  7. A blank body has no instructions key.

  8. 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 .md file in a subfolder and a file that is not .md are not read.

  9. Gates.

    • mcp={"skill": False}: no declaration, and agents/list is Method not found.
    • No plugin/agents/ folder, which is the shipped state until the explorer lands: still declared, agents/list returns agents: [] with the result's three fields, and agents/get returns Agent not found.
    • On a server with no Skills extension, the agents declaration stands alone.
  10. Isolation. Mutating a returned result does not change the next one.

Moved paths

  • tests/test_packaging.py, DATA_DIRS: skill.py, prompts.py and agents.py all map to "plugin".
  • tests/test_skill.py and tests/test_prompts.py lose their package-data tests (see Checked against the code).

The wheel (Ruling 4)

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.

.github/: Dr K's edits

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/** and prompts/** become one line, plugin/**.
  • workflows/package.yml:10 and :162: the comments that name skills/ become plugin/.
  • copilot-instructions.md:16: skills/selenium-flow/ becomes plugin/skills/selenium-flow/.
  • copilot-instructions.md:120: "skills/, prompts/ and js/" becomes "plugin/ and js/".

Documentation

  • AGENTS.md.
    • The embedded skill: the paths become plugin/skills/selenium-flow/ and the mapping is plugin/. 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/agent is 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).
  • 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 maps plugin/".
  • 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.

Outside this repo

  • 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 answers agents/* one day, the change is there (Ruling 5).
  • mcp-kb: add io.kubed/agent beside io.kubed.mcp-kb/agent (Ruling 2).
  • claude-control kb-agents: read io.kubed/agent and learn selenium-flow's in-cluster url as a second server (Ruling 2).

Live check after deploy

Run in-cluster, from the pod, because the gateway refuses the methods (Ruling 5):

  • a legacy initialize carries io.modelcontextprotocol/agents with {"listChanged": false}, beside the Skills extension;
  • agents/list returns agents: [], with resultType, ttlMs and cacheScope;
  • agents/get for any name returns Agent not found;
  • skill://selenium-flow/SKILL.md, the prompts and skills/list answer exactly as before the move.

The explorer's issue repeats the check with its agent in the list.

Next round

  • 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.

Clone this wiki locally