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

# Skill reference

> SKILL.md frontmatter fields and validation rules.

# Skill reference

## Frontmatter

Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required):

| Field                      | Required | Description                                                                    |
| -------------------------- | -------- | ------------------------------------------------------------------------------ |
| `name`                     | Yes      | Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.        |
| `description`              | Yes      | Max 1024 chars. What the skill does and when to use it.                        |
| `license`                  | No       | License name or reference to bundled file.                                     |
| `compatibility`            | No       | Max 500 chars. Environment requirements.                                       |
| `metadata`                 | No       | Arbitrary key-value mapping.                                                   |
| `allowed-tools`            | No       | Space-delimited list of pre-approved tools (experimental).                     |
| `disable-model-invocation` | No       | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |

### Name Rules

* 1-64 characters
* Lowercase letters, numbers, hyphens only
* No leading/trailing hyphens
* No consecutive hyphens
* Must match parent directory name

Valid: `pdf-processing`, `data-analysis`, `code-review`
Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`

### Description Best Practices

The description determines when the agent loads the skill. Be specific.

Good:

```yaml theme={null}
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
```

Poor:

```yaml theme={null}
description: Helps with PDFs.
```

## Validation

Atomic validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:

* Name doesn't match parent directory
* Name exceeds 64 characters or contains invalid characters
* Name starts/ends with hyphen or has consecutive hyphens
* Description exceeds 1024 characters

Unknown frontmatter fields are ignored.

Declared skills with missing descriptions are not loaded. Malformed `SKILL.md` files and `SKILL.md` files without a description produce warnings and are not loaded. Other Markdown files without valid skill frontmatter are ignored.

Name collisions (the same name from different real files) produce diagnostics and keep the existing first-winner precedence for `/skill:name`. Atomic also retains the other files as source-qualified candidates as described in [Skill Commands](/skills#skill-commands).