skill.md

Make your documentation agent-ready with automatically generated skill.md files that describe your product's capabilities for AI agents.

Mintlify automatically generates a skill.md file for your project by analyzing your documentation with an agentic loop. This file stays up to date as you make updates to your documentation and requires no maintenance. You can optionally add a custom skill.md file to the root of your project that overrides the automatically generated one.

View your skill.md by appending /skill.md to your documentation site's URL. Mintlify only generates skill.md files for documentation sites that are public.

Open the skill.md for this site.

Use `skill.md` files with agents

When users connect to your Model Context Protocol (MCP) server, their agents can discover and use your skill.md files as MCP resources without installing the skills separately.

To add your skills to an agent's context manually, use the skills CLI.

Bash

npx skills add https://your-docs-domain.com

This adds your product's capabilities to the agent's context so it can take actions on behalf of users.

Install a product's skill.md files into your agent.

Open in Cursor

Install the `skill.md` files from a Mintlify-hosted documentation site into my agent context so you know what this product can do.

1. Ask me for the documentation site URL if I haven't provided one, then run `npx skills add <url>` with that URL.
2. Print the list of skills that were installed, including each skill's name and description.
3. Summarize the key capabilities in one paragraph so I know what you can now help me accomplish with this product.
4. If any skill declares required inputs or constraints in its frontmatter, call them out before I ask you to use it.

Structure of `skill.md`

Mintlify generates a skill.md file following the agentskills.io specification. The generated file includes:

Metadata: Project name, description, and version.
Capabilities: What agents can accomplish with your product.
Skills: Specific actions organized by category.
Workflows: Step-by-step procedures for common tasks.
Integration: Supported tools and services.
Context: Background on your product's architecture.

Custom skill files

Add custom skill files to override the automatically generated skill.md. Mintlify supports hosting a single skill file and a directory for multiple skills. If you delete all custom skill files, Mintlify generates a new skill.md file.

Single skill file

Add a skill.md file to the root of your project to override the automatically generated file.

Multiple skill files

Add multiple skill files to the .mintlify/skills/ directory in your project. Each skill must be in its own subdirectory with a SKILL.md file:

.mintlify/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md

When you have multiple skills, the /skill.md endpoint redirects to the /.well-known/skills/index.json discovery endpoint, which lists all available skills. The discovery endpoints make each skill individually accessible.

Use symlinks to avoid duplication

If your skill files live elsewhere in your repository (for example, in a plugins/ or skills/ directory), you can symlink .mintlify/skills to that location instead of duplicating files:

Bash

# Skills live in a top-level skills/ directory
ln -s ../skills .mintlify/skills

project/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md
  .mintlify/
    skills -> ../skills
  docs.json

Mintlify resolves symlinks during deployment, so it discovers and serves the skill files as if they were directly inside .mintlify/skills/. This works with both directory symlinks and individual skill symlinks.

Frontmatter fields

Custom skill.md files must start with YAML frontmatter.

Field	Type	Description
`name`	string	The name of your skill.
`description`	string	A brief description of what your skill does.
`license`	string	The license for your skill (for example, `MIT` or `Apache-2.0`).
`compatibility`	string	Requirements or compatibility notes (for example, runtime dependencies).
`metadata`	object	Additional metadata as string key-value pairs (for example, `author` or `version`).
`allowed-tools`	string	Space-delimited list of pre-approved tools the skill may use (experimental).
`groups`	array	Restrict the skill to specific authenticated user groups. See Restrict skills to user groups.

Example

---
name: mintlify
description: Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references.
license: MIT
compatibility: Requires Node.js for CLI. Works with any Git-based workflow.
metadata:
  author: mintlify
  version: "1.0"
---

Restrict skills to user groups

If your documentation uses authentication, you can restrict a skill to specific user groups by adding a groups array to its frontmatter. Group filtering works the same way as page visibility: the skill is only exposed to authenticated users who belong to at least one of the listed groups.

SKILL.md

---
name: admin-tools
description: Internal operations for administrators.
groups: ["admin"]
---

Group-gated skills are:

Hidden from the public skills discovery endpoints and the public /skill.md file.
Exposed as MCP resources only to authenticated end users whose groups match. Users who don't match, and machine-to-machine clients without an end user, only see ungrouped skills.

Skills without a groups field remain visible to everyone.

Skills discovery endpoints

Mintlify hosts skills directories at /.well-known/skills/ and /.well-known/agent-skills/ that agents can use to discover and fetch your skill files programmatically.

Agent-skills discovery (recommended)

The /.well-known/agent-skills/ endpoint follows the agent-skills 0.2.0 discovery spec and includes content integrity verification.

GET /.well-known/agent-skills/index.json returns a JSON manifest listing all available skills:

JSON

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my-product",
      "type": "skill-md",
      "description": "A brief description of what your skill does.",
      "url": "/.well-known/agent-skills/my-product/SKILL.md",
      "digest": "sha256:a1b2c3..."
    }
  ]
}

Field	Description
`$schema`	Schema URL for the agent-skills 0.2.0 discovery spec.
`name`	A URL-safe slug derived from the `name` in your `skill.md` frontmatter.
`type`	The skill format. Always `skill-md`.
`description`	A brief description from your `skill.md` frontmatter, truncated to 1024 characters.
`url`	The path to fetch the full skill file.
`digest`	A `sha256` hash of the skill file content for integrity verification.

GET /.well-known/agent-skills/{name}/SKILL.md returns the skill.md file for a specific skill identified by its slugified name from the index.

Skills index

The /.well-known/skills/ endpoint is the original discovery format.

GET /.well-known/skills/index.json returns a JSON manifest listing all available skills:

JSON

{
  "skills": [
    {
      "name": "my-product",
      "description": "A brief description of what your skill does.",
      "files": ["SKILL.md"]
    }
  ]
}

The name field is a URL-safe slug derived from the name in your skill.md frontmatter.

Individual skill files

GET /.well-known/skills/{name}/skill.md returns the skill.md file for a specific skill identified by its slugified name from the index.

Agent card

Mintlify hosts an Agent-to-Agent (A2A) agent card at /.well-known/agent-card.json. The agent card is a standardized JSON document that helps A2A-compatible agents discover your documentation site and available skills in a single request.

GET /.well-known/agent-card.json returns a JSON document following the A2A agent card 0.3 schema. Each entry in the skills array corresponds to a skill from your skills discovery endpoints.

A2A-compatible agents fetch /.well-known/agent-card.json to discover your site by name and description, follow documentationUrl to retrieve human-readable content, and iterate over skills to fetch each skill.md file. The card also advertises a supportedInterfaces array so agents can negotiate transport before making a request.

Field	Description
`protocolVersion`	A2A protocol version. Always `0.3`.
`preferredTransport`	Default transport for clients that do not negotiate. Always `HTTP+JSON`.
`supportedInterfaces`	Array of `{ url, protocolBinding, protocolVersion }` entries describing how agents can reach your site.
`provider`	`{ url, organization }` identifying the documentation site. `organization` is the site title.
`defaultInputModes`	Media types the agent accepts as input. Always `["text/plain"]`.
`defaultOutputModes`	Media types the agent produces. Always `["text/plain"]`.
`capabilities`	Feature flags. Currently `{ streaming: false, pushNotifications: false }`.
`skills`	The skills exposed at `/.well-known/agent-skills/`.

URLs in the card (url, documentationUrl, provider.url, and each skill URL) use your configured custom domain, so the published card always advertises the canonical domain instead of the *.mintlify.site subdomain.

The agent card complements MCP by providing a lightweight discovery layer that does not require establishing a session.

Search documentation

Get started

Create content

Manage your site

Agent

Assistant

Agent-ready content

Document APIs

Integrations

Reference

skill.md

Use `skill.md` files with agents

Structure of `skill.md`

Custom skill files

Single skill file

Multiple skill files

Use symlinks to avoid duplication

Frontmatter fields

Restrict skills to user groups

Skills discovery endpoints

Agent-skills discovery (recommended)

Skills index

Individual skill files

Agent card

Get started

Create content

Manage your site

Agent

Assistant

Agent-ready content

Document APIs

Integrations

Reference

Use skill.md files with agents

Structure of skill.md

Custom skill files

Single skill file

Multiple skill files

Use symlinks to avoid duplication

Frontmatter fields

Restrict skills to user groups

Skills discovery endpoints

Agent-skills discovery (recommended)

Skills index

Individual skill files

Agent card

Related topics

Use `skill.md` files with agents

Structure of `skill.md`