skill-manager/references/specification.md

# Agent Skills — Full Specification Reference

Source: https://agentskills.io/specification

## Directory structure

```
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories
```

## SKILL.md format

The file must contain YAML frontmatter followed by Markdown content.

---

## Frontmatter fields

| Field | Required | Constraints |
|-------|----------|-------------|
| `name` | Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match the parent directory name. |
| `description` | Yes | Max 1024 chars. 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 chars. Indicates environment requirements (product, packages, network, etc.). |
| `metadata` | No | Arbitrary key-value mapping (string → string) for additional metadata. |
| `allowed-tools` | No | Space-separated string of pre-approved tools. (Experimental) |

---

## `name` field

Rules:
- 1–64 characters
- Only: lowercase letters `a-z`, digits `0-9`, hyphens `-`
- Must not start or end with a hyphen
- Must not contain consecutive hyphens `--`
- **Must match the parent directory name exactly**

Valid examples:
```yaml
name: pdf-processing
name: data-analysis
name: code-review
```

Invalid examples:
```yaml
name: PDF-Processing    # uppercase not allowed
name: -pdf              # cannot start with hyphen
name: pdf--processing   # consecutive hyphens not allowed
```

---

## `description` field

Rules:
- 1–1024 characters
- Should describe both **what** the skill does and **when** to use it
- Include specific keywords that help agents identify relevant tasks

**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:**
```yaml
description: Helps with PDFs.
```

Principles for effective descriptions:
- Use imperative phrasing: "Use this skill when…" not "This skill does…"
- Focus on user intent, not internal mechanics
- Be explicit about indirect triggers: "even if they don't explicitly mention 'CSV'"
- Err on the side of being specific and slightly pushy
- Keep it concise — a few sentences to a short paragraph

---

## `license` field

- Specifies the license applied to the skill
- Keep it short — either the name of a license or the name of a bundled license file

Example:
```yaml
license: Apache-2.0
license: Proprietary. LICENSE.txt has complete terms.
```

---

## `compatibility` field

- 1–500 characters if provided
- Only include if your skill has specific environment requirements
- Can indicate: intended product, required system packages, network access

Examples:
```yaml
compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv
```

Most skills do not need this field.

---

## `metadata` field

- A map from string keys to string values
- Use for storing additional properties not defined by the spec
- Make key names reasonably unique to avoid conflicts

Example:
```yaml
metadata:
  author: example-org
  version: "1.0"
```

---

## `allowed-tools` field

- A space-separated string of tools pre-approved to run
- Experimental — support varies between agent implementations

Example:
```yaml
allowed-tools: Bash(git:*) Bash(jq:*) Read
```

---

## Body content

The Markdown body after the frontmatter contains the skill instructions.

Recommended sections:
- Step-by-step instructions
- Examples of inputs and outputs
- Common edge cases

The agent loads the entire body when the skill activates. Keep it under 500 lines. Move longer reference material to separate files.

---

## Progressive disclosure

Skills are loaded in three stages:

| Stage | Content | Size |
|-------|---------|------|
| Startup | `name` + `description` only | ~100 tokens |
| Activation | Full `SKILL.md` body | < 5,000 tokens recommended |
| On demand | Files in `scripts/`, `references/`, `assets/` | As needed |

Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files and tell the agent *when* to load them — not just "see references/ for details."

---

## File references

Use relative paths from the skill root:

```markdown
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
```

Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.

---

## Optional directories

### `scripts/`

Contains executable code agents can run. Scripts should:
- Be self-contained or clearly document dependencies
- Include helpful error messages
- Handle edge cases gracefully

Supported languages depend on the agent implementation. Common: Python, Bash, JavaScript.

### `references/`

Contains documentation agents read on demand:
- `REFERENCE.md` — Detailed technical reference
- `FORMS.md` — Form templates or structured data formats
- Domain-specific files (`finance.md`, `legal.md`, etc.)

Keep individual reference files focused. Agents load these on demand — smaller files = less context used.

### `assets/`

Contains static resources:
- Templates (document, configuration)
- Images (diagrams, examples)
- Data files (lookup tables, schemas)