Document YAML frontmatter fields for custom skill.md files #2847
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
![tembo[bot]](https://avatars.githubusercontent.com/in/1223475?s=60&v=4){kind=small}
ai/skillmd.mdx
Outdated
| | `description` | string | A brief description of what your skill does. | | ||
| | `license` | string | The license for your skill (e.g., `MIT`, `Apache-2.0`). | | ||
| | `compatibility` | string | Requirements or compatibility notes (e.g., runtime dependencies). | | ||
| | `metadata` | object | Additional metadata as key-value pairs (e.g., `author`, `version`). | |
Contributor
There was a problem hiding this comment.
Spec defines metadata as a string-to-string map, so calling that out here helps prevent nested objects.
Suggested change
| | `metadata` | object | Additional metadata as key-value pairs (e.g., `author`, `version`). | | |
| | `metadata` | object | Additional metadata as string key-value pairs (e.g., `author`, `version`). | |
ai/skillmd.mdx
Outdated
| | `license` | string | The license for your skill (e.g., `MIT`, `Apache-2.0`). | | ||
| | `compatibility` | string | Requirements or compatibility notes (e.g., runtime dependencies). | | ||
| | `metadata` | object | Additional metadata as key-value pairs (e.g., `author`, `version`). | | ||
| | `allowed-tools` | string | Tools that agents are allowed to use with this skill. | |
Contributor
There was a problem hiding this comment.
Might be worth matching the spec’s wording/format for this field (space-delimited + experimental).
Suggested change
| | `allowed-tools` | string | Tools that agents are allowed to use with this skill. | | |
| | `allowed-tools` | string | Space-delimited list of pre-approved tools the skill may use (experimental). | |
Co-authored-by: tembo[bot] <208362400+tembo[bot]@users.noreply.github.com>
- Clarify metadata field accepts string key-value pairs to prevent nested objects - Update allowed-tools description to match spec wording and mention experimental status
mintlify-development bot
added a commit
that referenced
this pull request
Jan 24, 2026
- Add comprehensive frontmatter documentation with all supported fields - Clarify metadata as string key-value pairs (addresses review feedback) - Specify allowed-tools as space-delimited experimental feature (addresses review feedback) - Use mintlify-docs name to avoid collisions (addresses review feedback) - Make frontmatter requirement explicit, not optional Addresses all feedback from PR #2847 review comments.
4 tasks
cdxker
added a commit
that referenced
this pull request
Jan 24, 2026
* Document YAML frontmatter fields for custom skill.md files - Add comprehensive frontmatter documentation with all supported fields - Clarify metadata as string key-value pairs (addresses review feedback) - Specify allowed-tools as space-delimited experimental feature (addresses review feedback) - Use mintlify-docs name to avoid collisions (addresses review feedback) - Make frontmatter requirement explicit, not optional Addresses all feedback from PR #2847 review comments. * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor --------- Co-authored-by: mintlify-development[bot] <109878554+mintlify-development[bot]@users.noreply.github.com> Co-authored-by: cdxker <32852291+cdxker@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Added documentation for YAML frontmatter support in custom skill.md files, including all supported fields and a complete example.
Created by Mintlify agent
Note
Adds documentation for custom
skill.mdfrontmatter and example; minor metadata tweak in rootskill.md.skill.mdand provides a complete example inai/skillmd.mdxskill.mdfrontmatternamefrommintlify-docstomintlifyWritten by Cursor Bugbot for commit 54a8050. This will update automatically on new commits. Configure here.