Skip to content

2026 11 20 supported skills api

Kelly Ferrone edited this page Nov 20, 2026 · 3 revisions

Supported Skills API Plan

History. Drafted 2026-11-20 for #193. FastMCP 4.2 deprecates SkillProvider and fastmcp.utilities.skills, and 4.3 removes both, so pyproject.toml pinned fastmcp<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's docs/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.md lines 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() does Skill.from_directory(path), then Skill.from_files of its files minus the reserved index names, and returns EntryOnlySkillProvider(SkillCatalogProvider) over it.

  • The provider overrides _list_resources (SKILL.md only) and _get_resource (index files first, then super(), then the heading title). It is the directories.Folders of its skill.

  • skill_extension.SkillsExtension(fastmcp.skills.extension.SkillsExtension):

    • settings() returns {"directoryRead": True};
    • methods() rebinds skills/list and skills/get on FastMCP's own handlers with no protocol_versions, and adds the DirectoryRead binding;
    • clone() returns the subclass.

    skill.register adds it with mcp.add_extension, which replaces the bundled one, and keeps AdvertiseLegacyExtensions and NameTheIndex.

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.

Global Constraints

  • No SkillProvider, no fastmcp.utilities.skills, no fastmcp.server.providers.skills import anywhere, tests included: grep -rn "SkillProvider\|utilities.skills\|providers.skills" kubed tests finds nothing.
  • directories.py keeps its interface (Folders, DirectoryRead, index_resource, NameTheIndex, reserved); change it only if a test proves it must.
  • agents.py, frontmatter.py and extensions.py keep working; agents.register still takes the skill's name (server.py:318), now from the provider rather than skill_info.
  • Behaviour tests go through a real Client (list_resources, read_resource, list_skills, get_skill, read_skill, and the raw request helper in tests/fakes.py for legacy mode).
  • The served bytes are the Skill's bytes: read_file is never overridden. A future text translation (material delivery ruling 27, MD-50) goes into the Skill before 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.

Review Focus

  1. A legacy-mode Client gets skills/list and skills/get answers and sees the extension in initialize (the rebinding without protocol_versions).
  2. FastMCP's _is_served resolves every file through our _get_resource: the title swap must keep the SkillFileResource and its file, or the skill silently drops out of skills/list.
  3. An invalid skill (bad name, folder/name mismatch, symlink) is not served at all and logs at ERROR; a missing SKILL.md still warns.
  4. A reserved-name file is in neither _manifest, the entry, nor a read; a file under a reserved-name folder reads and is in _manifest but in no folder.
  5. A \r\n file's digest in the entry matches what read_resource returns.

Task 1: Serve the skill through fastmcp.skills (#193)

Files:

  • Modify: kubed/selenium_flow/mcp/skill.py (provider on SkillCatalogProvider, strict load(), folders from file paths, titles from the skill's bytes, a name for 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.name readers), kubed/selenium_flow/mcp/show.py:212 (comment only, unless a test shows _content must change), kubed/selenium_flow/mcp/frontmatter.py:3 (docstring names skill_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_skill uses onto Client (list_skills(), read_resource(".../_manifest"), read_skill(SKILL_URI) writing nothing: compare read_skill(...).files with the manifest's paths);
      • test_the_packaged_skill_is_a_valid_agent_skill: fastmcp.skills.Skill.from_directory(skill_path()) does not raise and its name == SKILL_NAME;
      • parametrized test_an_invalid_skill_is_not_served_at_all over a bad name, a folder/name mismatch, a missing description, and a symlinked file: load() (pointed at the tmp folder, e.g. by monkeypatching skill.skill_path) returns None, an ERROR record names the reason, and a server built that way has no skill:// resource, no skills/list and no extension in server/discover.
    • test_skills_extension.py:
      • replace the nonconforming-but-served test with the strict one above (or drop it there);
      • assert skills/get of the _manifest URI fails -32602 with Unknown skill URI;
      • assert a \r\n file's digest and size match its read_resource bytes (PLG-15/20);
      • keep the legacy-mode parametrizations: they must pass through the rebinding.
    • test_directories.py: build servers with skill_module.register(mcp, EntryOnlySkillProvider(Skill.from_directory(folder))) (or a small helper); add test_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(): missing SKILL.md → log.warning, None. Skill.from_directory or from_files raising ValueError/OSError (pydantic's ValidationError is a ValueError) → log.error naming 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 _heading today.
    • _get_resource: keep the returned object a SkillFileResource with the same file (model_copy(update={"description": ...})); give a file with no title File from selenium-flow skill (f"File from {name} skill").
    • The extension's rebinding copies FastMCP's own bindings with protocol_versions=None (dataclasses.replace on each of super().methods()); it never names FastMCP's private _handle_list / _handle_get or _candidate_sources. clone() returns type(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.0 and 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)".

After the task (controller)

  • 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's docs at 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 that resources/list has one skill:// row, _manifest and references/_index.md read, and skills/list names the skill.

Clone this wiki locally