Skip to main content

Agent Skills

Tool descriptions tell an agent what docs_search and docs_fetch do, not how to research your docs well. The server can also ship that guidance as Agent Skills, through the MCP skills extension (SEP-2640, io.modelcontextprotocol/skills).

Transcript

Tool descriptions tell an agent what your docs tools do, not how to use your docs well. Agent Skills fill that gap, and your docs site can ship them.

Every build includes one skill, docs-research. It's written from your site. It tells the agent to search, fetch the page, and link its source, then maps where things are.

Add your own for what only your team knows. Put each skill in a folder with a SKILL.md, and point the plugin at the parent folder.

Build the site. The plugin checks every skill, and packs it into the same bundle as your docs. There's nothing extra to deploy.

The server supports the MCP skills extension. Few hosts do yet, so its instructions also list every skill, and tell the agent to read it with docs_fetch.

Here's Claude Code, with a request that fails with a 429. It reads the error skill first, searches, fetches the rate limiting section, and answers with the fix and a link.

Read the Agent Skills guide on the plugin's docs site.

The built-in docs-research skill​

By default the plugin packages one skill, docs-research, which covers the search → fetch → cite workflow for your site. It's generated from your site at build time:

  • Its description names your docs, host, and tagline, for example "Answer questions using the Acme documentation at acme.dev (Build faster)". Agents read the description to decide when to load the skill.
  • A Where things are section groups the indexed pages by URL path, largest sections first. Each section lists its page count, a link to its overview page if there is one, and a few example page titles. It's left out when the pages don't form at least two multi-page sections.

The built-in skill is generic by design. For a skill that knows your product (its terminology, where each topic lives, the questions people actually ask), write your own docs-research skill. It replaces the built-in one. Start from a copy of skills-builtin/docs-research/.

Add your own skills​

Put each skill in its own directory with a SKILL.md at its root, and point the plugin at the parent directory:

// docusaurus.config.js
module.exports = {
plugins: [
[
'docusaurus-plugin-mcp-server',
{
server: { name: 'my-docs' },
// Serve the built-in docs-research skill plus every skill in ./mcp-skills
skills: { dir: 'mcp-skills' },
},
],
],
};
mcp-skills/
└── api-migration/
├── SKILL.md # YAML frontmatter with name + description, then instructions
└── references/
└── v1-to-v2.md

At build time the plugin:

  • validates every skill. The frontmatter name must match the directory name, and a skill can have at most 512 files and 16 MiB. Invalid skills fail the build with a SkillValidationError.
  • follows a symlinked skill directory in dir, skips symlinks inside a skill with a warning, and packages bundled scripts (.sh, .py, .js, …) with a warning.
  • precomputes SHA-256 digests and adds the skills to the artifact bundle, so the handler serves them with no extra config.

If you copy the built-in skill, replace its placeholders ({{siteDocs}}, {{siteSummary}}, {{siteMap}}) with your own wording. They're only filled in for the built-in copy.

SettingResult
(default)Built-in docs-research only
skills: { dir: 'mcp-skills' }Built-in skill plus yours. An author skill named docs-research replaces the built-in one
skills: { builtin: false, dir: 'mcp-skills' }Only your skills
skills: falseNo skills

Skills from your pages​

A setup or troubleshooting procedure can be a skill without a separate SKILL.md: mark it up in the page with AgentGuide, Step, Check, and Symptom, and the build compiles it into a skill named after the guide, served next to these. See Agent guides. A guide can't share a name with any other skill, including one in dir or the built-in docs-research.

To ship the same guides in your repository for npx skills add, copy them out of build/mcp/bundle.json after the build. This site does that with website/scripts/sync-skills.mjs, and CI fails if a page changes without a sync.

How clients get skills​

At runtime the server:

  • declares the io.modelcontextprotocol/skills extension and implements skills/list and skills/get.
  • serves every skill file as a resource at skill://<name>/<path>, for example skill://docs-research/SKILL.md.
  • adds a pointer to the skills to the server instructions, with each skill's URI and description, so clients that don't support the extension yet can still find the skills. See Instructions sent to clients.
  • lets docs_fetch read any skill file by its skill:// URI. Few hosts support the skills extension yet, and many let only the user, not the model, read resources, but every host lets the model call tools. The instructions tell the agent to use docs_fetch, or resources/read where the client supports it.

Keep skills to Markdown. MCP hosts treat served skills as untrusted input and won't run bundled scripts without the user's explicit approval.