A Claude Code skill is a Markdown file you drop into ~/.claude/skills/. It describes a complete workflow: when to trigger it, how to execute it step by step, what it should produce. Claude reads it at the right moment and follows it. No manual command, no copy-pasted prompt. You say “publish this article” and the skill chains the checks, image generation, commit, deploy, and LinkedIn draft on its own.
I have nine in production on this site. Eight work well. One is problematic. And that one is the most interesting to analyze.
Nine skills, nine domains
To understand what follows, here’s what my nine skills do. Each covers a specific domain of my workflow:
- blog-article: write and publish an article (FR + EN, OG image, deploy, LinkedIn, dev.to)
- blog-fix: fix a typo or bug on an already-published article without relaunching everything
- fiche-livre: read a technical book PDF and produce a complete book review (summary, 5-axis radar, SVG diagrams, bilingual)
- outil-factory: create or iterate on a free web tool (/outils/), with radar scoring and Playwright tests
- veille-debug: diagnose bugs in the automated tech watch system (AI article generation, cron, registry)
- vide-contexte: extract non-obvious insights from the current session to persistent memory before clearing context
- deep-research: launch a multi-source search with adversarial verification and cited synthesis
- frontend-design: visual direction guide to avoid producing generic Bootstrap output
- feature-loop: manage the full feature cycle (spec, implementation, review, tests, merge)
Eight work cleanly. The ninth, feature-loop, clocks in at 1,002 lines and roughly 25,000 tokens. That’s the one a recent audit put under the microscope.
What a skills audit actually looks at
Auditing a skill means measuring four things: raw length (lines, tokens), structure (body versus on-demand reference files), the density of urgency markers in the text, and what remains visible in long context, when Claude is on iteration 3 of a loaded session.
On the eight healthy skills, the numbers are clear: between 70 and 257 lines, 1,000 to 7,700 tokens, simple structure. feature-loop stands alone: 1,002 lines, 25,000 tokens, and text saturated with NON-NEGOTIABLE / NEVER / MANDATORY / LOCKED at every paragraph.
The diagnosis fits in one sentence: when everything is critical, nothing is.
Salience dilution
When Claude loads a skill, it loads the entire body. Everything in there competes for the model’s attention. If ten rules are all marked MANDATORY, the model has no way to decide which one to prioritize when there’s a conflict or a context constraint. It doesn’t arbitrate: it averages. And averaging ten MANDATORY rules gives zero clear priority.
The invariants that actually change behavior — the ones that break the workflow if forgotten — drown in token micro-optimizations and design justifications. Result: the most important rules are followed with the same reliability as the least important. Which is: not always.
On the eight healthy skills, critical rules fit in ten lines maximum. The rest is either absent or in reference files loaded at the step that needs them.
The silent drift in long context
A skill loads at trigger time. But a work session accumulates: file reads, tool outputs, exchanges, iterations. By iteration 3 of a complex feature, feature-loop‘s SKILL.md is buried under thousands of tokens of accumulated context.
The rules at the top of the file, Claude still sees. The ones on page 8, less so. This isn’t a bug. It’s the physics of attention: a language model gives more weight to recent tokens and to tokens at the beginning of context. What’s in the middle of a 25,000-token file, buried under tool outputs, is structurally less well processed.
The fix isn’t to move everything to the top. It’s to extract what doesn’t belong in the body: design justifications, complete examples, 50-line bash recipes. Those belong in a references/ file loaded at the exact step that needs them. The skill body stays an execution contract, not an encyclopedia.
What distinguishes the skills that hold
The eight healthy skills share two characteristics that aren’t obvious at first glance.
The description is a trigger, not a summary. Each skill has a frontmatter with a short description. That’s what Claude reads to decide whether to invoke it. A description that summarizes the skill (“this skill creates book reviews”) is less effective than one that lists concrete situations (“trigger on: ‘book review’, ‘summarize this book’, a book PDF provided”). The first says what the skill is. The second says when to call it — which is the only thing that matters at trigger time.
The body trusts the model. Short skills don’t over-specify. They give the contract (goal, output format, critical steps) and let Claude reason about the rest. An 80-line well-structured skill outperforms a 400-line over-specified one, because every one of those 80 lines has value and the model can hold them all in mind simultaneously. Over-specification is usually codified mistrust. And mistrust in 400 lines produces a skill even Claude can’t follow.
The public repo: six installable skills
I extracted six of my skills into a public repo: github.com/ohugonnot/claude-skills.
Six skills available, organized as a pipeline:
- issue-mr: turn a vague idea into a well-formed issue, branch, and MR/PR shell
- feature-loop: autonomous quality-gated loop — writer, test-writer, and reviewer are separate agents
- senior-review: senior-level review by dimension (correctness, security, design, tests), blind reviewers
- branch-wrap-up: clean branch close-out (conventional commit, push, memory capture)
- book-distill: read a PDF and produce a verified reading note, citations checked word for word
- vide-contexte: extract non-deducible session insights to persistent memory before /clear
Installation via the Claude Code marketplace in one line, or manually with a symlink:
# Via marketplace (recommended)
/plugin marketplace add ohugonnot/claude-skills
/plugin install feature-loop@web-developpeur-skills
# Or manually
git clone https://github.com/ohugonnot/claude-skills.git ~/claude-skills
ln -s ~/claude-skills/plugins/vide-contexte/skills/vide-contexte ~/.claude/skills/vide-contexte
Enter fullscreen mode Exit fullscreen mode
Publishing these skills changed how I write them. A skill for personal use can lean on implicit context: project conventions, file structure, things I know without writing them. A public skill must work cold, on an unknown project, without a local CLAUDE.md. That constraint forces you to make explicit everything that was tacit. And an explicit skill is a better skill, even for personal use.
The search engine that changes discovery
The real problem with skills isn’t writing them. It’s discovery. If you have twenty skills spread across sub-folders, knowing which one to call for a given need becomes a problem in itself. The natural reflex is to type the skill name, but you still need to remember the name.
Claude Code now has a keyword-based skill search. Instead of memorizing the exact list, you can search by domain or intent: “something to publish an article”, “a research skill”, “to clean up context”. The engine returns skills whose description matches.
This mechanism changes how you write descriptions. If that’s what gets indexed, the description must contain the words users will type when searching — not the internal terms you use to name the concept. The difference is subtle but real: “clean context before /clear” triggers on “empty the context”, “save before clear”, “extract the session”. A description oriented toward searched usage, not technical definition.
Conclusion
The real lesson from the audit isn’t in the list of rules. It’s in the gap between feature-loop and the other eight. A skill that’s too long doesn’t break because it’s unreadable. It breaks because it dilutes: critical rules drown in noise, and the model no longer has a way to know which ones deserve priority attention.
A skill body isn’t an exhaustive source of truth. It’s an execution contract. The cleaner it is, the better it holds when context accumulates. Anything not strictly necessary for execution belongs elsewhere: in a reference file, in a script, or nowhere.
🧩 Installable skills
The five public skills are available at github.com/ohugonnot/claude-skills. For writing patterns from Anthropic’s 17 official skills, see The rule vs the practice.
답글 남기기