Fineuralab
Claude Code Skill Structure
A guide to common Claude Code Skill structure: SKILL.md, references, scripts, assets, and progressive disclosure.
AI Skills guide
Claude Code Skill Structure
A practical skill repository is usually organized so the agent reads the smallest useful instruction first and opens deeper material only when the task needs it.
Main pieces
Most useful skill packages separate trigger instructions from heavy references and repeatable scripts.
- SKILL.md for trigger and core behavior.
- references/ for deeper rules and examples.
- scripts/ for mechanical repeatable steps.
- assets/ for templates, images, or fixtures.
Why progressive disclosure matters
Loading everything all the time makes agents slower and less predictable. A good skill says what to open and when.
- Short first read.
- Task-specific references.
- Clear script purpose.
- Minimal unrelated context.
Repository review
When browsing a skill repo, look beyond popularity and inspect whether the structure matches the promised use case.
- Does the folder layout match the README?
- Are examples realistic?
- Are scripts optional and inspectable?
- Are unsafe actions documented?