How claude skills were meant to be made (by hand)

Why everyone generates their claude code skills first#

The generation workflow feels productive. You describe what you want, the agent writes a SKILL.md, and you have a working file in under a minute. That speed is real, and I am not going to pretend it is worthless.

Using claude code skill generation as a scaffold you then gut is a valid approach. The problem is that almost nobody guts it. The generated file becomes the finished product, and that is where the damage starts.

Generated skills over-specify. They restate defaults the model already follows and pile on negative rules that contradict each other two sections later. The file looks thorough. It is actually noise.

This is not a fringe complaint. Developers on r/ClaudeCode built a deterministic compiler that reduced instruction tokens by 55.82%, which tells you how much bloat the community considers normal. On r/ClaudeAI, one user taught Claude to respond in caveman speak for 75% token savings. People are fighting instruction overhead with increasingly creative hacks because generated skills waste so much context.

The prohibition cascade that kills generated skills#

Generated skills lean heavily on negative instructions. "Never use abbreviations." "Do not add comments unless asked." "Never output markdown in JSON fields." These rules stack up fast, and research by Hilliard (2026) measured exactly when they break things.

When negative restrictions cross 40% of total instructions, the model begins exhibiting breakdown behaviors. At 60%, static loops become inevitable. The safe ceiling is 30%, which translates to a three-to-one ratio of positive directives to negative ones.

This is not just a ratio problem. Telling an LLM what NOT to do is fundamentally unreliable. The "pink elephant" effect applies.

Say "never mention pricing" and the model starts thinking about pricing. Say "do not use passive voice" and the model allocates attention to tracking passive constructions instead of producing good output.

I have seen this firsthand. A generated skill for my blog writer agent had 22 rules, 14 of them negative. Two directly contradicted each other. The model tried to satisfy both and produced output that looped on the same paragraph structure over and over.

Separate EMNLP 2024 research by Tam et al. confirmed a related problem. Structured output format constraints, like forcing JSON or XML responses, produce a measurable decline in reasoning quality.

Generated skills are full of exactly this kind of constraint. The generator does not know what you actually need, so it specifies everything, and the model pays a reasoning tax on every token of unnecessary structure.

Note. The prohibition cascade is not about having any negative rules. It is about the ratio. A few targeted "never do X" instructions are fine. Twenty of them in one file is where the model starts fighting itself.

Anthropic proved 80% of their own prompt was noise#

This is the single strongest piece of evidence for hand-written agent skills, and it comes from Anthropic themselves. Their engineering team found that removing over 80% of Claude Code's system prompt produced no measurable loss on their coding evaluations. That is not a rounding error. That is the vendor admitting their own instructions were mostly dead weight.

They also published something I find more revealing. When they audited their own internal usage, they found conflicting messages within a single request. Instructions like "leave documentation as appropriate" sitting next to "DO NOT add comments" in the same prompt. Their system prompt, skills, and user requests were clashing with each other.

Research on prompt bloat shows reasoning degrades at around 3,000 tokens of instructions, well below what most context windows allow. A generated skill file can easily hit 1,500 tokens on its own. Stack a few of those alongside your CLAUDE.md and you are already past the cliff before the model reads a single line of your actual code.

The counterintuitive lesson is that less instruction produces better behavior, because the model can actually find the instructions that matter.

What a hand-written skill actually looks like#

Here is a generated skill for commit messages. I have simplified it, but the shape is representative of what /init produces.

# Commit Message Skill

## Rules
- Always use conventional commit format
- Never use past tense in the subject line
- Do not exceed 72 characters in the subject
- Always include a scope in parentheses
- Never leave the body empty
- Use imperative mood only
- Do not use periods at the end of the subject
- Always reference the issue number if available
- Never use abbreviations in the subject
- Use standard abbreviations for common terms in the body
- Do not use emoji in commit messages
- Always capitalize the first letter of the subject

Twelve rules. At least three the model already follows by default. Two contradict each other ("never use abbreviations" and "use standard abbreviations"). The file reads like a spec, not guidance.

Here is the hand-written version I actually use.

# Commit messages

Lead with the verb, keep under 72 chars.
When the change touches a single system, scope it (e.g. feat(cache)).
Skip the body unless the diff is non-obvious.

• Generated version had 12 rules; hand-written has 3
• Generated had 2 contradictions; hand-written has none
• Generated is a compliance checklist; hand-written is behavioral guidance

Three lines. No negatives. Every sentence exists because the model would get it wrong without the instruction. That is what SKILL.md writing looks like when you treat it as behavioral guidance instead of a compliance checklist.

The guide to writing skills that actually trigger covers the mechanics of making these fire correctly. But the authoring philosophy is even simpler. If the model already does it, do not write the rule.

Developers in the community are arriving at the same conclusion from different angles. Andrej Karpathy's CLAUDE.md reportedly uses just four short behavioral clauses, and users who adopted similarly minimal instruction sets describe it as a game changer. Four clauses. Not forty rules.

The rule that makes hand-authoring work#

Only write what the model would get wrong without you.

That is the entire method. Before adding a rule to a skill file, run the task without the skill. If the model already does the thing correctly, the rule is noise.

If it does not, write the correction in plain behavioral prose. Not a prohibition. Not a format template. Just tell it what to do differently.

I call this the delta test. The skill file should contain only the delta between the model's default behavior and what you actually want.

Everything else decays. It becomes a contradiction waiting to happen and a maintenance burden that breaks on every model release.

• Run the task once with no skill file and note where the output misses
• Write the correction as a positive instruction, not a "never" rule
• Stop when the model produces the output you want
• Delete any rule that restates what the model already does

My production plugin has 15+ skills written this way. None of them needed rewrites when moving from Opus 4 to Opus 5. The generated skills I started with broke on every upgrade because they encoded assumptions about how a specific model version behaved, not what I actually needed from the output.

Generated skills feel safe because they look thorough. Hand-written skills feel risky because they look sparse. But the sparse file is the one that works next month, and the month after that, and across the model upgrade you did not plan for.

TL;DR. Generated skills create bloated, contradictory instruction sets that degrade with every model release. Hand-write your skills as short behavioral prose. Only include the delta between what the model does by default and what you need it to do differently. That is the whole method.