# SKILL.md frontmatter, field by field

The frontmatter is how an agent decides whether a skill applies. Two fields are required; the rest narrow behaviour or carry your own bookkeeping.

Source: <https://www.contexory.com/docs/reference/frontmatter-reference>

## Every field

The complete set. Anything else you add is preserved but ignored.

| Field | Required | What it does |
| --- | --- | --- |
| `name` | Yes | The skill's identifier. Lowercase, hyphenated, unique within your library. |
| `description` | Yes | When to use the skill. This is what an agent matches against, and the highest-leverage field in the file. |
| `allowed-tools` | No | Narrows which tools the agent may use while this skill is active. |
| `license` | No | A licence identifier, for skills you intend to share. |
| `compatibility` | No | Assumptions the skill makes about its inputs or environment. |
| `metadata` | No | A free-form string map for your own bookkeeping. Never read by the agent. |

## name

The identifier. It is also the folder name the skill is written to at every destination, which is why the rules are strict:

- Lowercase letters, digits and single hyphens only: no uppercase, no underscores, no consecutive hyphens.
- 1 to 64 characters.
- `anthropic` and `claude` are reserved. Pick something that names the job instead.

```
name: pdf-review-checklist   # valid
name: PDF-Review              # invalid — uppercase
name: pdf--review             # invalid — double hyphen
name: claude                  # invalid — reserved
```

Name the job, not the tool: `pdf-review-checklist` tells a reader what the skill does, `helper-2` does not.

## description

Required, and the field to spend your time on. An agent picks a skill by reading descriptions; it does not read bodies first. A description that does not describe a **situation** gives it nothing to match against.

The difference in practice:

```
# Weak — states a topic, gives the agent no trigger
description: Contract review.

# Strong — names the situation that should invoke it
description: Use when the user asks for a contract or PDF to be reviewed. Walks
  the standard clause checklist and reports findings by severity.
```

- **Name the trigger.** Phrases like "Use when the user…" or "For tasks involving…" are what make a skill fire at the right moment.
- **Write in the third person.** Describe what the skill does, not what you will do.
- **Up to 1024 characters.** Long is allowed; use the room to cover the cases that should trigger it.

> **Under-triggering is silent**
>
> A skill that never fires produces no error; the agent simply answers without it, and looks like it was never installed. If a skill seems to be ignored, the description is the first thing to check.

## allowed-tools

Optional. A space-separated list of tool tokens the agent may use while the skill is active. Omit it and the skill inherits whatever the agent already has. See [allowed-tools](/docs/reference/allowed-tools) for the grammar and how to scope it.

```
allowed-tools: Read Grep Bash(git:*)
```

## license, compatibility, metadata

Three fields that carry information rather than change behaviour:

| Field | Notes |
| --- | --- |
| `license` | A licence identifier such as `MIT`. Worth setting on anything you intend to share outside your team. |
| `compatibility` | Up to 500 characters. Assumptions the skill makes: input formats, size limits, a language. Read by people, not enforced. |
| `metadata` | A map of string keys to string values, for ownership, review cycles, ticket references. Never read by the agent, so use it freely. |

```
---
name: pdf-review-checklist
description: Use when the user asks for a contract to be reviewed…
allowed-tools: Read Grep
license: MIT
compatibility: Assumes contracts are English-language and under 100 pages.
metadata:
  owner: legal-ops
  review-cycle: quarterly
---
```

## Fields we do not recognise

Any key we do not recognise is **preserved exactly as written**. A skill imported from elsewhere keeps its extra frontmatter through an edit-and-publish round trip, comments and key order included.

> **Preserved is not the same as understood**
>
> An unrecognised field survives, but nothing validates it and nothing acts on it. If a host-specific key matters to you, keep a note of what it is for; the file will not tell you.