Claude Skills Folder Structure

The SKILL.md spec is loose on purpose, but the conventions that work in practice are tight. Here is the folder structure I use after shipping a few dozen skills.

The canonical layout

my-skill/
├── SKILL.md              # required
├── scripts/              # optional, executable
│   ├── build.sh
│   └── lint.ts
├── references/           # optional, read-only docs
│   └── api-spec.md
└── examples/             # optional, sample inputs
    └── sample-input.json

Zip from the right level

The number-one install failure is zipping one level too high. SKILL.md must be at the root of the archive, not nested inside my-skill/SKILL.md. From inside the folder run zip -r ../my-skill.zip ..

Full install guide here.

scripts/ vs references/

• scripts/ — files the agent may execute. Keep them small and self-contained.
• references/ — files the agent reads when relevant. Long docs, API specs, schemas. Put what would bloat the body markdown here.

Naming

Folder name = name: in frontmatter. Match them exactly. Both lowercase, both hyphens. This is what /skills ships uniformly across the catalog.

Stop here if you can

Most skills are a single SKILL.md. Add subfolders only when the skill grows. Browse our catalog — most top-rated skills are exactly one file.