Claude Code skill folder structure: what goes where
A skill is a folder: SKILL.md at the top, references for long material, optional scripts, a README for people. The layout, the frontmatter and naming rules.
A skill is just a folder, but a consistent layout makes skills easier to review, share and package. This is the one we use for every skill we ship.
my-skill/
SKILL.md frontmatter + the rules Claude follows
references/ long material, opened when needed
tokens.css
components.md
scripts/ optional helpers SKILL.md tells Claude to run
README.md for people: install, requirements, examples
LICENSEThe frontmatter
---
name: my-skill
description: What it does, in concrete nouns. Use when the user asks for...
---The name matches the folder. The description is the part that decides whether the skill gets used, so it is worth the most care: see how to write a skill description.
Checks worth automating
SKILL.mdexists at the top level, not one folder down.- The frontmatter name matches the folder name.
- The description exists and stays under 1024 characters.
- Every file
SKILL.mdmentions underreferences/actually exists.
Our packing script refuses to build a ZIP when any of these fail. Why long material belongs in references/ is in the references folder.
Questions
What must a Claude skill folder contain?
At minimum a SKILL.md at the top level with frontmatter containing a name and a description. Everything else is optional.
What are the rules for a skill's name?
Lowercase letters, numbers and hyphens, kept short, and matching the folder name is the safe convention. The name is how the skill is identified and invoked directly.
Where do scripts go in a skill?
In a scripts folder, called from instructions in SKILL.md. Keep them self-contained and check their dependencies, because they run on the user's machine.