Document multiple skill files support

[mintlify]

Summary

• Documents the new .mintlify/skills/ directory for defining multiple skill files per project
• Explains how /skill.md redirects to the discovery index when multiple skills are defined
• Updates discovery endpoint descriptions to reference multi-skill behavior

What shipped

Mintlify now supports multiple skill files per project. Users can place separate skill.md files in subdirectories under .mintlify/skills/ (e.g., .mintlify/skills/api-management/skill.md). Each skill appears as its own entry in the /.well-known/skills/ and /.well-known/agent-skills/ discovery endpoints. When multiple skills exist, /skill.md redirects to the discovery index instead of returning a single file.

---

Note

Low Risk
Documentation-only updates describing new multi-skill layout and discovery/redirect behavior; no runtime or security-sensitive code changes.

Overview
Updates ai/skillmd.mdx to document multiple skill.md files per project via .mintlify/skills/{slug}/skill.md, including requirements for per-skill frontmatter and how slugs are derived.

Clarifies discovery behavior when multiple skills exist: /skill.md redirects to /.well-known/skills/index.json, and both /.well-known/skills/index.json and /.well-known/agent-skills/index.json list each skill as a separate entry, with individual skill fetch paths.

^{Reviewed by Cursor Bugbot for commit 4956abe. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mintlify	🟢 Ready	View Preview	Apr 9, 2026, 2:00 AM