Skills

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

xmcp automatically detects Agent Skills under the /src/skills/ directory and serves them through the MCP Skills extension (io.modelcontextprotocol/skills). This path can be configured in your xmcp.config.ts file.

Skills ship the instructions for using your server together with the server itself. A client that supports the extension lists them, shows them to the user, and loads one when a task calls for it.

Directory structure

Each skill is a directory containing a SKILL.md file, plus any supporting files it refers to. They are plain files: there is nothing to export and no wrapper to write.

src/skills/
└── release-notes/
    ├── SKILL.md              # Required: frontmatter + instructions
    └── references/
        └── TEMPLATE.md       # Optional supporting files

SKILL.md starts with YAML frontmatter followed by the instructions in Markdown:

---
name: release-notes
description: Draft release notes from the changes merged since a release tag. Use when the user asks for a changelog or a summary of what shipped.
license: MIT
---

# Release notes

1. Call the `list-merged-changes` tool with the previous release tag.
2. Group the changes by type: features first, then fixes.
3. Write the notes using the layout in `references/TEMPLATE.md`.

The frontmatter follows the Agent Skills specification:

• name is required and must equal the directory name. Use at most 64 lowercase letters, numbers and single hyphens, without a leading or trailing hyphen.
• description is required and can be up to 1024 characters. Say what the skill does and when to use it.
• Any other field, such as license or metadata, is published unchanged.

What gets served

When at least one skill exists, the server:

• Declares capabilities.extensions["io.modelcontextprotocol/skills"].
• Answers skills/list with an entry for every skill, and skills/get with the entry for one SKILL.md URI.
• Registers every file as a resource, so resources/list and resources/read work for them like for any other resource.

Files are addressed as skill://<skill-name>/<file-path>:

Each entry carries the skill's frontmatter and a complete list of its files with their SHA-256 digest and size, which clients use to verify what they read:

{
  "uri": "skill://release-notes/SKILL.md",
  "frontmatter": {
    "name": "release-notes",
    "description": "Draft release notes from the changes merged since a release tag. Use when the user asks for a changelog or a summary of what shipped.",
    "license": "MIT"
  },
  "resources": [
    {
      "uri": "skill://release-notes/SKILL.md",
      "digest": "sha256:…",
      "size": 412
    },
    {
      "uri": "skill://release-notes/references/TEMPLATE.md",
      "digest": "sha256:…",
      "size": 83
    }
  ]
}

Servers without skills are unchanged: the capability, the two methods and the skill:// resources only exist when a skill does.

Supporting files

A skill can hold any files in any subdirectories. Text files (valid UTF-8) are served as text and everything else as a base64 blob, so the bytes a client receives always match the published digest. SKILL.md is served as text/markdown; other files get a MIME type from their extension.

Files and directories whose name starts with a dot are ignored. A SKILL.md in a subdirectory of a skill is served as a supporting file of that skill, not as a separate skill.

Build-time validation

Skills are read, validated and embedded into the bundle at build time, so they are served without filesystem access on every target, including Cloudflare Workers. The build fails with a message naming the problem when:

• A skill directory has no SKILL.md, or a file sits directly in the skills directory, when paths.skills is set to a path. With the default, these entries are skipped with a warning instead, so a src/skills directory used for other code does not break the build.
• SKILL.md has no frontmatter, starts with a byte order mark, or the frontmatter is not valid YAML.
• name is missing, differs from the directory name, or breaks the naming rules.
• description is missing or too long.
• A skill has more than 512 files or more than 16 MiB in total, the limits clients are required to support.

In development, xmcp dev picks up added, removed and edited skill files. An invalid skill is reported in the terminal and the last valid skills stay served until it is fixed.

Visibility and middleware

Skills follow the name rules of the components configuration: a skill whose name is excluded is not served, and when include is set a skill is served only if include.names lists it. Skills have no tags.

Skill files are read through resources/read, so MCP middleware for that method applies to them. skills/list and skills/get do not run through MCP middleware.

Not supported yet

• resources/directory/read: the server does not declare directoryRead. Each entry already lists every file of its skill.
• Skills nested under an organizational prefix, such as skill://acme/billing/refunds/SKILL.md.
• Skills whose content is generated at request time.

See the runnable skills example for a server with one skill and curl requests for each method.