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.
A skill is a directory
Section titled “A skill is a directory”skills/notes/├── SKILL.md└── references/style.mdSKILL.md starts with frontmatter that has a name and a description. The directory’s name is the skill’s name.
---name: notesdescription: 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 thatalready says the same thing. See [the style guide](references/style.md) for how a note reads.Register the skills
Section titled “Register the skills”One call registers every skill the server publishes.
"""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>.
Generated or packaged files
Section titled “Generated or packaged files”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 frontmattername. - A directory’s skill path defaults to the directory’s name.
SkillDefinition.from_directory(dir, path=...)overrides it. - Dotfiles and
__pycache__are skipped.
What is checked at startup
Section titled “What is checked at startup”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
nameoutside 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.
Test it
Section titled “Test it”served_skills connects the way a host does, lists the skills, reads every file back and checks it against its digest.
"""The skills a host sees, read back and verified against their digests on both eras."""
import pytestfrom 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", }On the wire
Section titled “On the wire”- Frontmatter is parsed with YAML 1.2 semantics for booleans, numbers and dates (
yes,1:30and2026-01-01stay strings, and017is 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/listreturns every skill in one page. On protocol2026-07-28both results carryttlMs: 0andcacheScope: "private".- On a 2025-era (
initialize) connection the declaration is not sent, because that handshake carries nocapabilities.extensions.skills/listandskills/getanswer on either era.
With the mcp SDK’s MCPServer
Section titled “With the mcp SDK’s MCPServer”A server built on mcp.server.mcpserver.MCPServer instead of FastMCP passes the extension at construction:
from mcp.server.mcpserver import MCPServerfrom nimblebrain_server_sdk import MCPServerSkillsExtension
server = MCPServer("notes", extensions=[MCPServerSkillsExtension([SKILLS / "notes"])])Related
Section titled “Related”- Skills in NimbleBrain: how a skill loads, and its file format
- Testing
- API reference