diff --git a/ai/skillmd.mdx b/ai/skillmd.mdx
index e918ac7fb..4e65659dd 100644
--- a/ai/skillmd.mdx
+++ b/ai/skillmd.mdx
@@ -17,16 +17,16 @@ View your `skill.md` by appending `/skill.md` to your documentation site's URL.
 <PreviewButton href="https://mintlify.com/docs/skill.md">Open the skill.md for this site.</PreviewButton>
 
 <Tip>
-Both `llms.txt` and `skill.md` files help agents work with your documentation, but they serve different purposes.
+  Both `llms.txt` and `skill.md` files help agents work with your documentation, but they serve different purposes.
 
-- `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information.
-- `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply.
+  - `llms.txt` is a directory. It lists all your documentation pages with descriptions so agents know where to find information.
+  - `skill.md` is a capability summary. It tells agents what they can accomplish with your product, what inputs they need, and what constraints apply.
 </Tip>
 
 ## 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.
+  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,30 @@ 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 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: mintlify-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"
+---
+```
\ No newline at end of file
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.