diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index dba1d7b71..badbdf00e 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -8,13 +8,13 @@ Mintlify hosts a `skill.md` file at the root of your project that describes what
 
 The [skill.md specification](https://agentskills.io/specification) is a structured, machine-readable format that makes capabilities, required inputs, and constraints for products explicit so that agents can use them more reliably.
 
-Mintlify automatically generates a `skill.md` file for your project by analyzing your documentation with an agentic loop. This file stays up to date as you make updates to your documentation and requires no maintenance. You can optionally add a custom `skill.md` file to the root of your project that overrides the automatically generated one.
+Mintlify automatically generates a `skill.md` file for your project by analyzing your documentation with an agentic loop. This file stays up to date as you make updates to your documentation and requires no maintenance. You can optionally add a custom `skill.md` file to the root of your project to override the auto-generated one, or define [multiple skills](#multiple-skills) using the `.mintlify/skills/` directory.
 
 <Note>
   Generating or updating a `skill.md` file can take up to 24 hours.
 </Note>
 
-View your `skill.md` by appending `/skill.md` to your documentation site's URL. Mintlify only generates `skill.md` files for documentation sites that are public.
+View your `skill.md` by appending `/skill.md` to your documentation site's URL. When your project has [multiple skills](#multiple-skills), `/skill.md` redirects to `/.well-known/skills/index.json` so agents can discover all available skills. Mintlify only generates `skill.md` files for documentation sites that are public.
 
 <PreviewButton href="https://mintlify.com/docs/skill.md">Open the skill.md for this site.</PreviewButton>
 
@@ -54,15 +54,38 @@ Mintlify generates a `skill.md` file following the [agentskills.io specification
 - **Integration**: Supported tools and services.
 - **Context**: Background on your product's architecture.
 
-## Custom `skill.md` files
+## Custom skill files
 
-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.
+Add custom skill files to override the automatically generated skill. If you delete all custom files, 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.
+Write custom 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
+
+Add a `skill.md` file to the root of your project to override the auto-generated skill. This is the simplest approach when your product has one skill.
+
+### Multiple skills
+
+To define multiple skills, create a `.mintlify/skills/` directory with a subdirectory for each skill:
+
+```
+.mintlify/
+  skills/
+    my-first-skill/
+      SKILL.md
+    my-second-skill/
+      SKILL.md
+```
+
+Each `SKILL.md` file follows the same format as a root `skill.md`. When multiple skills are defined, the `/skill.md` endpoint redirects to `/.well-known/skills/index.json` so agents can discover all available skills.
+
+<Note>
+  If both a root `skill.md` and `.mintlify/skills/` directory exist, the multi-skill directory takes precedence.
+</Note>
 
 ### Frontmatter fields
 
-Custom `skill.md` files must start with YAML frontmatter.
+Custom skill files must start with YAML frontmatter.
 
 | Field           | Type   | Description                                                                         |
 | --------------- | ------ | ----------------------------------------------------------------------------------- |