From 5d16d7243595e51460e2a493aec78a7fe9b76e89 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 16:30:44 -0600 Subject: [PATCH] Move frontmatter field table above examples in specification doc Place the field constraints table immediately after the `Frontmatter` heading so readers see the reference before the examples. Also remove "(required)" from the heading, wrap examples in a ``, and relabel "With optional fields:" to "Example with optional fields:". Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 32a9e57..0e8d05b 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -21,7 +21,19 @@ skill-name/ The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. -### Frontmatter (required) +### Frontmatter + +| Field | Required | Constraints | +|-------|----------|-------------| +| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | +| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. | +| `license` | No | License name or reference to a bundled license file. | +| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). | +| `metadata` | No | Arbitrary key-value mapping for additional metadata. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) | + + +**Minimal example:** ```markdown SKILL.md --- @@ -30,7 +42,7 @@ description: A description of what this skill does and when to use it. --- ``` -**With optional fields:** +**Example with optional fields:** ```markdown SKILL.md --- @@ -42,15 +54,7 @@ metadata: version: "1.0" --- ``` - -| Field | Required | Constraints | -|-------|----------|-------------| -| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | -| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. | -| `license` | No | License name or reference to a bundled license file. | -| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). | -| `metadata` | No | Arbitrary key-value mapping for additional metadata. | -| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) | + #### `name` field