
How to Create a Claude Code Skill, and Ten Ways It Fails
The name field is ignored, a missing description is filled in from your body, and a SKILL.md one directory too deep loads nothing and says nothing. Measured, then built for real.
CATEGORY · 65 ARTICLES

The name field is ignored, a missing description is filled in from your body, and a SKILL.md one directory too deep loads nothing and says nothing. Measured, then built for real.

We registered a hook on all 33 events at once and ran real sessions against them. Which fire, what each payload actually contains, and the three ways a hook fails without telling you.

The format-on-write hook every guide recommends, run three times against a control. Plus the event that never fires on failure and the payload the binary describes wrongly.

Fourteen matchers in one run, four ways to decide, and the transcript that records a command the shell never executed.

Seven runs, four repository shapes, two models: what /init writes, what it costs, and the half of a CLAUDE.md it cannot produce.

One 53-line diff, six known bugs, five runs across two models and three effort levels — plus the routing table that decides how deep the review actually goes.

The prompt behind /security-review, its 17-item exclusion list and confidence-8 cutoff, measured against a diff with six known vulnerabilities in it.

We pulled the default keymap out of the shipped binary: 180 bindings, 82 keys, 22 contexts, 30 actions you can only reach by binding a key yourself.