Agent skills

Your documentation tells agents what your product does. Agent skills tell them how to work in your repository: review checklists, doc-writing pipelines, release steps, and other repeatable workflows you encode as markdown.

Before you begin

• MCP enabled on your published public site (see MCP server)
• Context on how agent surfaces fit together (see Agent-ready docs)

There is no skills toggle in docs.json. When MCP is on and the repo is public, docs.page scans .agents/skills/** and registers each SKILL.md automatically.

Agent skills are instruction files you commit to your repository. docs.page exposes each SKILL.md as an MCP resource on your site's MCP server, on the same Git ref as your hosted docs.

Skills are optional. Add them when your team encodes repeatable workflows in markdown and you want external agents to discover those instructions through the same MCP endpoint as your docs.

Each skill lives in its own folder under .agents/skills/. The entry point must be named SKILL.md:

.agents/skills/
  docs-write/
    SKILL.md
  release/
    SKILL.md
    templates.md

Nested folders are supported. A file at .agents/skills/team/deploy/SKILL.md registers as skill slug team/deploy.

Only paths matching .agents/skills/**/SKILL.md are published. Supporting files in the same folder stay in Git for authors but are not separate MCP resources.

Each skill becomes a markdown resource with a stable URI:

docs-page://skills/{slug}

For example, .agents/skills/docs-write/SKILL.md maps to docs-page://skills/docs-write. Clients list resources through the MCP session, then fetch the skill body as text/markdown.

Discovery runs when the server starts a session: docs.page reads the GitHub tree for the current ref and serves file contents on demand. If MCP is disabled (mcp.enabled: false) or the repository is private, skill resources are unavailable.

See Agent skills on Features for URI encoding and access rules.

• Create one folder per skill

  Give agents a named entry point: add .agents/skills/{name}/SKILL.md with markdown instructions. Use YAML frontmatter (name, description) when your client expects it.

• Push to the branch your MCP client targets

  Publish on the resolved ref: commit and push. Production MCP URLs use the default branch; branch previews use the ~{ref} segment in the site URL.

• Verify in your MCP client

  Confirm resources appear: list MCP resources on your docs server. You should see one entry per SKILL.md, plus docs-page-config-schema. Fetch a skill to load its instructions. Start a fresh MCP session after pushing if the catalog looks stale.

• Agent-ready docs: how skills fit alongside llms.txt and Ask AI
• MCP server: connect Cursor, Claude Code, or another MCP client
• Agent skills on Features: discovery mechanics and URI details