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.

1. Using .agents/skills/ for GitHub Copilot (it needs .github/skills/).
2. Listing version/author/license as required frontmatter.
3. Putting category: and version: at the top level instead of under

metadata:.

1. Producing a Title_Case or snake_case name instead of kebab-case.
2. Writing a vague description ("Helps with X") that omits the "when to use".
3. 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/.