From c983dd6d539fb1fb553d7fc913f9b28da9dd5e5d Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 9 Apr 2026 01:57:27 +0000
Subject: [PATCH] Document multi-skill support via .mintlify/skills/ directory

Generated-By: mintlify-agent
---
 ai/skillmd.mdx | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..c527e4bdf 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -60,6 +60,30 @@ 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 are best described separately, you can create multiple skill files using the `.mintlify/skills/` directory. Each subdirectory contains a `SKILL.md` file that defines one skill.
+
+```
+.mintlify/
+└── skills/
+    ├── api-client/
+    │   └── SKILL.md
+    └── data-export/
+        └── SKILL.md
+```
+
+Each `SKILL.md` file follows the same format as a root `skill.md` file, including YAML frontmatter and the [agentskills.io specification](https://agentskills.io/specification).
+
+When you use multiple skill files:
+- The `/skill.md` endpoint redirects to `/.well-known/skills/index.json` so agents discover all available skills.
+- Each skill appears as a separate entry in the [discovery endpoints](#skills-discovery-endpoints).
+- The `name` field in each file's frontmatter determines its URL slug. For example, a skill named `api-client` is served at `/.well-known/skills/api-client/skill.md`.
+
+<Note>
+  If you have both a root `skill.md` and files in `.mintlify/skills/`, the `.mintlify/skills/` directory takes precedence.
+</Note>
+
 ### Frontmatter fields
 
 Custom `skill.md` files must start with YAML frontmatter.