# Starlight Skills Authoring

> Provides rules and frontmatter schema for writing AI skills. Use this when you need to know how to add `skill: true`, configure skill metadata, or understand the naming constraints. Do not use this for plugin configuration options or deployment instructions.

- Skill: `mew-ton/starlight-skills-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mew-ton/starlight-skills-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mew-ton/starlight-skills-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mew-ton (https://skillmd.com/u/mew-ton)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mew-ton/starlight-skills-authoring

---


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:

```yaml
---
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:
1. `skill-category` inside the frontmatter.
2. Auto-derived from the file path if `autoCategoryMode` is enabled.
3. 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.