API Reference / agent / mcp /

skills.py

Skills over MCP (SEP-2640) support for the TuiML MCP server.

The bundled SKILL.md (the canonical TuiML agent guide, also installed by tuiml setup as a Claude Code skill) is served over MCP so any client that speaks the io.modelcontextprotocol/skills extension can discover and read it without a separate install step. The server:

  • advertises capabilities.extensions["io.modelcontextprotocol/skills"];
  • serves skills/list and skills/get (the extension's two methods);
  • exposes every skill file as an ordinary MCP resource under the
skill:// scheme (skill://tuiml/SKILL.md), so clients without the extension can still read the guide via resources/read.

The wire shapes follow the SEP-2640 working draft maintained by the Skills Over MCP working group (https://github.com/modelcontextprotocol/experimental-ext-skills).

python 
>>> from tuiml.agent.mcp.skills import get_skill_entry, SKILL_MD_URI
>>> entry = get_skill_entry()
>>> entry["uri"] == SKILL_MD_URI
True
>>> entry["frontmatter"]["name"]
'tuiml'
>>> [r["uri"] for r in entry["resources"]][:2]
['skill://tuiml/SKILL.md', 'skill://tuiml/reference/cli.md']
>>> entry["resources"][0]["digest"][:7]
'sha256:'

Functions

Func

parse_frontmatter

Line 91
parse_frontmatter(text: str) -> Dict[str, str]

Parse the flat key: value YAML frontmatter at the top of a SKILL.md.

Only the flat subset used by Agent Skills frontmatter is supported (name, description, version, ...). Nested or multi-line values are not needed by the bundled skill, so no YAML dependency is pulled in.

Parameters

text
str
Full Markdown text, optionally starting with a --- block.

Returns

dict of str -> str
Frontmatter fields, or an empty dict if there is no frontmatter.
Func

get_skill_frontmatter

Line 164
get_skill_frontmatter() -> Dict[str, str]

Return the SKILL.md frontmatter as a dict.

Returns

dict of str -> str
At least name and description; the bundled file also carries version and mcp_server.
Func

get_skill_entry

Line 176
get_skill_entry() -> Dict[str, Any]

Build the SEP-2640 skill entry returned by skills/list and skills/get.

Returns

dict
{"uri", "frontmatter", "resources"} where resources lists every file with its uri, sha256: digest and size so a client can install and verify the skill.
Func

list_skills

Line 201
list_skills() -> Dict[str, Any]

Build the skills/list result.

Returns

dict
{"skills": [entry]} with the single bundled TuiML skill. The list is complete, so no nextCursor is set.
Func

get_skill

Line 213
get_skill(uri: str) -> Optional[Dict[str, Any]]

Resolve a skills/get request.

Parameters

uri
str
Either the skill's SKILL.md URI or its root URI.

Returns

dict or None
The skill entry, or None if uri names no bundled skill.
Func

list_skill_resources

Line 231
list_skill_resources() -> List[Dict[str, Any]]

Describe every skill file for resources/list.

Returns

list of dict
One entry per file with uri, name, description, mime_type and size, ready to unpack into mcp.types.Resource. SKILL.md takes its name and description from the frontmatter, as SEP-2640 recommends.
Func

read_skill_resource

Line 260
read_skill_resource(uri: str) -> Optional[Tuple[str, str]]

Resolve a resources/read for a skill:// URI.

Parameters

uri
str
A skill://tuiml/<file> URI.

Returns

tuple of (str, str) or None
(mime_type, text) for a known file, else None.