# Reference: skill file format

> Neutral description of the markdown files the `read_skill` tool serves.

## Location

| Rule | Value |
|------|-------|
| Directory | `skillsDir` (default `skills`). |
| Patterns | `<skillsDir>/<name>.md` (flat) and `<skillsDir>/<name>/SKILL.md` (one directory per skill), mixed freely. Other files in a skill's directory are ignored. |
| Skill name on disk | The file name without `.md`, or the directory name for a `SKILL.md`. |
| Both forms for one name | `read_skill` returns the flat file. |
| Missing directory | Not an error: zero skills, `read_skill` not declared. |

## Front matter

Optional. When present, the file starts with a line `---` and the header ends at the next `---` line. Only two keys are read; the others are ignored.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `name` | string | file name without `.md` | Name shown in the catalogue and accepted by `read_skill`. An empty value keeps the default. |
| `description` | string | `""` | One-line summary shown in the catalogue. |

A `description:` line in the body, after the closing `---`, is not metadata.

## Catalogue rendering

The tool description is:

```
Load a skill: the step-by-step procedure to follow for this kind of task. Call it BEFORE doing the work, with the name of the matching skill, and then follow what it says. Available skills:
  <name> — <description>
  <name>
```

Entries are sorted by name; the ` — <description>` part is omitted when the description is empty.

### Example

```markdown
---
name: what-time-is-it
description: Give the current date and time.
keywords: time, date, clock
---

# What time is it?

Run:

```bash
date "+%A %d %B %Y — %H:%M:%S (%Z)"
```
```

The `keywords` key is accepted in the file and ignored by the loader.

## Shipped examples

| Path | `name` | `description` |
|------|--------|---------------|
| `skills/greetings/SKILL.md` | `greetings` | Greet somebody with a festive message. |
| `skills/vulcan-salute/SKILL.md` | `vulcan-salute` | Send a vulcan salute to somebody. |
| `skills/what-time-is-it/SKILL.md` | `what-time-is-it` | Give the current date and time. |

They use the directory-per-skill layout; started from the repository root, `mm` reports `skills: 3`.