Document YAML frontmatter fields for custom skill.md files

ai/skillmd.mdx

@@ -26,7 +26,7 @@
 ## Use `skill.md` files with agents
 
 <Note>
 If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/skill.md` and `/.well-known/skills/*` paths (with caching disabled) to your Mintlify subdomain.
 </Note>
 
 Agents can process your `skill.md` with the [skills CLI](https://www.npmjs.com/package/skills).
@@ -57,3 +57,36 @@
 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 must start with YAML frontmatter. 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 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`
+
+```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.
+```

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.