Skill Anatomy: SKILL.md, References, Scripts, Assets

The minimal folder

The minimal skill is a directory containing SKILL.md. The frontmatter names the skill and describes when it should be used. The Markdown body gives the agent the operating procedure: steps, checks, examples, constraints, and references to any bundled files.

my-skill/
  SKILL.md

That small shape is enough for many editorial or review workflows. Add more files only when they make the skill easier to maintain, safer to execute, or more reproducible.

Frontmatter: name and description

The name should be stable, lowercase, and easy to refer to. The description is not marketing copy; it is a trigger contract. It should tell the agent and user exactly which task calls for the skill and which nearby tasks do not.

A weak description says "helps with design." A stronger one says "Use when creating production-grade frontend interfaces that need distinctive visual design and avoidance of generic AI aesthetics." The second version gives the agent a real matching boundary.

References: deep material on demand

Put long policy, domain, or API notes in references/ instead of stuffing everything into SKILL.md. The skill entrypoint should route the agent to the right reference when needed. This keeps the first loaded context small and lets the agent read deeper only after it knows the task variant.

Good reference files are named for decisions: brand-voice.md, api-auth.md, review-rubric.md, or invoice-rules.md. Avoid vague names such as notes.md when the folder may grow.

Scripts and assets

Use scripts/ when the workflow has deterministic work that should not be retyped from memory: rendering PDFs, validating schemas, extracting metadata, checking a fixture, or running a repeatable conversion. A script should be narrow, inspectable, and documented by the skill instructions.

Use assets/ for templates, example files, visual materials, boilerplate, and other reusable inputs. Assets are useful when the output must match a format that prose alone cannot describe reliably.

Visual model

FAQ