From eea09c6a7e9bdc465022e38512f3279001604427 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Wed, 8 Apr 2026 21:58:28 +0000
Subject: [PATCH 1/2] Document .mintlify/skills/ directory for multi-skill
 support

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

diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..acf6530fe 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -56,13 +56,38 @@ Mintlify generates a `skill.md` file following the [agentskills.io specification
 
 ## Custom `skill.md` files
 
+Write custom skill files 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.
+
+### Single skill file
+
 Add a `skill.md` file to the root of your project to override the automatically generated file. If you delete a custom file, Mintlify generates a new `skill.md` file.
 
-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
+
+Add multiple skill files to the `.mintlify/skills/` directory when your product has distinct capabilities that benefit from separate skill definitions. Each skill lives in its own subdirectory with a `SKILL.md` file:
+
+```
+.mintlify/
+  skills/
+    api-reference/
+      SKILL.md
+    cli-tools/
+      SKILL.md
+    integrations/
+      SKILL.md
+```
+
+Mintlify uses the subdirectory name as the skill's slug (for example, `api-reference`). Each `SKILL.md` file can include frontmatter with `name` and `description` fields to provide additional metadata. During deployment, Mintlify uploads each skill and generates a `skills/index.json` manifest automatically.
+
+When a `.mintlify/skills/` directory with valid skill files is present, Mintlify skips automatic AI skill generation and uses your custom skills instead.
+
+<Note>
+  You can use both approaches simultaneously. A root `skill.md` file is detected alongside `.mintlify/skills/` entries, but the presence of custom skills in `.mintlify/skills/` prevents AI-generated skill replacement.
+</Note>
 
 ### Frontmatter fields
 
-Custom `skill.md` files must start with YAML frontmatter.
+Custom skill files must start with YAML frontmatter.
 
 | Field           | Type   | Description                                                                         |
 | --------------- | ------ | ----------------------------------------------------------------------------------- |

From b7438bebf5d14bba82d3f25a61092deb5ed7d735 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Wed, 8 Apr 2026 22:10:13 +0000
Subject: [PATCH 2/2] Clarify slug sanitization and manifest cleanup behavior

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

diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index acf6530fe..41b4e92e9 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -77,9 +77,9 @@ Add multiple skill files to the `.mintlify/skills/` directory when your product
       SKILL.md
 ```
 
-Mintlify uses the subdirectory name as the skill's slug (for example, `api-reference`). Each `SKILL.md` file can include frontmatter with `name` and `description` fields to provide additional metadata. During deployment, Mintlify uploads each skill and generates a `skills/index.json` manifest automatically.
+Mintlify sanitizes the subdirectory name into a URL-safe slug by lowercasing it and replacing non-alphanumeric characters with hyphens (for example, `API Reference` becomes `api-reference`). Each `SKILL.md` file can include frontmatter with `name` and `description` fields to provide additional metadata. If multiple skill files resolve to the same slug, only the last one is used. During deployment, Mintlify uploads each skill and generates a `skills/index.json` manifest automatically.
 
-When a `.mintlify/skills/` directory with valid skill files is present, Mintlify skips automatic AI skill generation and uses your custom skills instead.
+When a `.mintlify/skills/` directory with valid skill files is present, Mintlify skips automatic AI skill generation and uses your custom skills instead. If you remove the `.mintlify/skills/` directory, Mintlify resumes AI-generated skill creation on the next deployment.
 
 <Note>
   You can use both approaches simultaneously. A root `skill.md` file is detected alongside `.mintlify/skills/` entries, but the presence of custom skills in `.mintlify/skills/` prevents AI-generated skill replacement.