Skip to content

Skills

A skill is a set of instructions an agent loads when its work matches: how to use your tools well, in your words. A server publishes skills by declaring the MCP Skills extension, io.modelcontextprotocol/skills. What NimbleBrain does with a published skill is in Skills published by an MCP server.

skills/notes/
├── SKILL.md
└── references/style.md

SKILL.md starts with frontmatter that has a name and a description. The directory’s name is the skill’s name.

skills/notes/SKILL.md
---
name: notes
description: How to keep notes with this server. Use when the user asks to save, find or tidy notes.
---
# Notes
Save one fact per note with `save_note`. Before saving, call `list_notes` and skip a note that
already says the same thing. See [the style guide](references/style.md) for how a note reads.

One call registers every skill the server publishes.

skills_server.py
"""A server that publishes a skill: instructions an agent loads when its work matches."""
from pathlib import Path
from fastmcp import FastMCP
from nimblebrain_server_sdk import SkillDefinition, add_skills
mcp = FastMCP("notes")
# A directory holding SKILL.md and its reference files; the directory name is the skill's name.
NOTES_SKILL = Path(__file__).parent / "skills" / "notes"
# A skill whose files are built at startup instead of read from a directory.
glossary = SkillDefinition(
"glossary", # served at skill://glossary/SKILL.md
{
"SKILL.md": "---\nname: glossary\ndescription: The words this team uses.\n---\n\n"
"A *note* is one fact. A *board* is a set of notes.\n",
},
)
add_skills(mcp, [NOTES_SKILL, glossary])

add_skills answers skills/list and skills/get with each skill’s entry (its SKILL.md URI, its frontmatter verbatim, and a sha256 digest and byte size for every file) and serves every file through resources/read at skill://<skill-path>/<file-path>.

When a skill’s files are not a directory of their own (a SKILL.md built at startup, or one packaged beside other code), pass a SkillDefinition with the skill path and the files keyed by their path in the skill, as glossary does above.

  • The skill path may carry a prefix ("acme/billing/refunds"). Its last segment must equal the frontmatter name.
  • A directory’s skill path defaults to the directory’s name. SkillDefinition.from_directory(dir, path=...) overrides it.
  • Dotfiles and __pycache__ are skipped.

Everything the specification requires of a skill is checked when the server is built, so a bad skill fails then and not on a host’s first read:

  • a missing SKILL.md, or one with no frontmatter;
  • a name outside the Agent Skills naming rules, or one that differs from the last path segment;
  • a file path that escapes the skill, or that a URI would encode differently;
  • two skills at one URI.

A skill beyond the specification’s limits (512 files or 16 MiB) logs a warning.

served_skills connects the way a host does, lists the skills, reads every file back and checks it against its digest.

test_skills_server.py
"""The skills a host sees, read back and verified against their digests on both eras."""
import pytest
from skills_server import mcp
from nimblebrain_server_sdk.testing import Mode, served_skills
@pytest.mark.parametrize("mode", ["auto", "legacy"])
async def test_the_server_publishes_its_skills(mode: Mode) -> None:
skills = await served_skills(mcp, mode) # lists, reads every file, checks each digest
assert set(skills) == {"skill://notes/SKILL.md", "skill://glossary/SKILL.md"}
notes = skills["skill://notes/SKILL.md"]
assert notes["frontmatter"]["name"] == "notes"
assert {r["uri"] for r in notes["resources"]} == {
"skill://notes/SKILL.md",
"skill://notes/references/style.md",
}
  • Frontmatter is parsed with YAML 1.2 semantics for booleans, numbers and dates (yes, 1:30 and 2026-01-01 stay strings, and 017 is 17), matching the parsers hosts compare with.
  • Text files are served as text resources and anything that is not UTF-8 as a blob. Either way the digest covers the raw file bytes.
  • skills/list returns every skill in one page. On protocol 2026-07-28 both results carry ttlMs: 0 and cacheScope: "private".
  • On a 2025-era (initialize) connection the declaration is not sent, because that handshake carries no capabilities.extensions. skills/list and skills/get answer on either era.

A server built on mcp.server.mcpserver.MCPServer instead of FastMCP passes the extension at construction:

from mcp.server.mcpserver import MCPServer
from nimblebrain_server_sdk import MCPServerSkillsExtension
server = MCPServer("notes", extensions=[MCPServerSkillsExtension([SKILLS / "notes"])])