mew-ton Authoring a skill is as simple as creating a standard Starlight documentation page and adding a few specific fields to its frontmatter.
Defining a Skill Page
By declaring skill: true in the frontmatter of any document page, you mark that page as an AI Skill. The marked page continues to function as a normal documentation page for humans, but it will also be processed as a skill during the build.
The body of the page is distributed directly as the body of the skill. We do not provide a mechanism to filter the body text solely for AI usage—you maintain a single source of truth.
Frontmatter Fields
You must define your skills using the frontmatter of your Markdown or MDX file:
| Field | Required | Description |
|---|---|---|
skill |
Yes | Set to true to mark the page as a skill. |
description |
Yes | A human-readable summary. Used for the visual catalog page and the exported AI skill metadata. |
title |
Recommended | The page title. Used to auto-derive the skill name if not specified. |
skill-name |
No | Explicit mechanical identifier for the skill (1 to 64 characters, lowercase alphanumeric and hyphens only). If not provided, it is derived from the title. |
skill-category |
No | Explicit category path separated by / (e.g., development/frontend). |
skill-license |
No | License name or reference (e.g., MIT). |
skill-compatibility |
No | Environment compatibility details (max 500 characters). |
skill-metadata |
No | Any arbitrary key-value pairs to add to the exported skill metadata. |
skill-allowed-tools |
No | A space-separated verbatim string of pre-approved tool identifiers for the agent. |
(Note: Companion files and schema references are supported via the subfiles field. See the Companion Files chapter for detailed usage.)
Full Frontmatter Example
Here is a full-size example of what a skill page's frontmatter might look like:
---
title: "React Component Guidelines"
description: "Rules and best practices for creating new React components in this project."
skill: true
skill-name: "react-components"
skill-category: "frontend/react"
skill-license: "MIT"
skill-compatibility: "React 18.x with TypeScript"
skill-allowed-tools: "Bash(git:*) Read Write"
skill-metadata:
version: "1.2.0"
author: "Frontend Team"
subfiles:
- "schemas/component.json"
---
Rule Basics
Skill Name Rules
Skill names are machine-readable identifiers and must be unique across the site. Duplicate skill names will result in a build error.
- Allowed characters: Lowercase letters (
a-z), numbers (0-9), and hyphens (-). - Length: 1 to 64 characters.
- Constraints: Cannot begin or end with a hyphen. Cannot contain consecutive hyphens (
--).
Category Resolution
Categories dictate how your skills are grouped in the sidebar and catalog. The category is determined in this order:
skill-categoryinside the frontmatter.- Auto-derived from the file path if
autoCategoryModeis enabled. - Empty string (Uncategorized).
Frontmatter JSON Schema
A machine-readable JSON Schema for all frontmatter fields is available as a companion file: _assets/skill-frontmatter.schema.json.
Use this schema to validate frontmatter values programmatically or to understand the exact constraints (allowed characters, length limits, required fields) for each field without reading prose documentation.