Repository navigation
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.
- An agent connects to a bare server, reads
skill://selenium-flow/SKILL.mdand drives the browser as the skill says, with nothing installed on the client. - A person picks
repair_flowafter 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.
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.
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.
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.mdhas a table row for every tool the server lists (the two mirror tools excepted) and for every resource and template (ui://andskill://excepted); - every
selector=andto=literal in the skill's pages, README.md and AGENTS.md is one thatcore.browser.locatoraccepts; - 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.
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.
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.
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;
-
argumentsis not a list, or an item is not a mapping with a name; - an argument is both
requiredand has adefault; - 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.
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
nameis 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.
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.
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.
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.
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