diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..41b4e92e9 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 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. 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.
+</Note>
 
 ### Frontmatter fields
 
-Custom `skill.md` files must start with YAML frontmatter.
+Custom skill files must start with YAML frontmatter.
 
 | Field           | Type   | Description                                                                         |
 | --------------- | ------ | ----------------------------------------------------------------------------------- |