Skip to content
Back to blog

How to serve Agent Skills from an MCP server

Agent Skills are folders of instructions an agent loads when a task calls for them. Learn how the MCP Skills extension publishes them from your server and how to ship one with xmcp.

An MCP server can ship Agent Skills alongside its tools. A skill is a directory with a SKILL.md file and any supporting files, and the MCP Skills extension (io.modelcontextprotocol/skills) is how a server publishes it. With xmcp, you add the directory under src/skills and the server does the rest.

This guide follows the repository's skills example.

What is an Agent Skill?

An Agent Skill is a set of written instructions for a task, packaged as files. SKILL.md holds YAML frontmatter with a name and a description, followed by the instructions in Markdown. Supporting files, such as a template or a reference table, sit next to it.

The description says what the skill does and when to use it. A client that supports skills lists them, shows them to the user, and loads one when a task calls for it.

How are skills different from tools and prompts?

A tool runs code. A prompt is a message template. A skill is the instructions for using them well.

ToolPromptSkill
What it isA function with an input schemaA reusable message templateMarkdown instructions plus supporting files
What it returnsA result from running your codeMessages for the modelFile contents
How it is fetchedtools/list, tools/callprompts/list, prompts/getskills/list, skills/get, resources/read
Typical useFetch data or perform an actionStart a task from a known requestTeach a multi-step workflow using your tools

Skills and tools work together. The example's skill tells the agent to call the server's list-merged-changes tool, then format the result with a template file.

See MCP Tools vs Resources vs Prompts for the three core primitives.

How do I add a skill to an xmcp server?

Create a directory under src/skills whose name is the skill's name, and put a SKILL.md in it:

Text
src/skills/release-notes/SKILL.md

There is nothing to export and no wrapper to write. xmcp reads src/skills by default, validates each skill at build time, and embeds the files in the bundle. That means skills are served without filesystem access, including on Cloudflare Workers.

The frontmatter follows the Agent Skills specification:

  • name is required and must equal the directory name: at most 64 lowercase letters, numbers, and single hyphens.
  • description is required and can be up to 1024 characters.
  • Other fields, such as license and metadata, are published unchanged.

What does the server publish?

When at least one skill exists, the server does three things:

  1. Declares capabilities.extensions["io.modelcontextprotocol/skills"].
  2. Answers skills/list with an entry for every skill, and skills/get with the entry for one SKILL.md URI.
  3. Registers every file as a resource at skill://<skill-name>/<file-path>.

Each entry carries the skill's frontmatter and a list of its files with a SHA-256 digest and size, so a client can verify what it reads:

JSON

A server without skills is unchanged. The capability, the two methods, and the skill:// resources exist only when a skill does.

Run the example

Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:

Shell

List the skills:

Shell

Read a supporting file as an ordinary resource:

Shell

The returned text hashes to the digest published for that file. The example's README includes the server/discover and skills/get requests too.

Common questions

Do I need to write code to serve a skill?

No. A skill is plain files. Add a directory with a SKILL.md under src/skills and xmcp serves it. During development, xmcp dev picks up added, removed, and edited skill files.

What happens if a skill is invalid?

The build fails with a message naming the problem: missing frontmatter, a name that differs from the directory, a missing or too-long description, or a skill larger than 512 files or 16 MiB.

Can a client without the Skills extension use my skills?

Partly. Every skill file is also an ordinary MCP resource, so any client can find it with resources/list and read it with resources/read. Only clients that support the extension treat it as a skill.

Can I restrict who sees a skill?

Yes. Skills follow the name rules of the components configuration, and an authorize policy applies to skills/list and skills/get. Protect the full skill://<name>/ prefix in the policy to restrict every file. See MCP tool permissions for the policy itself.

Can skill content be generated at request time?

Not yet. Skills are read and embedded at build time. Skills nested under an organizational prefix and resources/directory/read are also not supported yet.

Next steps

One framework to rule them all