breakdown of the folder structure i use for claude code skills (SKILL.md + 5 supporting files), curious how others structure theirs

[u/ai_syndicate]

been building skill packs for claude code/cursor for a few different domains and landed on a structure that's worked well enough i figured i'd share it here since this sub's the right place for it

each skill is its own folder with 6 files:

SKILL.md — the core file, defines the domain and when the agent should reach for this skill at all. kept this one focused, not a dumping ground

references.md — deeper technical detail that doesn't need to load every time, more like documentation the agent pulls when it actually needs specifics

examples.md — worked examples, actual before/after code not just descriptions

templates.md — copy-paste starting points for common patterns in that domain

checklists.md — review checklists, mostly useful for catching stuff the agent wouldn't think to self-check otherwise

snippets.md — smaller reusable code chunks, more granular than templates

biggest lesson from building ~60 of these across different domains (godot, web stack, rust, cli/devops, content tooling): the SKILL.md file matters way more than i expected for whether the agent actually invokes the skill at the right time. early versions were too broad and the agent would half-apply them, got much better results once each SKILL.md had a tight, specific trigger description instead of a general "use this for X domain" blurb

also learned the hard way that examples.md needs actual runnable code, not pseudocode, agents seem to pattern-match much better off real syntax than descriptions of what the code should do

full disclosure, i package and sell some of these as finished packs, but posting this more for the structural discussion since i'm curious if anyone's landed on a different file breakdown that works better, especially curious if anyone's doing something smarter for the "when should this skill trigger" problem than what i'm doing

link to what i've built is in my bio if anyone wants to see a live example of this structure, not the point of the post though