From d623a0c724f0b543f97aab13fe9799ecd1b6ff98 Mon Sep 17 00:00:00 2001 From: cdxker <32852291+cdxker@users.noreply.github.com> Date: Fri, 23 Jan 2026 21:51:20 -0800 Subject: [PATCH 1/4] Update ai/skillmd.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- ai/skillmd.mdx | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index e918ac7fb..d14c3280b 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -57,3 +57,36 @@ Mintlify generates a `skill.md` file following the [agentskills.io specification Add a `skill.md` file to the root of your project to override the automatically generated file. If you delete a custom file, Mintlify generates a new `skill.md` file. Write a custom file when you want precise control over how agents interact with your product. Follow the [agentskills.io specification](https://agentskills.io/specification) to ensure compatibility with agent tooling. + +### Frontmatter fields + +Custom `skill.md` files support YAML frontmatter to provide metadata about your skill. The following fields are supported: + +| Field | Type | Description | +| --- | --- | --- | +| `name` | string | The name of your skill. | +| `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`). | +| `allowed-tools` | string | Tools that agents are allowed to use with this skill. | + +### Example custom `skill.md` + +```md +--- +name: shell-docs +description: Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references. +license: MIT +compatibility: Requires Node.js for CLI. Works with any Git-based workflow. +metadata: + author: mintlify + version: "1.0" +--- + +# Mintlify best practices + +**Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.** + +Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components. +``` From b9d62805f3f09adeb3e9bdfe2f6e5d44c8106e97 Mon Sep 17 00:00:00 2001 From: cdxker <32852291+cdxker@users.noreply.github.com> Date: Fri, 23 Jan 2026 21:59:32 -0800 Subject: [PATCH 2/4] Documentation edits made through Mintlify web editor --- skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skill.md b/skill.md index 4c22446f3..1c40e4a8c 100644 --- a/skill.md +++ b/skill.md @@ -1,5 +1,5 @@ --- -name: mintlify-docs +name: mintlify description: Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references. license: MIT compatibility: Requires Node.js for CLI. Works with any Git-based workflow. From 05f6bfff032981eedee867c171eb8cc810d02473 Mon Sep 17 00:00:00 2001 From: cdxker <32852291+cdxker@users.noreply.github.com> Date: Fri, 23 Jan 2026 22:06:33 -0800 Subject: [PATCH 3/4] Update ai/skillmd.mdx Co-authored-by: tembo[bot] <208362400+tembo[bot]@users.noreply.github.com> --- ai/skillmd.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index d14c3280b..2ee9b10d5 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -60,7 +60,7 @@ Write a custom file when you want precise control over how agents interact with ### Frontmatter fields -Custom `skill.md` files support YAML frontmatter to provide metadata about your skill. The following fields are supported: +Custom `skill.md` files must start with YAML frontmatter. The following fields are supported: | Field | Type | Description | | --- | --- | --- | From 54a80507a9a98731eb43824bb8347c04e74c14b9 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 24 Jan 2026 07:03:06 +0000 Subject: [PATCH 4/4] Address review comments for skill.md frontmatter documentation - Clarify metadata field accepts string key-value pairs to prevent nested objects - Update allowed-tools description to match spec wording and mention experimental status --- ai/skillmd.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx index 2ee9b10d5..01e49e513 100644 --- a/ai/skillmd.mdx +++ b/ai/skillmd.mdx @@ -68,8 +68,8 @@ Custom `skill.md` files must start with YAML frontmatter. The following fields a | `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`). | -| `allowed-tools` | string | Tools that agents are allowed to use with this skill. | +| `metadata` | object | Additional metadata as string key-value pairs (e.g., `author`, `version`). | +| `allowed-tools` | string | Space-delimited list of pre-approved tools the skill may use (experimental). | ### Example custom `skill.md` @@ -89,4 +89,4 @@ metadata: **Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.** Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components. -``` +``` \ No newline at end of file