Document multi-skill support

ai/skillmd.mdx

@@ -43,7 +43,7 @@
   Teach your users how to use `skill.md` files with agents so that they have better results using your product with their AI tools.
 </Tip>
 
 ## `skill.md` structure
 
 Mintlify generates a `skill.md` file following the [agentskills.io specification](https://agentskills.io/specification). The generated file includes:
 
@@ -60,6 +60,35 @@
 
 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 @@
 ---
 ```
 
+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.