docs: document .mintlify/skills/ for multiple custom skills

[skeptrunedev]

Summary

• Updates the custom skill.md section to document both single-file and .mintlify/skills/ directory approaches
• Adds directory structure example and explains multi-skill discovery behavior

Test plan

• Verify page renders correctly
• Check internal links

---

Note

Low Risk
Low risk: documentation-only changes plus new example SKILL.md files; no runtime code paths or APIs are modified.

Overview
Documents custom skills via .mintlify/skills/ in ai/skillmd.mdx, clarifying the single root skill.md vs multi-skill directory approach, adding an example directory layout, and describing how /skill.md redirects to discovery endpoints when multiple skills exist.

Adds two example skill definitions under .mintlify/skills/ (mintlify-api and mintlify-docs) to demonstrate the SKILL.md format and content.

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

[mintlify-development]

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

Project	Status	Preview	Updated (UTC)
userauth	🟡 Building	–	Apr 8, 2026, 9:54 PM

[mintlify]

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

Project	Status	Preview	Updated (UTC)
mintlify	🟢 Ready	View Preview	Apr 8, 2026, 9:57 PM

[ethanpalm]

Just a few style/concision nits but lgtm

[ethanpalm]

Suggested change

	Add custom skill files to override the automatically generated `skill.md`. Mintlify supports two approaches: a single file for simple cases and a directory for multiple skills. If you delete all custom skill files, Mintlify generates a new `skill.md` file.
	Add custom skill files to override the automatically generated `skill.md`. Mintlify supports hosting a single skill file and a directory for multiple skills. If you delete all custom skill files, Mintlify generates a new `skill.md` file.

[ethanpalm]

Suggested change

	Add multiple skill files to the `.mintlify/skills/` directory in your project. Each skill lives in its own subdirectory with a `SKILL.md` file:
	Add multiple skill files to the `.mintlify/skills/` directory in your project. Each skill must be in its own subdirectory with a `SKILL.md` file:

[ethanpalm]

Suggested change

	When you have multiple skills, the `/skill.md` endpoint redirects to the `/.well-known/skills/index.json` discovery endpoint, which lists all available skills. Each skill is individually accessible through the discovery endpoints.
	When you have multiple skills, the `/skill.md` endpoint redirects to the `/.well-known/skills/index.json` discovery endpoint, which lists all available skills. The discovery endpoints make each skill individually accessible.

[ethanpalm]

Suggested change

	You can use both approaches together. A root `skill.md` file and
	`.mintlify/skills/` entries are both included in the discovery index.
	You can use both approaches together with a root `skill.md` file and `.mintlify/skills/` directory. The discovery index includes all skills.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 32bb7e6. Configure here.}