---
name: agent-skills-package-spec
source: https://app.decimal.ai/s/agent-skills-package-spec@1/SKILL.md
source_sha256: 3dcdd90480de
---

# Agent Skills package layout (agentskills.io)

## Contract
Enforces the agentskills.io packaging spec: the install path, the uppercase
`SKILL.md` main file, the three exact subdirectory names, and the frontmatter
field rules. Apply whenever you create, scaffold, port, or validate an Agent
Skill package for Codex CLI, GitHub Copilot, or Amp.

## Rules

### R1 — Install path is tool-specific
- Codex CLI: `.agents/skills/{skill-name}/SKILL.md`
- Amp: `.agents/skills/{skill-name}/SKILL.md` (same root as Codex)
- GitHub Copilot: `.github/skills/{skill-name}/SKILL.md`

Codex and Amp share `.agents/skills/`; only Copilot uses `.github/skills/`.

### R2 — The main file is `SKILL.md`, uppercase, at the directory root
The file is always spelled `SKILL.md` — uppercase `SKILL`, capital `.md` stem.
Never `skill.md`, `Skill.md`, `README.md`, or `index.md`. It sits directly at
the root of the skill directory, never nested inside a subdirectory.

### R3 — Directory name MUST equal the frontmatter `name`
The folder that contains `SKILL.md` is named exactly the same string as the
`name:` field. If `name: pdf-tables`, the folder is `pdf-tables/`.

### R4 — Subdirectories: three exact names, all optional
- `scripts/` — executable code. NOT `src/`, `bin/`, or `lib/`.
- `references/` — additional docs. NOT `docs/`, `reference/`, or `doc/`.
- `assets/` — static resources (images, fixtures, CSVs). NOT `static/`,
  `resources/`, `data/`, or `media/`.

These are the only sanctioned subdirectories. Pick by file kind: runnable code →
`scripts/`, prose/docs → `references/`, everything static/binary → `assets/`.

### R5 — Frontmatter has exactly two required fields
YAML between `---` fences. ONLY these two are required:
- `name`
- `description`

Nothing else is required — not `version`, not `license`, not `category`.

### R6 — `name` validation
- 1–64 characters.
- Lowercase alphanumeric and hyphens only.
- No uppercase letters.
- No leading or trailing hyphen.
- No consecutive hyphens (`--`).
- Must match the directory name (R3).

### R7 — `description` validation
- 1–1024 characters.
- States BOTH what the skill does AND when to use it. A description that gives
  only the "what" (or only the "when") is incomplete.

### R8 — Optional frontmatter fields
Add only when relevant: `license`, `compatibility` (runtime/binary deps),
`allowed-tools` (which tools the skill may run). Plus `metadata:` — a nested
map for things like `category:` and `version:`. `category` and `version` live
UNDER `metadata:`, never as top-level keys.

### R9 — Body length
Markdown after the frontmatter, no format restriction. Keep the whole `SKILL.md`
under 500 lines; move overflow content into the `references/` subdirectory.

## Worked examples (BEFORE = base default, AFTER = conforming)

### R1 — install path
- Task: scaffold a Copilot skill that lints SQL.
- BEFORE: `skills/sql-lint/SKILL.md` or `.agents/skills/sql-lint/SKILL.md`.
- AFTER: `.github/skills/sql-lint/SKILL.md` (Copilot uses `.github/`).

### R2 — main file name
- BEFORE: `pdf-tables/skill.md` or `pdf-tables/README.md`.
- AFTER: `pdf-tables/SKILL.md` (uppercase, at the root).

### R3 — directory matches name
- BEFORE: folder `MySkill/` with `name: my-skill`.
- AFTER: folder `my-skill/` with `name: my-skill` (identical strings).

### R4 — subdirectory names
- BEFORE: `src/extract.py`, `docs/api.md`, `static/logo.png`.
- AFTER: `scripts/extract.py`, `references/api.md`, `assets/logo.png`.

### R5 — required fields
- BEFORE: frontmatter with `name`, `description`, `version`, `author` all
  presented as required.
- AFTER: only `name` and `description` are required; the rest are optional.

### R6 — name validation
- BEFORE: `name: PDF_Form_Filler`.
- AFTER: `name: pdf-form-filler` (lowercase, hyphens for word breaks).

### R7 — description
- BEFORE: `description: Helps with PDFs`.
- AFTER: `description: Extracts tables and form fields from PDF documents. Use
  for document analysis, data extraction, and form parsing.`

### R8 — optional fields
- BEFORE: top-level `category: docs` and `version: 1.0.0`.
- AFTER:
  ```yaml
  metadata:
    category: docs
    version: 1.0.0
  ```

### R9 — length overflow
- BEFORE: a 900-line `SKILL.md` with full API tables inline.
- AFTER: `SKILL.md` under 500 lines, with the tables moved to
  `references/api.md`.

## Edge cases & exceptions
- **Codex vs Amp:** both resolve to `.agents/skills/` — there is no separate
  Amp root. Only Copilot diverges to `.github/skills/`.
- **Porting between tools** changes ONLY the root directory; the package
  contents (the `SKILL.md` and subdirs) are byte-for-byte identical. Codex/Amp →
  Copilot: move `.agents/skills/x` to `.github/skills/x`.
- **Trailing hyphen / leading hyphen** both fail R6, even though the middle is
  valid: `-resizer` and `resizer-` are both rejected.
- **Single-word name** needs no hyphen: `linter` is valid.
- **`name` length is the directory's too** — a 64-char name means a 64-char
  folder; keep it short in practice.
- **`metadata.category` is NOT the same as the skill's discovery category** in a
  host registry; here it is just a nested frontmatter convenience field.
- **`allowed-tools`** is a hint about runnable tools, not an enforced sandbox —
  declare it when the skill shells out, but it does not gate execution.

## Do / Don't
- DON'T name the file `skill.md` / `README.md`. DO name it `SKILL.md`.
- DON'T use `src/` or `bin/` for code. DO use `scripts/`.
- DON'T use `docs/` for docs. DO use `references/`.
- DON'T use `static/` or `resources/`. DO use `assets/`.
- DON'T put `category`/`version` at the top level. DO nest them under
  `metadata:`.
- DON'T mark `version`/`license` as required. DO require only `name` +
  `description`.
- DON'T uppercase or double-hyphen the `name`. DO keep it lowercase with single
  hyphens.
- DON'T let the directory name drift from `name`. DO keep them identical.

## Common mistakes the base makes
1. Writing `skill.md` lowercase or `README.md` as the main file.
2. Defaulting to `src/`, `lib/`, `docs/`, `static/` instead of the three exact
   names.
3. Using `.agents/skills/` for GitHub Copilot (it needs `.github/skills/`).
4. Listing `version`/`author`/`license` as required frontmatter.
5. Putting `category:` and `version:` at the top level instead of under
   `metadata:`.
6. Producing a `Title_Case` or `snake_case` name instead of `kebab-case`.
7. Writing a vague description ("Helps with X") that omits the "when to use".
8. Letting the folder name differ from the `name` field.

## Quick checklist
- [ ] Path: `.agents/skills/` (Codex/Amp) or `.github/skills/` (Copilot).
- [ ] Main file `SKILL.md`, uppercase, at the root.
- [ ] Folder name == `name` field.
- [ ] Subdirs only `scripts/`, `references/`, `assets/`.
- [ ] Required frontmatter: `name` + `description` only.
- [ ] `name`: lowercase, 1–64, single hyphens, no leading/trailing hyphen.
- [ ] `description`: 1–1024, what + when.
- [ ] `category`/`version` nested under `metadata:`.
- [ ] `SKILL.md` under 500 lines; overflow to `references/`.