agentskills-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

## Agent Skills Specification

A **skill** is a directory containing a `SKILL.md` file that teaches an AI agent how to perform a task or use a domain of knowledge. This specification defines the required format.

### Directory Structure

```
<skill-name>/
├── SKILL.md          # Required — frontmatter + body
├── scripts/          # Optional — executable scripts
├── references/       # Optional — reference documents
└── assets/           # Optional — binary assets
```

### SKILL.md Format

```
---
name: <kebab-case-name>
description: <human-readable description>
license: <SPDX license identifier>
compatibility: <optional version or platform constraint>
allowed-tools: <space-separated kebab-case tool IDs (e.g. file-read web-fetch bash)>
metadata:
  key: value
---

<markdown body — instructions for the agent>
```

### Frontmatter Fields

| Field           | Required | Constraints                                                                              |
| --------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name`          | Yes      | kebab-case (lowercase letters, digits, hyphens); max 64 chars; must match directory name |
| `description`   | Yes      | Non-empty; max 1024 chars                                                                |
| `license`       | No       | SPDX identifier (e.g. MIT, Apache-2.0)                                                   |
| `compatibility` | No       | Max 500 chars; version constraint or platform note                                       |
| `allowed-tools` | No       | Space-separated kebab-case tool IDs (e.g. `file-read web-fetch bash`)                    |
| `metadata`      | No       | Arbitrary key/value map for custom attributes                                            |

### Body

- Written in Markdown
- Contains instructions the agent should follow when this skill is active
- Use `##` headings to organize sections
- Include examples, constraints, and step-by-step guidance

### Validation Rules

1. `name` must be kebab-case: only lowercase ASCII letters, digits, and non-leading/trailing/consecutive hyphens
2. `name` must match the directory name exactly
3. `description` must be non-empty and ≤ 1024 characters
4. `compatibility` if present must be ≤ 500 characters
5. The SKILL.md must have valid YAML frontmatter delimited by `---`

### Example

```
---
name: git-commit
description: Teaches the agent to write semantic git commit messages following the Conventional Commits specification.
license: MIT
allowed-tools: bash file-read
---

## Conventional Commits

Always format commit messages as: `<type>(<scope>): <description>`

Types: feat, fix, chore, docs, refactor, test, perf

### Rules
- Subject line max 72 characters
- Use imperative mood ("add feature" not "added feature")
- Reference issues with (#123) at end of subject
```

### When Generating a SKILL.md

1. Choose a `name` that is kebab-case and describes the skill's purpose
2. Write a `description` that is one clear sentence (≤ 1024 chars)
3. Set `license: MIT` unless the user specifies otherwise
4. List any tools the skill requires in `allowed-tools`
5. Write a body with `##` sections: purpose, rules/constraints, examples
6. Keep instructions actionable and specific — avoid vague language
7. Output the complete SKILL.md content including the `---` frontmatter delimiters

From cedricziel/assistant, MIT.

More from cedricziel/assistant