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

Plugin

The server ships its own guidance and serves it itself, so a client needs nothing but the server. That material lives in one folder, plugin/, laid out as a Claude Code plugin: a skill that teaches an agent to drive the browser, two prompts a person picks, and an agent that explores a site. This area covers the folder and how it ships, the three ways the server serves it (the skill as resources, the Skills extension, the Agents extension), the prompts, the explorer agent, and what the server's instructions say about all of it.

Use cases

  • An agent connects to a bare server, reads skill://selenium-flow/SKILL.md and drives the browser as the skill says, with nothing installed on the client.
  • A person picks repair_flow after a failed flow run names it in its hint.
  • A host that implements the Agents extension fetches the explorer and runs it as a subagent.
  • An operator switches the skill off and the server serves the tools alone.

Neighbours

PLG-1. How MCP tools, resources and prompts are listed and hidden is in surfaces.md and is not restated here. The mcp.skill setting is in config.md. flows_here is in saved-flows.md.

The plugin/ folder

PLG-2. plugin/ is at the repo root and holds:

Path What
.claude-plugin/plugin.json the Claude plugin manifest
skills/selenium-flow/ the skill: SKILL.md and references/*.md
prompts/*.md the prompts, one file each
agents/*.md the agent definitions, one file each

PLG-3. plugin.json holds a name (selenium-flow) and a one-sentence description, and nothing else: no version, no commands. The server does not read it. Claude Code does not offer the prompts as commands, because their folder is not one a Claude plugin reads.

PLG-4. The wheel installs the folder as the package kubed.selenium_flow.mcp.plugin: pyproject.toml maps that package to plugin/, and its package data matches *, **/* and .claude-plugin/*. The third pattern ships plugin.json, which the first two skip as a dot folder. A test holds that every file under plugin/ is matched.

PLG-5. The Dockerfile copies the repo and installs the project, so the folder is in the image. The image workflow's path filter lists plugin/**, so a change under it rebuilds the image.

PLG-6. skill.py, prompts.py and agents.py each find their folder the same way: beside the module (mcp/plugin/) when that directory exists, else plugin/ at the repo root of a checkout. The test is for plugin/ and not agents/, so a wheel with plugin/ and no agents/ has no agents and never falls back to a plugin/agents elsewhere.

PLG-7. A missing folder is not an error: no skill, no prompts or no agents is a valid state and the server starts. The folders are read once, when the server is built, so a file changed on disk is served as it was until the process restarts.

The embedded skill

PLG-8. The skill is plugin/skills/selenium-flow/. Its name is its folder's name, because SkillProvider takes the name from the folder. The frontmatter name equals it, and a test holds this.

PLG-9. The skill ships in the wheel, so it describes the version of the server that serves it. It teaches what the tool list does not: when to extract and when to screenshot, how to name a workspace, what a timeout on a good selector means, how to write a flow. SKILL.md holds the rules and an index; one reference page per topic holds the rest.

PLG-10. SKILL.md has a name of 1 to 64 lowercase letters, digits and hyphens, a description of 1 to 1024 characters that says when to use the skill, and a body under 500 lines. Every references/*.md file is linked from SKILL.md, and every link resolves.

PLG-11. The skill stays in step with the code through tests, each of which fails when they part:

  • SKILL.md has a table row for every tool the server lists (the two mirror tools excepted) and for every resource and template (ui:// and skill:// excepted);
  • every selector= and to= literal in the skill's pages, README.md and AGENTS.md is one that core.browser.locator accepts;
  • the control-notice phrases the skill quotes, two of them whole, are the sentences in live.control;
  • every page and anchor a failed run's hint can name is a shipped page and a heading in it.

The skill as resources

PLG-13. skill.load returns a SkillProvider over the skill folder, with each supporting file an individual resource. It returns nothing, and logs a warning, when SKILL.md is missing or the provider cannot be built; the server then starts without the skill.

PLG-14. The URIs are skill://selenium-flow/SKILL.md, one per file under the folder (skill://selenium-flow/references/FLOWS.md), and skill://selenium-flow/_manifest, the file list as FastMCP builds it. resources/list shows each file. FastMCP's client helpers (list_skills, get_skill_manifest) work against them. There is no _index.md and no library segment.

PLG-15. A .md file is served as text/markdown text with its frontmatter kept. It is read as text, so a \r\n file is served with \n.

PLG-16. mcp.skill off, or a skill that did not load, leaves the server with no skill resources, no Skills extension and no agents (PLG-30). Every later check of "is the skill served" reads that.

The Skills extension

PLG-17. The server declares io.modelcontextprotocol/skills with the value {} and binds skills/list and skills/get. They are JSON-RPC methods beside resources/list, not tools. FastMCP declares the extension on server/discover; a middleware adds it to initialize, which FastMCP leaves without it. The methods answer any caller.

PLG-18. The extension is offered only when the skill conforms: SKILL.md has a frontmatter that is a mapping and survives a trip through JSON, a name equal to the folder name, and a description of 1 to 1024 characters. A skill that does not conform stays available as resources, a warning names the reason, and the extension is not declared.

PLG-19. The one entry is built once, with the server. Its keys are uri (skill://selenium-flow/SKILL.md), frontmatter (the header exactly as parsed) and resources: every file of the skill, SKILL.md included, sorted by URI, each as uri, digest (sha256:<hex>) and size.

PLG-20. A resource's digest and size are those of the bytes resources/read returns, not the bytes on disk: a text/* file is read as text and re-encoded as UTF-8, any other file is read raw. The _manifest hashes the disk bytes, so the two can differ for a file whose newlines the read normalises.

PLG-21. skills/list returns {"resultType": "complete", "ttlMs": 0, "cacheScope": "private", "skills": [entry]}, and skills/get the same envelope with skill. skills/get takes a required, non-empty uri, which must be the entry's SKILL.md URI: any other, the _manifest URI included, fails with -32602 and Skill not found.

PLG-22. skills/list has one page. Any cursor fails with -32602 and Invalid skills cursor. Each result is a deep copy of the entry, so one caller's edit changes nothing for the next.

PLG-61. The extension's methods are in mcp/skill_extension.py alone, apart from skill.py, because FastMCP has no support for the Skills extension of its own. The file can be deleted once it has.

The prompts

PLG-23. prompts.register publishes every plugin/prompts/*.md file as an MCP prompt, named by the file name without .md: build_flow and repair_flow are shipped. Prompts are served whether or not the skill is, and listed the same to every caller (surfaces.md, SURF-16).

PLG-24. A prompt file is YAML frontmatter and a body. The keys read are description (whitespace collapsed; none when empty) and arguments, a list of mappings with a name and optionally description, required (default false) and default.

PLG-25. A placeholder is {{ name }}, spaces optional, name being a letter or _ and then letters, digits or _. Single braces are text, so a flow's ${param} and a JSON example render as written.

PLG-26. A prompt file is refused when:

  • it has no frontmatter block or an unterminated one;
  • its frontmatter is not a mapping or its YAML does not parse;
  • arguments is not a list, or an item is not a mapping with a name;
  • an argument is both required and has a default;
  • its body has a placeholder no argument declares.

load_prompts logs a refused or unreadable file and skips it, and the other prompts and the server are unaffected. A test loads every shipped prompt strictly.

PLG-27. A prompt renders as one user text. A value of None or "" counts as not given. A placeholder renders as the given value, else the argument's default, else the empty string. A required argument not given fails with Missing required arguments: <names>.

PLG-28. repair_flow's flow argument completes from the flow names the caller can read, from flow://flows.

PLG-29. A failed flow run's hint names repair_flow with its flow and step, because an agent cannot invoke a prompt but can tell a person which to pick. With the skill served the hint also carries a read URI of a reference page and a section beside it.

The agents extension

PLG-30. The agents are served when the skill is, and only then: server.py registers them beside the skill, with the skill's name as the only skill an agent may name. With mcp.skill off, or a skill that did not load, nothing is declared and agents/list answers Method not found. With the skill served, the extension is declared whatever the folder holds, and whether or not the skill conforms to the Skills extension. An empty folder gives an empty agents/list.

PLG-31. The server declares io.modelcontextprotocol/agents with the value {"listChanged": false} and binds agents/list and agents/get. FastMCP declares it on server/discover; a middleware adds it to initialize and keeps any extension already there. The methods answer any caller. The server sends no notifications/agents/list_changed.

PLG-32. The server serves definitions and the host runs them. An agent is never a resource, a prompt or a tool.

PLG-33. agents.load reads the *.md files directly in plugin/agents/, in file-name order, not those in subfolders. A file is skipped, with a warning naming it and the reason, when:

  • it cannot be read as UTF-8;
  • it has no YAML frontmatter, or one that is not a non-empty mapping, or one that does not survive JSON;
  • its name is not a non-empty string, or holds whitespace, a control or invisible character, / or @;
  • it has no non-empty string description.

PLG-34. Two files with one name: the first by file name is served, and the second is skipped with a warning naming the file that holds the name.

PLG-35. mcp/frontmatter.py, shared with the Skills extension, splits the header: the lines between a first line of --- and the next line that is --- once its trailing whitespace is cut. A --- inside a value is not an end. A \r\n file loads.

PLG-36. agents/list returns the cards in name order. A card has name; description, with whitespace collapsed; and capabilities, the frontmatter's list when it is a list of strings and [] otherwise.

PLG-37. agents/get takes a required, non-empty name and returns:

Field Value
agent the name
instructions the body, stripped; absent when blank
modelRoutingHint from model (PLG-38); absent when none applies
tools always []
_meta {"io.kubed/agent": {"frontmatter": …, "skills": {…}}}

PLG-38. model is lowercased and split into runs of letters and digits. The first run that is opus, sonnet or haiku gives the hint {"role": "large"}, "medium" or "small", with "vision": false. inherit, a model naming none of them, and a model that is not a string give none.

PLG-39. tools is empty because the extension allows only the answering server's own tools, and an agent's tools are the host's to grant. The frontmatter's tools list reaches a host only through _meta.

PLG-40. _meta["io.kubed/agent"] is one shape for every server that serves agents. frontmatter is the header as written. skills maps each name in the frontmatter's skills list that is the served skill to skill://<name>/SKILL.md; other names are left out, a skills that is not a list of strings counts as none, and the value is {} when none resolve.

PLG-41. An agent's instructions are its body as written. The server rewrites nothing in it: no plugin:skill name, no ${CLAUDE_PLUGIN_ROOT}. A shipped agent names the skill by its full skill:// URI, which a client reads as any resource.

PLG-42. agents/list has one page: any cursor fails with -32602 and Invalid agents cursor. An unknown name fails with -32602, Agent not found and data: {"reason": "agent_not_found"}. Both results carry resultType: "complete", ttlMs: 0 and cacheScope: "private", and each is a deep copy.

The explorer agent

PLG-44. plugin/agents/explorer.md is the one shipped agent. It explores a website for a main agent, in that agent's workspace and browser, and hands back a short report. Its habit is to try a saved flow before driving by hand, and to save a flow for what will recur.

PLG-45. Its frontmatter holds name: explorer; a description written for the main agent, saying that the explorer drives the workspace's browser so the main agent calls no selenium-flow tool until it reports, that it needs the question, the start URL and the values a flow needs, and that it changes nothing on a site unless the hand-off names the exact step; model: sonnet, which routes as medium; maxTurns: 40; skills: [selenium-flow]; and a tools list.

PLG-46. The tools list names fourteen registered tools: open_session, navigate, extract, outline, screenshot, interact, write, press_key, frame, dialog, await_control, run_flow, save_flow and execute_script. It uses no host-qualified name (mcp__…). It leaves out end_browser, delete_flow, resize, save_site_data, upload_file, drag, print, keep_file, show, assert and network_body.

PLG-47. The body tells the explorer to read skill://selenium-flow/SKILL.md before any browser call and FLOWS.md before its first save_flow, following the body where they differ; to read workspace://current and start on the open session's page; to call open_session only when there is none, because opening one ends the browser the main agent holds; to call await_control once on a refusal that names it and stop if a person still holds the browser; and to leave the browser open on its last page.

PLG-48. Where a result or workspace://current carries flows_here, the explorer applies the skill's rule to the step in hand before driving by hand. It runs a flow only with values the main agent gave it or the page shows, never because a flow is hinted, and counts a flow that changes the site as that change.

PLG-49. The explorer saves a flow for a sequence that will plainly recur, with sites and paths set so that flows_here offers it. Before each save it reads flow://flows, and a name listed there, in the workspace or the shared library, is taken unless it saved that flow in this run. The server does not enforce this: save_flow replaces without asking.

PLG-50. The explorer takes no step that changes the site (an order, a message, a deletion, a form submit, a search or a login included) unless the hand-off names it, and then once. A second time, or a step not named, goes in its report with the step it would have taken. When unsure it treats a step as one that changes the site.

PLG-51. The explorer stops when the question is answered, when something it was not given blocks it, when the next step is unnamed and would change the site, when a person still holds the browser after one await_control, or at 40 turns. By about turn 35 it writes its report.

PLG-52. The report is Markdown of about 200 words under five headings in this order: Found, Flows used, Flows saved, Couldn't and Browser. Browser is an origin, a path and a hash route, with no query string. The report holds no page text beyond the answer and no inline screenshot.

PLG-53. Every tool name the explorer's text quotes and the server lists is in its tools, and every URI its body names is served: a skill:// file exists in the folder, any other is a listed resource or template. A test holds both.

A client that does not know the extensions

PLG-54. Every client reads the skill as resources: resources/list, resources/read and skill://selenium-flow/_manifest, with no extension in play (PLG-14).

PLG-55. A client whose model cannot read resources gets list_resources and read_resource, which list and read the same skill:// URIs (SURF-15).

PLG-56. A client lists the prompts with prompts/list and renders one with prompts/get.

PLG-57. The agents are reachable only through agents/list and agents/get. A client that does not call them never sees an agent.

What the instructions say

PLG-58. See PROT-28 and PROT-31: with the skill served, the server's instructions end with a pointer to skill://selenium-flow/SKILL.md, and with it off or not loaded they carry none. They mention nothing else from this area.

PLG-59. See PROT-29 and PROT-30: the pointer's wording depends on whether the client can read resources, and the text is chosen on each handshake.

PLG-60. With the skill served, workspace://current carries a guidance URI for the WORKSPACES.md reference page. With the skill off it carries none.

Clone this wiki locally