From 4956abe363198bb0bc2d73aa66740dc50d9db317 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 9 Apr 2026 01:57:46 +0000
Subject: [PATCH] Document multiple skill files via .mintlify/skills/ directory
Generated-By: mintlify-agent
---
ai/skillmd.mdx | 33 ++++++++++++++++++++++++++++-----
1 file changed, 28 insertions(+), 5 deletions(-)
diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..cc016bd06 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -8,13 +8,13 @@ Mintlify hosts a `skill.md` file at the root of your project that describes what
The [skill.md specification](https://agentskills.io/specification) is a structured, machine-readable format that makes capabilities, required inputs, and constraints for products explicit so that agents can use them more reliably.
-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.
+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 custom skill files to override the automatically generated one.
Generating or updating a `skill.md` file can take up to 24 hours.
-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.
+View your `skill.md` by appending `/skill.md` to your documentation site's URL. If your project has multiple skills, `/skill.md` redirects to the `/.well-known/skills/index.json` discovery endpoint. Mintlify only generates `skill.md` files for documentation sites that are public.
Open the skill.md for this site.
@@ -60,6 +60,29 @@ Add a `skill.md` file to the root of your project to override the automatically
Write a custom file when you want precise control over how agents interact with your product. Follow the [agentskills.io specification](https://agentskills.io/specification) to ensure compatibility with agent tooling.
+### Multiple skill files
+
+If your product has distinct capabilities that you want to expose as separate skills, add multiple skill files to a `.mintlify/skills/` directory in your project. Each skill lives in its own subdirectory with a `skill.md` file:
+
+```
+.mintlify/
+ skills/
+ api-management/
+ skill.md
+ dashboard/
+ skill.md
+```
+
+Each `skill.md` file must include its own YAML frontmatter with a unique `name` field. The subdirectory name becomes the skill's slug in the discovery endpoints.
+
+When your project defines multiple skills:
+
+- The discovery endpoints at `/.well-known/skills/index.json` and `/.well-known/agent-skills/index.json` list all skills.
+- `/skill.md` redirects to `/.well-known/skills/index.json` so agents can discover all available skills.
+- Individual skill files are accessible at `/.well-known/skills/{slug}/skill.md`.
+
+If you only need a single skill, you can still add a `skill.md` file to the root of your project. It takes precedence over the automatically generated file.
+
### Frontmatter fields
Custom `skill.md` files must start with YAML frontmatter.
@@ -93,7 +116,7 @@ Mintlify hosts skills directories at `/.well-known/skills/` and `/.well-known/ag
The `/.well-known/agent-skills/` endpoint follows the [agent-skills 0.2.0 discovery spec](https://schemas.agentskills.io/discovery/0.2.0/schema.json) and includes content integrity verification.
-`GET /.well-known/agent-skills/index.json` returns a JSON manifest listing all available skills:
+`GET /.well-known/agent-skills/index.json` returns a JSON manifest listing all available skills. If your project defines [multiple skill files](#multiple-skill-files), each skill appears as a separate entry:
```json
{
@@ -125,7 +148,7 @@ The `/.well-known/agent-skills/` endpoint follows the [agent-skills 0.2.0 discov
The `/.well-known/skills/` endpoint is the original discovery format.
-`GET /.well-known/skills/index.json` returns a JSON manifest listing all available skills:
+`GET /.well-known/skills/index.json` returns a JSON manifest listing all available skills. If your project defines [multiple skill files](#multiple-skill-files), each skill appears as a separate entry:
```json
{
@@ -139,7 +162,7 @@ The `/.well-known/skills/` endpoint is the original discovery format.
}
```
-The `name` field is a URL-safe slug derived from the `name` in your `skill.md` frontmatter.
+The `name` field is a URL-safe slug derived from the `name` in your `skill.md` frontmatter, or the subdirectory name when using the `.mintlify/skills/` directory.
### Individual skill files