> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dopamine.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Use Markdown skills to add reusable instructions and expand agent behavior.

Skills are reusable, self-contained instruction files you can attach to your agents.
Each skill is a single Markdown file with a YAML frontmatter block that defines its metadata.

## Limits

* Maximum **10 skills** per account
* Maximum **10 KB** per skill file

## File format

A skill is a `SKILL.md` file. It must start with a YAML frontmatter block followed by the skill content in Markdown.

```markdown theme={null}
---
name: my-skill-name
description: A short description of what this skill does.
allowed-tools:
  - web-search
license: MIT
compatibility: Works best with Claude 3+
metadata:
  author: Jane Doe
  version: "1.0"
---

## Skill Instructions

Write your skill instructions here in plain Markdown...
```

## Frontmatter fields

### Required

| Field         | Type   | Description                                             |
| ------------- | ------ | ------------------------------------------------------- |
| `name`        | string | Unique skill identifier. See [name rules](#name-rules). |
| `description` | string | What the skill does. Max 1024 characters.               |

### Optional

| Field           | Type            | Description                                                   |
| --------------- | --------------- | ------------------------------------------------------------- |
| `allowed-tools` | list of strings | Tools this skill is permitted to use.                         |
| `license`       | string          | License identifier (e.g. `MIT`).                              |
| `compatibility` | string          | Notes on model or platform compatibility. Max 500 characters. |
| `metadata`      | dictionary      | Arbitrary key-value metadata (e.g. author, version).          |

<Warning>
  No other fields are allowed. Any unexpected frontmatter fields will cause a validation error.
</Warning>

## Name rules

The `name` field has strict formatting requirements:

* **Lowercase only** — no uppercase letters allowed
* **Allowed characters** — letters (`a-z`), digits (`0-9`), and hyphens (`-`)
* **No leading or trailing hyphens** — `-my-skill` and `my-skill-` are invalid
* **No consecutive hyphens** — `my--skill` is invalid
* **Maximum 64 characters**

<CodeGroup>
  ```text Valid names theme={null}
  summarizer
  web-researcher
  code-review2
  sql-helper
  ```

  ```text Invalid names theme={null}
  My Skill        ← uppercase and space
  --debug         ← leading hyphens
  sql_helper      ← underscore not allowed
  UPPERCASE       ← not lowercase
  my--skill       ← consecutive hyphens
  ```
</CodeGroup>

## Structure requirements

The `SKILL.md` file must:

1. **Start with `---`** to open the YAML frontmatter
2. **Close the frontmatter** with a second `---`
3. Contain **valid YAML** inside the frontmatter block
4. Have the frontmatter parse as a **YAML mapping** (not a list or scalar)

### Minimal valid example

```markdown theme={null}
---
name: summarizer
description: Summarizes long text into bullet points.
---

When asked to summarize, extract the key points and present them as a concise bulleted list.
```

## Common validation errors

| Error                                           | Fix                                          |
| ----------------------------------------------- | -------------------------------------------- |
| `Missing required field: name`                  | Add a `name` field to the frontmatter        |
| `Missing required field: description`           | Add a `description` field to the frontmatter |
| `Skill name must be lowercase`                  | Use all lowercase in the name                |
| `Skill name contains invalid characters`        | Use only letters, digits, and hyphens        |
| `Skill name cannot start or end with a hyphen`  | Remove leading or trailing hyphens           |
| `Skill name cannot contain consecutive hyphens` | Replace `--` with `-`                        |
| `Unexpected fields in frontmatter`              | Remove fields not in the allowed list        |
| `SKILL.md must start with YAML frontmatter`     | Ensure the file starts with `---`            |
| `Description exceeds 1024 character limit`      | Shorten the description                      |
| `allowed-tools must be a list`                  | Use YAML list syntax for `allowed-tools`     |
| `File too large`                                | Keep the skill file under 10 KB              |
| `Limit reached`                                 | You can have at most 10 skills per account   |

Skills work best when they are attached to a focused [agent](/agents) or a repeatable [workflow](/workflows), then paired with the right [integrations](/integrations).

<RelatedLinks pageId="skills" />