From 8d8ca59e0c46b0ac2c8da47b3d20e1c6afa3164a Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 9 Apr 2026 00:10:59 +0000
Subject: [PATCH] docs: add multi-skill support via .mintlify/skills/ directory

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

diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..f08c3f380 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -60,6 +60,35 @@ 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
+
+You can define multiple skills by creating a `.mintlify/skills/` directory in your project. Each subdirectory represents a separate skill and must contain a `SKILL.md` file.
+
+```
+your-project/
+├── .mintlify/
+│   └── skills/
+│       ├── authentication/
+│       │   └── SKILL.md
+│       ├── webhooks/
+│       │   └── SKILL.md
+│       └── data-export/
+│           └── SKILL.md
+└── docs/
+```
+
+Mintlify uploads each skill separately and generates a manifest so agents can discover and load only the skills they need. When you provide custom skills in `.mintlify/skills/`, Mintlify skips auto-generating a `skill.md` file.
+
+<Note>
+  You can still place a single `skill.md` at the project root. If you use both a root `skill.md` and the `.mintlify/skills/` directory, all files are included in the skills manifest.
+</Note>
+
+#### How slugs are derived
+
+The subdirectory name becomes the skill's URL slug. Mintlify sanitizes it by lowercasing, replacing non-alphanumeric characters with hyphens, and stripping leading or trailing hyphens. For example, `My API Client` becomes `my-api-client`.
+
+If you place a single `skill.md` at the project root instead of using subdirectories, the slug defaults to the `name` field in the frontmatter.
+
 ### Frontmatter fields
 
 Custom `skill.md` files must start with YAML frontmatter.
@@ -85,6 +114,8 @@ metadata:
 ---
 ```
 
+When using the `.mintlify/skills/` directory, `name` and `description` are used in the skills discovery manifest. If `name` is omitted, it defaults to the directory slug.
+
 ## 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.