Document YAML frontmatter fields for custom skill.md files

[mintlify-development]

Summary

Addresses all review comments from PR #2847 by documenting YAML frontmatter fields for custom skill.md files.

Changes Made

• Added comprehensive frontmatter documentation to ai/skillmd.mdx with table of all supported fields
• Clarified field descriptions based on review feedback:
  • metadata: Specified as "string key-value pairs" to prevent nested objects
  • allowed-tools: Described as "space-delimited" and marked as "experimental" to match spec
• Made frontmatter requirement explicit: Changed from optional language to "Custom skill.md files must start with YAML frontmatter"
• Updated example to use mintlify-docs: Avoids naming collisions as suggested in review

Review Comments Addressed

✅ Comment 1: Changed "Custom skill.md files can start with YAML frontmatter" to "Custom skill.md files must start with YAML frontmatter"
✅ Comment 2: Updated metadata description to "Additional metadata as string key-value pairs"
✅ Comment 3: Updated allowed-tools description to "Space-delimited list of pre-approved tools the skill may use (experimental)"
✅ Comment 4: Used mintlify-docs instead of mintlify in example to avoid collisions

Test Plan

• Verify documentation renders correctly with mint dev
• Check that frontmatter table formatting displays properly
• Ensure code example syntax highlighting works
• Run vale to check style compliance

---

This PR supersedes #2847 with all review feedback addressed.

---

Note

Adds concise guidance for creating custom skill.md files and tidies callout formatting.

• Docs: New "Frontmatter fields" section in ai/skillmd.mdx with a table of supported keys and an example YAML block
• Formatting: Fixes duplicated/misformatted bullets inside Tip and Note callouts
• Sample file: Updates root skill.md frontmatter name from mintlify-docs to mintlify

^{Written by Cursor Bugbot for commit d69b539. This will update automatically on new commits. Configure here.}