There are 35 skill folders in my ~/.claude/skills directory right now, and 53 more that I ship publicly on my marketplace. Those numbers hide the real one: the count of skills I have deleted, which is larger than most people's count of skills written. That ratio is the honest summary of everything below. Skills are the highest-leverage feature in Claude Code, and the craft of building them is mostly the craft of knowing what not to encode, because a skill that teaches the model something it already knows does not just waste tokens. It actively makes output worse by overriding better native judgment with your frozen opinion.
Most skills die young, and the autopsy is always the same
Every skill I have retired failed the same test: it encoded behavior instead of knowledge. A commit-message skill, back when models wrote stilted commit messages, produced rigid formula long after the models had learned to write better ones unaided. A content-outline skill kept forcing a structure the model would have improved on. Each was correct on the day I wrote it and a liability two model generations later.
The skills that survive encode things the model cannot know: my thresholds, my scars, my project's facts. My SEO skills carry the exact quality gates I adopted after Google deindexed most of this site, with numbers like "hard stop at 500+ pages without justification." No model update makes that obsolete, because it was never the model's knowledge to begin with. Before writing any skill now, I ask one question: could a strong model already do this if I just asked? If yes, no skill. If the answer is "yes, but not to my standard, with my rules," that delta is the skill.
The description field is marketing, and the customer is the model
A skill loads when Claude decides it is relevant, and it decides from the description. That makes the description a routing advertisement, and vague ones mean your skill sits unused while you wonder why the feature "doesn't work." Here is the actual description from my programmatic SEO skill:
description: >
Programmatic SEO planning and analysis for pages generated at scale...
Use when user says "programmatic SEO", "pages at scale", "dynamic pages",
"template pages", "generated pages", or "data-driven SEO".
Notice the second half: literal trigger phrases, the words a user actually types. Every one of my 35 skills that reliably fires has this shape, and every skill I ever debugged for under-triggering was missing it. One nuance that took me too long: calibrated urgency belongs in the description (which does routing) and never in the body (which does behavior). A body full of CRITICAL and MUST produces anxious, rigid output on current models. A description full of concrete trigger phrases produces correct routing. Same volume knob, opposite settings.
Skills are folders, and that changes what they can hold
A skill is not one Markdown file; it is a directory, and Claude reads beyond SKILL.md only when the task calls for it. My SEO family, 14 skills covering content, technical, schema, sitemaps, hreflang, and more, shares a references/ layer: the content skill's E-E-A-T section is a summary that points at a full framework document loaded only when the analysis needs it. This progressive disclosure is the difference between a skill costing 200 tokens on load and 4,000. Budget matters more than people think, because skill descriptions ride in context all the time, and their bodies compete with your actual task for attention.
The folder structure also enables real composition. My programmatic-SEO skill's internal-linking section literally says "match seo-content guidelines" for link density, one skill deferring to another's rules rather than duplicating them. Duplicated guidance drifts; referenced guidance stays consistent. Fourteen skills that agree with each other behave like one senior consultant. Fourteen skills that subtly conflict behave like a committee.
Skills rot on a calendar, so put a calendar on them
Open any of my skill files and the first line after the frontmatter is a comment like <!-- Updated: 2026-02-07 -->. That habit came from a painful discovery: skills rot in two independent ways. The domain moves (my SEO skills reference specific Google policy enforcement waves, which have dates) and the models move (guidance written to compensate for a weakness becomes railroading once the weakness is gone). The date stamp turns "is this stale?" from a feeling into a check. When I sit down after a model release, I sort by date and re-read the oldest first, and something gets deleted almost every time. Nobody talks about skill maintenance because nobody talks about their skills six months later. The ones I still run six months later are the ones that got edited monthly.
Match the leash to the fragility
The wrong-degrees-of-freedom failure runs both directions. My early skills railroaded judgment calls: step-by-step scripts for tasks where the model's own plan was better than mine. Current models punish that with obedient mediocrity. But the opposite failure is real too: for genuinely fragile operations, vague prose is negligence. My rewrite pipelines pair the judgment skill with exact, do-not-modify commands for the destructive steps, backups before writes, range guards on IDs. The rule I settled on: prose heuristics for open fields, exact scripts for narrow bridges, and be honest about which one you are standing on.
The related discipline is encoding inputs instead of steps. My content skill does not tell the model how to structure a post; it tells it which experience inputs to demand from me before drafting. That inversion, skill as interrogator rather than skill as script, produced the single biggest quality jump across my whole roster.
Ship them, because distribution is a forcing function
Publishing 53 skills on my Agent Skills Marketplace improved the private ones, for the same reason open-sourcing improves code: an audience forces you to separate "my machine's quirks" from "actual method." Every skill that went public got its assumptions written down, its trigger description sharpened, and its project-specific paths pulled out into configuration. Half of the lessons in this post only became visible during that extraction. If you build a skill you are proud of, package it for a stranger even if you never publish; the packaging is the audit. And before shipping anything, measure whether the skill actually helps: testing skills with a skill-creator workflow beats vibes, because some of my proudest skills tested out as neutral, which is a polite word for clutter.
Where I would start today
Not by installing thirty community skills, which is how you get a bloated setup that fires the wrong expertise at the wrong time; my current curated stack is deliberately small for that reason. Start with the repetition audit: notice the instructions you give Claude more than twice, write the smallest skill that captures your version of that knowledge, give it a trigger-phrase description, date-stamp it, and use it for two weeks before writing the next one. If you are still getting comfortable with the tool itself, the fundamentals come first, because skills multiply a workflow that already works and merely decorate one that does not.
Learn the full build process
I teach the complete arc, from the repetition audit through skill architecture, testing, and shipping to a marketplace, inside my AI School, using these exact 35 skills as the case studies, deletions included. If you would rather learn from my dead skills than create your own graveyard, that is the shortest path I can offer.
