From 3736fdb995af251d30eca9623f08874c41122e37 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 15:44:40 -0600 Subject: [PATCH 1/8] Format directory and file names as inline code in specification doc Wrap `SKILL.md`, `scripts/`, `references/`, and `assets/` headings in backticks for consistency with the rest of the document, which already uses inline code formatting for these names in body text. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 34d3a9a..997f4a5 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -18,7 +18,7 @@ skill-name/ You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill. -## SKILL.md format +## `SKILL.md` format The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. @@ -169,7 +169,7 @@ Note that the agent will load this entire file once it's decided to activate a s ## Optional directories -### scripts/ +### `scripts/` Contains executable code that agents can run. Scripts should: - Be self-contained or clearly document dependencies @@ -178,7 +178,7 @@ Contains executable code that agents can run. Scripts should: Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript. -### references/ +### `references/` Contains additional documentation that agents can read when needed: - `REFERENCE.md` - Detailed technical reference @@ -187,7 +187,7 @@ Contains additional documentation that agents can read when needed: Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context. -### assets/ +### `assets/` Contains static resources: - Templates (document templates, configuration templates) From 08d1d688c1500b848881d772e8db84d846dc2725 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 15:47:57 -0600 Subject: [PATCH 2/8] Improve clarity of `name` field constraints in specification doc Place inline code examples next to the terms they describe (e.g., "`a-z`" next to "alphanumeric characters") rather than grouping them at the end. Also add the word "hyphen" before the code-formatted `-` for readability. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 997f4a5..3e816e8 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -57,8 +57,8 @@ metadata: The required `name` field: - Must be 1-64 characters -- May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`) -- Must not start or end with `-` +- May only contain unicode lowercase alphanumeric characters (`a-z`) and hyphens (`-`) +- Must not start or end with a hyphen (`-`) - Must not contain consecutive hyphens (`--`) - Must match the parent directory name From cbc354c2ffb5cf7e682455a9118180ccd5f27c2a Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 16:00:09 -0600 Subject: [PATCH 3/8] Expand directory tree in specification doc Show optional directories (`scripts/`, `references/`, `assets/`) directly in the directory tree with inline annotations, replacing the separate `` block. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 3e816e8..f10f8be 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -11,13 +11,12 @@ A skill is a directory containing at minimum a `SKILL.md` file: ``` skill-name/ -└── SKILL.md # Required +├── SKILL.md # Required: metadata + instructions +├── scripts/ # Optional: executable code +├── references/ # Optional: documentation +└── assets/ # Optional: templates, resources ``` - -You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill. - - ## `SKILL.md` format The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. From a9d33af2d5e04e2e4b87429d5b17cc1180cc4d49 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 16:16:58 -0600 Subject: [PATCH 4/8] Wrap examples in `` components in specification doc The `####` field headings didn't stand out enough amongst all the code blocks, making the page hard to scan. Wrapping each field's examples in a `` draws a border around them and adds padding, so each subsection looks more contained instead of bleeding into the next. Also bolds the example labels within each card. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index f10f8be..6286443 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -30,7 +30,7 @@ description: A description of what this skill does and when to use it. --- ``` -With optional fields: +**With optional fields:** ```yaml --- @@ -61,7 +61,8 @@ The required `name` field: - Must not contain consecutive hyphens (`--`) - Must match the parent directory name -Valid examples: + +**Valid examples:** ```yaml name: pdf-processing ``` @@ -72,7 +73,7 @@ name: data-analysis name: code-review ``` -Invalid examples: +**Invalid examples:** ```yaml name: PDF-Processing # uppercase not allowed ``` @@ -82,6 +83,7 @@ name: -pdf # cannot start with hyphen ```yaml name: pdf--processing # consecutive hyphens not allowed ``` + #### `description` field @@ -90,15 +92,17 @@ The required `description` field: - Should describe both what the skill does and when to use it - Should include specific keywords that help agents identify relevant tasks -Good example: + +**Good example:** ```yaml description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. ``` -Poor example: +**Poor example:** ```yaml description: Helps with PDFs. ``` + #### `license` field @@ -106,10 +110,12 @@ The optional `license` field: - Specifies the license applied to the skill - We recommend keeping it short (either the name of a license or the name of a bundled license file) -Example: + +**Example:** ```yaml license: Proprietary. LICENSE.txt has complete terms ``` + #### `compatibility` field @@ -118,13 +124,15 @@ The optional `compatibility` field: - Should only be included if your skill has specific environment requirements - Can indicate intended product, required system packages, network access needs, etc. -Examples: + +**Examples:** ```yaml compatibility: Designed for Claude Code (or similar products) ``` ```yaml compatibility: Requires git, docker, jq, and access to the internet ``` + Most skills do not need the `compatibility` field. @@ -137,12 +145,14 @@ The optional `metadata` field: - Clients can use this to store additional properties not defined by the Agent Skills spec - We recommend making your key names reasonably unique to avoid accidental conflicts -Example: + +**Example:** ```yaml metadata: author: example-org version: "1.0" ``` + #### `allowed-tools` field @@ -150,10 +160,12 @@ The optional `allowed-tools` field: - A space-delimited list of tools that are pre-approved to run - Experimental. Support for this field may vary between agent implementations -Example: + +**Example:** ```yaml allowed-tools: Bash(git:*) Bash(jq:*) Read ``` + ### Body content From 7a05447ecbe93880fcf5cc9bacd94d34ae34b27b Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 16:23:52 -0600 Subject: [PATCH 5/8] Add `SKILL.md` filename annotations to code blocks in specification doc The fenced code blocks showing `SKILL.md` content were labeled as `yaml` or plain `markdown`. Changing them to `markdown SKILL.md` adds a filename hint and more accurately reflects that they contain full `SKILL.md` snippets (including `---` frontmatter delimiters), not just raw YAML. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 6286443..32a9e57 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -23,7 +23,7 @@ The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. ### Frontmatter (required) -```yaml +```markdown SKILL.md --- name: skill-name description: A description of what this skill does and when to use it. @@ -32,7 +32,7 @@ description: A description of what this skill does and when to use it. **With optional fields:** -```yaml +```markdown SKILL.md --- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. @@ -219,7 +219,7 @@ Keep your main `SKILL.md` under 500 lines. Move detailed reference material to s When referencing other files in your skill, use relative paths from the skill root: -```markdown +```markdown SKILL.md See [the reference guide](references/REFERENCE.md) for details. Run the extraction script: From 5d16d7243595e51460e2a493aec78a7fe9b76e89 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Fri, 6 Mar 2026 16:30:44 -0600 Subject: [PATCH 6/8] 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 From fe28cce09e069778aee1ef6ccce6bc079f94ef33 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Mon, 9 Mar 2026 09:30:26 -0500 Subject: [PATCH 7/8] Add `...` entry to directory tree in specification doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The directory listing is not exhaustive — skill authors can include other files and subdirectories beyond those shown. Adding a `...` entry makes this explicit. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index 0e8d05b..e2cc97a 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -7,14 +7,15 @@ This document defines the Agent Skills format. ## Directory structure -A skill is a directory containing at minimum a `SKILL.md` file: +A skill is a directory containing, at minimum, a `SKILL.md` file: ``` skill-name/ ├── SKILL.md # Required: metadata + instructions ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation -└── assets/ # Optional: templates, resources +├── assets/ # Optional: templates, resources +└── ... # Any additional files or directories ``` ## `SKILL.md` format From 8c82ac2a8d91d0ce3fae7a790e4613bccdb8fcb1 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Mon, 9 Mar 2026 09:41:26 -0500 Subject: [PATCH 8/8] Remove redundant intro sentence from specification doc The frontmatter `description` already serves as the page subtitle in Mintlify, so the "This document defines the Agent Skills format." line was just restating it. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/specification.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/specification.mdx b/docs/specification.mdx index e2cc97a..6fc8db8 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -3,8 +3,6 @@ title: "Specification" description: "The complete format specification for Agent Skills." --- -This document defines the Agent Skills format. - ## Directory structure A skill is a directory containing, at minimum, a `SKILL.md` file: