Skills: Procedures vs Abilities
Every skill you install is either something you invoke or something the model decides to invoke on its own — and only one of those costs you context on every single turn, forever
One file, two completely different jobs
A Claude Code skill looks like one thing — a folder with a `SKILL.md` in it. But it can play one of two very different roles, and mixing them up is how you end up with either a skill nobody uses or a skill that silently taxes every conversation you'll ever have.
You type /tdd or say "run the deploy checklist." You already decided this is the task. The skill is a fixed recipe that runs start to finish. Its full body only loads into context the moment you call it.
You never type a command. The model reads your message, compares it against every installed skill's description, and decides for itself whether one applies. For that to work, every description has to sit in context on every turn — whether it fires or not.
A procedure is free until called. An ability is a standing line item in every prompt you'll ever send — read, weighed, and mostly discarded, over and over, for as long as it stays installed.
You already have both kinds installed
You don't need a hypothetical example. Two of the engineering skills already on your machine (~/.claude/skills/) show the split in their own frontmatter.
---
name: setup-matt-pocock-skills
description: Configure this repo for
the engineering skills...
disable-model-invocation: true
------
name: diagnosing-bugs
description: Diagnosis loop for hard
bugs and performance regressions.
Use when the user says "diagnose"
or reports something broken...
---Same folder structure, same `SKILL.md` filename, completely different contract with the model.
The tax you're already paying
Every session, before you type a word, Claude Code hands the model a catalog: every installed skill's name and description, so it can decide which ones might apply to whatever comes next. That catalog isn't free.
Counted directly from ~/.claude/skills/: 174 skills, each with a SKILL.md frontmatter description. Just those descriptions total roughly 50KB of text — loaded and parsed by the model on every single turn, whether any of them is relevant or not. (Check your own count before quoting — this grows every time a skill gets added.)
That's the cost structure Pocock is pointing at: an ability isn't priced once at creation time, it's priced continuously, for the entire lifetime of the skill. A procedure skill with a bloated body costs you nothing until you call it. An ability skill with a bloated description costs you a little, always, on top of every other ability competing for the model's attention in that same catalog.
Every description is real context, every turn — cache-eligible, but still parsed and weighed.
More descriptions in the catalog means more chances for two similar ones to collide, or for the right one to get missed.
One vague ability is a rounding error. A hundred vague abilities is a catalog nobody, human or model, can reason about.
How to write an ability that pays off
Given that cost, an ability skill needs to clear a higher bar than a procedure. Four checks before you flip it from a command to something the model auto-triggers:
diagnosing-bugs says "Use when the user says diagnose/debug this, or reports something broken/throwing/failing/slow" — concrete phrases the model can pattern-match. "Helps with code quality" would either never fire or fire on everything.
If the situation that needs this skill comes up constantly and is easy to recognize from the wording alone, the standing tax is worth it. If it comes up once a quarter, you're paying every day for a payoff you get four times a year.
Only the frontmatter — name and description — sits in the permanent catalog. The full instructions load once the skill actually fires. Keep the frontmatter tight; put the weight in the body, or in files the body points to.
If you'd happily remember to type /diagnose yourself every time, it's a fine procedure — ship it as a command and stop there. Promote to an ability only when you've noticed you (or the model) keep needing it without anyone remembering to ask.
Start every new skill as a procedure — user_invocable: true, no auto-trigger. Only add model-invocation once you've watched yourself reach for it repeatedly, unprompted, across real sessions. That's evidence, not a guess.
Invocation is a design decision, not a default
It's tempting to make every skill model-invoked so you "never have to remember the command." That instinct is backwards. Every ability you add makes every other ability slightly harder for the model to find and slightly more expensive to carry. The catalog is a shared resource — every skill in it is spending from the same budget.
The discipline isn't "write fewer skills." It's match the invocation mode to the actual cost/benefit: procedures for anything you're willing to ask for by name, abilities reserved for the handful of situations where auto-detection genuinely outperforms you remembering. Most of what you'll build should stay a procedure. That's not a limitation — it's the cheap, controllable, exactly-when-you-want-it default.
Procedure or ability check
Three situations. Decide which invocation mode fits — and why it costs what it costs.
You write a skill that migrates a legacy config format — something you'll run once, maybe twice, ever, on purpose.
How should it be invoked?
An ability skill's description reads: "Helps improve your code." No trigger phrases, no scenario.
What's the actual problem with this?
You keep pasting stack traces into chat and asking for a systematic diagnosis, several times a week, and it's always obvious from the message alone that this is what's needed.
Is this a good candidate for an ability skill?
Open ~/.claude/skills/, pick three skills, and check their frontmatter. For each: is it model-invoked, and does its description have a trigger distinctive enough to earn the tax it's charging every session? If not, that's a candidate to tighten — or demote to a procedure.