Repository navigation
2026 11 20 supported skills api
History. Drafted 2026-11-20 for #193. FastMCP 4.2 deprecates
SkillProviderandfastmcp.utilities.skills, and 4.3 removes both, sopyproject.tomlpinnedfastmcp<4.3(#186). quick-mcp (kubed-mcp) re-exports no deprecated FastMCP name and will lift skill serving from selenium-flow next, so selenium-flow moves first, as the base case. The research and spike are in kubed-io/cluster'sdocs/superpowers/specs/2026-11-20-quick-mcp-app-research-2.md, section C: every behaviour below was shown on FastMCP 4.2.2 with this repo's packaged skill. Dr K's ruling (2026-11-20): strict. A skill that breaks the Agent Skills rules is not served at all and an error says why; PLG-18's partial serving goes. Calls made here (the implementer's):
- folders come from the skill's file paths, not a disk scan, so a directory with no file under it is no longer a folder (PLG-64). A skill built from code or a package has no disk, and that is what quick-mcp will serve;
- a file with no heading keeps the description
File from selenium-flow skill, which FastMCP 4.2 no longer supplies, so the_index.mdlines do not change (PLG-68);- the extension subclass stays in
skill_extension.py, now a few dozen lines (PLG-61).
For agentic workers: REQUIRED SUB-SKILL: Use skill://superpowers/subagent-driven-development/SKILL.md to implement this plan task by task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: the skill is served through fastmcp.skills (Skill, SkillCatalogProvider, a
SkillsExtension subclass) with today's behaviour, strict validation, and fastmcp>=4.2,<5.
Architecture:
-
skill.load()doesSkill.from_directory(path), thenSkill.from_filesof its files minus the reserved index names, and returnsEntryOnlySkillProvider(SkillCatalogProvider)over it. -
The provider overrides
_list_resources(SKILL.mdonly) and_get_resource(index files first, thensuper(), then the heading title). It is thedirectories.Foldersof its skill. -
skill_extension.SkillsExtension(fastmcp.skills.extension.SkillsExtension):-
settings()returns{"directoryRead": True}; -
methods()rebindsskills/listandskills/geton FastMCP's own handlers with noprotocol_versions, and adds theDirectoryReadbinding; -
clone()returns the subclass.
skill.registeradds it withmcp.add_extension, which replaces the bundled one, and keepsAdvertiseLegacyExtensionsandNameTheIndex. -
Tech Stack: Python 3.11+, fastmcp 4.2.2 (and 4.2.0, 4.2.3 for the range check), pytest, ruff.
Spec: PLG-8, PLG-13, PLG-15, PLG-17 to PLG-22, PLG-61, PLG-64, PLG-66 to PLG-68 in plugin.md, already updated on this branch. Read them before starting.
- No
SkillProvider, nofastmcp.utilities.skills, nofastmcp.server.providers.skillsimport anywhere, tests included:grep -rn "SkillProvider\|utilities.skills\|providers.skills" kubed testsfinds nothing. -
directories.pykeeps its interface (Folders,DirectoryRead,index_resource,NameTheIndex,reserved); change it only if a test proves it must. -
agents.py,frontmatter.pyandextensions.pykeep working;agents.registerstill takes the skill's name (server.py:318), now from the provider rather thanskill_info. - Behaviour tests go through a real
Client(list_resources,read_resource,list_skills,get_skill,read_skill, and the rawrequesthelper intests/fakes.pyfor legacy mode). - The served bytes are the
Skill's bytes:read_fileis never overridden. A future text translation (material delivery ruling 27, MD-50) goes into theSkillbefore the provider is built, so_manifest, the entry and every read agree. - Commits are signed locally, exact paths staged, never
-a. The maintainer is "Dr K" in anything written.
- A legacy-mode
Clientgetsskills/listandskills/getanswers and sees the extension ininitialize(the rebinding withoutprotocol_versions). - FastMCP's
_is_servedresolves every file through our_get_resource: the title swap must keep theSkillFileResourceand itsfile, or the skill silently drops out ofskills/list. - An invalid skill (bad name, folder/name mismatch, symlink) is not served at all and logs at
ERROR; a missing
SKILL.mdstill warns. - A reserved-name file is in neither
_manifest, the entry, nor a read; a file under a reserved-name folder reads and is in_manifestbut in no folder. - A
\r\nfile's digest in the entry matches whatread_resourcereturns.
Files:
- Modify:
kubed/selenium_flow/mcp/skill.py(provider onSkillCatalogProvider, strictload(), folders from file paths, titles from the skill's bytes, anamefor callers) - Modify:
kubed/selenium_flow/mcp/skill_extension.py(becomes the subclass;entry_for,_served_bytes,_problem,GetSkillParams, the hand-rolled handlers go) - Modify:
kubed/selenium_flow/server.py:126,315,318,kubed/selenium_flow/main.py:79(skill_info.namereaders),kubed/selenium_flow/mcp/show.py:212(comment only, unless a test shows_contentmust change),kubed/selenium_flow/mcp/frontmatter.py:3(docstring namesskill_extension) - Modify:
pyproject.toml:32("fastmcp[tasks]>=4.2,<5", comment says why the floor) - Test:
tests/test_skill.py,tests/test_skills_extension.py,tests/test_directories.py,tests/test_agents_extension.py,tests/test_show.py:319,tests/test_show_inventory.py:162, and whatever else the suite shows - Modify:
CHANGELOG.md(lines under [Unreleased])
Interfaces:
-
Produces:
skill.load() -> EntryOnlySkillProvider | None;EntryOnlySkillProvider(skill: Skill)with.name,.skill,children(uri),folder_uri(rel);skill.register(mcp, provider);skill_extension.EXTENSION_ID,skill_extension.SETTINGS,skill_extension.SkillsExtension. -
Step 1: Write the failing tests.
-
test_skill.py:- move
list_skills,get_skill_manifest,download_skilluses ontoClient(list_skills(),read_resource(".../_manifest"),read_skill(SKILL_URI)writing nothing: compareread_skill(...).fileswith the manifest's paths); -
test_the_packaged_skill_is_a_valid_agent_skill:fastmcp.skills.Skill.from_directory(skill_path())does not raise and itsname == SKILL_NAME; - parametrized
test_an_invalid_skill_is_not_served_at_allover a bad name, a folder/name mismatch, a missing description, and a symlinked file:load()(pointed at the tmp folder, e.g. by monkeypatchingskill.skill_path) returns None, an ERROR record names the reason, and a server built that way has noskill://resource, noskills/listand no extension inserver/discover.
- move
-
test_skills_extension.py:- replace the nonconforming-but-served test with the strict one above (or drop it there);
- assert
skills/getof the_manifestURI fails-32602withUnknown skill URI; - assert a
\r\nfile's digest and size match itsread_resourcebytes (PLG-15/20); - keep the legacy-mode parametrizations: they must pass through the rebinding.
-
test_directories.py: build servers withskill_module.register(mcp, EntryOnlySkillProvider(Skill.from_directory(folder)))(or a small helper); addtest_an_empty_directory_is_no_folder(PLG-64).
-
-
Step 2: Run them, expect failures:
pytest tests/test_skill.py tests/test_skills_extension.py tests/test_directories.py -q -p no:cacheprovider. -
Step 3: Implement as in Architecture. Notes:
-
load(): missingSKILL.md→log.warning, None.Skill.from_directoryorfrom_filesraisingValueError/OSError(pydantic'sValidationErroris aValueError) →log.errornaming the path and reason, None. The reserved-file and reserved-folder warnings stay. - Folders: every parent path of every file, plus the root; a path with a reserved segment is no folder, but its files stay in the skill (PLG-67).
- Titles: from
skill.files[path]bytes, same fence rules as_headingtoday. -
_get_resource: keep the returned object aSkillFileResourcewith the samefile(model_copy(update={"description": ...})); give a file with no titleFile from selenium-flow skill(f"File from {name} skill"). - The extension's rebinding copies FastMCP's own bindings with
protocol_versions=None(dataclasses.replaceon each ofsuper().methods()); it never names FastMCP's private_handle_list/_handle_getor_candidate_sources.clone()returnstype(self)(). (Amended after review, 11-20: the first draft named the private handlers.)
-
-
Step 4: Run the whole suite (
pytest -q -x -p no:cacheprovider,ruff check .,ruff format --check .) and fix every remaining test that named the old API or copy. -
Step 5: The range. In a throwaway venv in the scratchpad, install the project with
fastmcp==4.2.0and run the suite; again with the latest 4.x (pip index versions fastmcp). Report both results. -
Step 6: CHANGELOG under [Unreleased]:
-
- The skill is served with FastMCP's supported \fastmcp.skills` API; `fastmcp` is `>=4.2,<5` (#193).` - An invalid skill is no longer served at all, and the server logs an error saying why (#193).-
- Skill files are served byte for byte, so a \\r\n` file keeps its `\r\n` (#193).`
-
-
Step 7: Commit the exact paths, signed:
git commit -S -m "Skill: serve it with FastMCP's supported skills API, strictly (#193)".
- Review: one reviewer subagent on the diff against the spec rows and Review Focus.
- Wiki: commit this plan and the spec on the wiki branch
feat/supported-skills-api, push it, and point the superproject'sdocsat it. - Live: ask Dr K before opening the PR; then build the PR image, toggle kubed-io/selenium's
newTag,kubectl up, and check in the pod thatresources/listhas oneskill://row,_manifestandreferences/_index.mdread, andskills/listnames the skill.
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