I avoided Claude Code skills for six months because the docs made them sound like a separate framework. A skill is a folder with one SKILL.md file in ~/.claude/skills/ : YAML frontmatter with a name and a description , then markdown instructions. Claude reads the description at session start and fires the skill when your request matches. That’s the whole mechanic, and the minimum useful version is about 30 lines. After building a handful, here are the things that actually cost me time: The description is the trigger, not documentation. My first one said “Manages my project operations.” It never fired. I rewrote it to list the literal phrases I’d type (“set up the project here”, “audit this”) and it fired on the first try. Spend most of your effort here. One skill, one purpose. If three workflows don’t share state, that’s three skills. A bloated description matches inconsistently. References vs templates. References are files Claude reads but never copies. Templates are files it copies into your project. Mix them up and it either writes a doc into your repo or never produces output. Skills don’t auto-reload. Edit a SKILL.md mid-session and the running instance still uses the old version. Restart to pick up changes. I lost 20 minutes to this. Version-control the folder. Otherwise every machine runs a slightly different version of your skills and you stop trusting them. The non-trivial one I built is a project-memory system (indexing + a tiered memory bank + rules + sub-agents) packaged as a single skill with multiple modes. On the project I’ve run it on longest, context spend and hallucinated edits both dropped a lot once the agent stopped searching blindly and stopped reinventing code that already existed. Curious what others have packaged as skills, and whether anyone splits by mode the way I did or keeps each workflow as its own skill? submitted by /u/MaterialAppearance21
Originally posted by u/MaterialAppearance21 on r/ClaudeCode