From 426af21b102a07df4861224df9a28ad37fb276db Mon Sep 17 00:00:00 2001 From: skeptrune Date: Wed, 8 Apr 2026 14:53:33 -0700 Subject: [PATCH 1/4] docs: document .mintlify/skills/ directory for multiple custom skills --- ai/skillmd.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index d8ab10e6f..89a3b8667 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -21,9 +21,9 @@ View your `skill.md` by appending `/skill.md` to your documentation site's URL. Both `llms.txt` and `skill.md` files help agents work with your documentation, but they serve different purposes. - - `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information. - - `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply. - +- `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information. +- `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply. + ## Use `skill.md` files with agents From d9fbfa0c4cb22816c1b3a4b8f5d47b0e685c190e Mon Sep 17 00:00:00 2001 From: skeptrune Date: Wed, 8 Apr 2026 20:19:45 -0700 Subject: [PATCH 2/4] fix: indent list items inside Tip component to fix MDX parse error --- ai/skillmd.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index 89a3b8667..d8ab10e6f 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -21,9 +21,9 @@ View your `skill.md` by appending `/skill.md` to your documentation site's URL. Both `llms.txt` and `skill.md` files help agents work with your documentation, but they serve different purposes. -- `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information. -- `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply. - + - `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information. + - `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply. + ## Use `skill.md` files with agents From eb32078359aafb886d62c273aedad35614a86f10 Mon Sep 17 00:00:00 2001 From: skeptrune Date: Thu, 9 Apr 2026 12:23:55 -0700 Subject: [PATCH 3/4] Test symlinked .mintlify/skills pointing to skills/ directory --- .mintlify/skills | 1 + {.mintlify/skills => skills}/mintlify-api/SKILL.md | 0 {.mintlify/skills => skills}/mintlify-docs/SKILL.md | 0 3 files changed, 1 insertion(+) create mode 120000 .mintlify/skills rename {.mintlify/skills => skills}/mintlify-api/SKILL.md (100%) rename {.mintlify/skills => skills}/mintlify-docs/SKILL.md (100%) diff --git a/.mintlify/skills b/.mintlify/skills new file mode 120000 index 000000000..42c5394a1 --- /dev/null +++ b/.mintlify/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/.mintlify/skills/mintlify-api/SKILL.md b/skills/mintlify-api/SKILL.md similarity index 100% rename from .mintlify/skills/mintlify-api/SKILL.md rename to skills/mintlify-api/SKILL.md diff --git a/.mintlify/skills/mintlify-docs/SKILL.md b/skills/mintlify-docs/SKILL.md similarity index 100% rename from .mintlify/skills/mintlify-docs/SKILL.md rename to skills/mintlify-docs/SKILL.md From db129375f006b2638b2b5332d704cb2b0947986b Mon Sep 17 00:00:00 2001 From: skeptrune Date: Thu, 9 Apr 2026 19:14:33 -0700 Subject: [PATCH 4/4] docs: document symlink support for .mintlify/skills directory --- ai/skillmd.mdx | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index d8ab10e6f..664e0a59a 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -84,6 +84,29 @@ When you have multiple skills, the `/skill.md` endpoint redirects to the `/.well You can use both approaches together with a root `skill.md` file and `.mintlify/skills/` directory. The discovery index includes all skills. +### Use symlinks to avoid duplication + +If your skill files live elsewhere in your repository (for example, in a `plugins/` or `skills/` directory), you can symlink `.mintlify/skills` to that location instead of duplicating files: + +```bash +# Skills live in a top-level skills/ directory +ln -s ../skills .mintlify/skills +``` + +``` +project/ + skills/ + payments/ + SKILL.md + analytics/ + SKILL.md + .mintlify/ + skills -> ../skills + docs.json +``` + +Mintlify resolves symlinks during deployment, so the skill files are discovered and served as if they were directly inside `.mintlify/skills/`. This works with both directory symlinks and individual skill symlinks. + ### Frontmatter fields Custom `skill.md` files must start with YAML frontmatter.