Fifty Skills and What They Actually Taught Me

A Claude skill is a markdown file that tells the model how to handle a specific type of task. You write the instructions, define when it should fire, and the model loads it automatically when the task matches. Think of it as a reusable judgment packet, not code, but encoded decision-making.

I've built fifty of them. The number sounds impressive until you look at what actually happened.

Fifteen of the fifty fire regularly. The rest are either too narrow (they match a task I do once a quarter), too broad (they fire when they shouldn't and add noise), or broken in ways I haven't fixed yet. Four have compliance gaps that prevent me from deploying them to the environment where they'd matter most.

What the number 50 taught me that the number 1 wouldn't have.

Planned Skills Are the Weakest

My first skills were architected. I sat down, identified workflow categories, document generation, code auditing, social post drafting, and wrote skills for each. Proper YAML frontmatter. Clean decision trees. Thorough instructions.

They were fine. Generic. The kind of thing you'd get from an "AI skill template" blog post. They worked in the same way that a cookbook recipe works: technically correct output that nobody remembers eating.

The skills that actually compound are the ones I captured, not planned. Here's the pattern: I'm working on something. Claude gets it wrong. I correct it. It gets the same thing wrong the next session. I correct it again. Third time, I stop correcting and start capturing.

The difference is specificity. A planned skill says "when writing a blog post, use this structure and this voice." A captured skill says "when writing a blog post, never open with a question, never produce output with more than three headers, and if the first draft has bullet points where prose should be, rewrite it in paragraphs before presenting." The captured skill knows what went wrong. The planned skill guesses what might.

The Description Field Is the Whole Game

A skill has two parts: the instructions (what to do) and the description (when to fire). I spent months writing better instructions. I should have been writing better descriptions.

The description is what Claude reads to decide whether the skill is relevant to the current task. A vague description, "helps with writing", means the skill fires on everything text-adjacent, diluting the context with instructions meant for blog posts when you're writing a commit message. A sharp description fires precisely when it should and stays quiet otherwise.

I've rewritten descriptions more than instructions. The instructions are the knowledge. The description is the routing. Bad routing makes good knowledge useless.

Fail Conditions Beat Positive Instructions

Every skill I write now has an explicit section I call FAIL CONDITIONS. Not "do this well", "if the output contains X, the skill failed."

Positive instructions tell Claude what to aim for. Fail conditions tell Claude what to avoid. The avoidance list is more useful because Claude's default failure mode is generic, confident output. You're not correcting for wrong answers, you're correcting for average answers. The fail condition catches average before it ships.

The Environment Split That Broke My Deployment

Skills I built in Claude Code worked perfectly. Same skills deployed to a claude.ai project broke silently. No errors. No warnings. Just enforcement that didn't enforce.

The reason: Claude Code runs in a terminal with shell access. Skills there can reference hooks, shell scripts that block operations or run linters. Claude.ai's project environment doesn't have shell access. A skill that relies on a PostToolUse hook to auto-format code after every write simply... doesn't auto-format. The instruction is in the skill. The mechanism it depends on doesn't exist in that runtime.

Four of my skills have this problem. I can't deploy them to the environment where they'd add the most value until I refactor enforcement from shell hooks to inline instructions. That refactor is gated by a rule I set for myself: fix before expand. No new skills until the compliance gaps are closed.

It's the right rule. It also means I've been at 50 for two months.

What Fifty Teaches You That Five Doesn't

At five skills, you think the skill is the deliverable. You built a thing. It works. Ship it.

At fifty, you realize the library is the deliverable. Individual skills matter less than the system that routes between them, the correction loop that improves them, and the fail conditions that prevent regression. The skill is a file. The library is the judgment layer.

This is the same pattern I see in every AI adoption: the tool is never the interesting part. The interesting part is the system around the tool, the maintenance, the correction, the quality gates, the decision about when to use it and when not to.

If you're at one or two skills, the lesson isn't "build more." The lesson is: pay attention to what goes wrong, capture the corrections, and let the mistakes tell you what the next skill should be. The factory is the failure pattern, not the planning session.