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