mirror of
https://github.com/agentskills/agentskills.git
synced 2026-06-18 15:54:06 +08:00
Merge pull request #216 from jonathanhefner/clean-up-specification-doc
Visually clean up the specification page
This commit is contained in:
Jonathan Hefner
+58
-44
@@ -3,46 +3,24 @@ 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:
|
||||
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
|
||||
└── ... # Any additional files or directories
|
||||
```
|
||||
|
||||
<Tip>
|
||||
You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill.
|
||||
</Tip>
|
||||
|
||||
## SKILL.md format
|
||||
## `SKILL.md` format
|
||||
|
||||
The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
|
||||
|
||||
### Frontmatter (required)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: A description of what this skill does and when to use it.
|
||||
---
|
||||
```
|
||||
|
||||
With optional fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: example-org
|
||||
version: "1.0"
|
||||
---
|
||||
```
|
||||
### Frontmatter
|
||||
|
||||
| Field | Required | Constraints |
|
||||
|-------|----------|-------------|
|
||||
@@ -53,16 +31,41 @@ metadata:
|
||||
| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
|
||||
| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) |
|
||||
|
||||
<Card>
|
||||
**Minimal example:**
|
||||
|
||||
```markdown SKILL.md
|
||||
---
|
||||
name: skill-name
|
||||
description: A description of what this skill does and when to use it.
|
||||
---
|
||||
```
|
||||
|
||||
**Example with optional fields:**
|
||||
|
||||
```markdown SKILL.md
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: example-org
|
||||
version: "1.0"
|
||||
---
|
||||
```
|
||||
</Card>
|
||||
|
||||
#### `name` field
|
||||
|
||||
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
|
||||
|
||||
Valid examples:
|
||||
<Card>
|
||||
**Valid examples:**
|
||||
```yaml
|
||||
name: pdf-processing
|
||||
```
|
||||
@@ -73,7 +76,7 @@ name: data-analysis
|
||||
name: code-review
|
||||
```
|
||||
|
||||
Invalid examples:
|
||||
**Invalid examples:**
|
||||
```yaml
|
||||
name: PDF-Processing # uppercase not allowed
|
||||
```
|
||||
@@ -83,6 +86,7 @@ name: -pdf # cannot start with hyphen
|
||||
```yaml
|
||||
name: pdf--processing # consecutive hyphens not allowed
|
||||
```
|
||||
</Card>
|
||||
|
||||
#### `description` field
|
||||
|
||||
@@ -91,15 +95,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:
|
||||
<Card>
|
||||
**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.
|
||||
```
|
||||
</Card>
|
||||
|
||||
#### `license` field
|
||||
|
||||
@@ -107,10 +113,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:
|
||||
<Card>
|
||||
**Example:**
|
||||
```yaml
|
||||
license: Proprietary. LICENSE.txt has complete terms
|
||||
```
|
||||
</Card>
|
||||
|
||||
#### `compatibility` field
|
||||
|
||||
@@ -119,13 +127,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:
|
||||
<Card>
|
||||
**Examples:**
|
||||
```yaml
|
||||
compatibility: Designed for Claude Code (or similar products)
|
||||
```
|
||||
```yaml
|
||||
compatibility: Requires git, docker, jq, and access to the internet
|
||||
```
|
||||
</Card>
|
||||
|
||||
<Note>
|
||||
Most skills do not need the `compatibility` field.
|
||||
@@ -138,12 +148,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:
|
||||
<Card>
|
||||
**Example:**
|
||||
```yaml
|
||||
metadata:
|
||||
author: example-org
|
||||
version: "1.0"
|
||||
```
|
||||
</Card>
|
||||
|
||||
#### `allowed-tools` field
|
||||
|
||||
@@ -151,10 +163,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:
|
||||
<Card>
|
||||
**Example:**
|
||||
```yaml
|
||||
allowed-tools: Bash(git:*) Bash(jq:*) Read
|
||||
```
|
||||
</Card>
|
||||
|
||||
### Body content
|
||||
|
||||
@@ -169,7 +183,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 +192,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 +201,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)
|
||||
@@ -208,7 +222,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:
|
||||
|
||||
Reference in New Issue
Block a user