Building Claude Code skills and plugins that actually get used

Most teams adopt Claude Code by typing better prompts. That works for a week. Then the same explanation gets typed for the fortieth time, slightly differently each time, and the quality of the output depends on who wrote the prompt and how tired they were.

A skill is where that stops. It is a procedure written down once, loaded when relevant, and invoked by name.

A skill is judgement, not documentation

The most common mistake is writing a skill that describes a capability. “Handles deployments” is useless. The model already knows what a deployment is.

What it does not know is your judgement. Which environment to check first. That the staging database is shared, so a destructive migration needs a heads-up in Slack. That a failing health check in the first 60 seconds means wait, and a failing one at 5 minutes means roll back. That the rollback command is not the one in the README because the README is out of date.

That is the content. A skill is the thing you would say to a competent new hire on their first day, written down so you never have to say it again.

If a skill contains nothing you would not find in public documentation, delete it. It is costing context and adding nothing.

Write the trigger before the body

A skill that never fires is worse than no skill, because you believe you are covered. Most skills fail here, not in the instructions.

The description is what gets matched against the task. It needs the words a person would actually use, including the messy ones. Not “performs database schema migrations” but something that also catches “add a column”, “change the table”, “the migration failed”, “roll back the schema”.

Write the trigger by listing five real sentences someone would type, then making sure each one obviously matches. If you have to squint, so will the model.

State the negative case too. “Use this for schema changes, not for seed data - that is seed-data.” Boundaries between similar skills are where misfires cluster, and one sentence prevents most of them.

Narrow beats broad, every time

A skill covering “content” that handles blog posts, newsletters and social copy will be mediocre at all three. It has to open with a decision tree, and every branch dilutes the instructions for the others.

Three skills with sharp triggers beat one with a decision tree. They are easier to write, easier to test, and easier to fix, because when one produces a bad result you know exactly which file to edit.

The test: if the first line of your skill is a question about which mode to operate in, it should be two skills.

Plugins are skills with a distribution problem solved

A skill in your own directory helps you. A plugin bundles skills, commands, agents and hooks so a team installs one thing and gets a working setup.

This matters more than it sounds for adoption. The gap between “here is a folder of files, copy them into the right place” and “install this” is the gap between a tool three people use and a tool the whole team uses. Packaging is not overhead; it is most of the adoption problem.

Version them. A skill that silently changes behaviour under someone who depends on it burns trust faster than a skill that never existed.

Make the skill verify itself

The most expensive failure mode is a skill that reports success without checking. It propagates: everything downstream builds on a foundation nobody confirmed.

Every skill should end by running something real. The test suite. The build. A query against actual state. “I updated the config” is a claim. “I updated the config and the build passes” is a fact.

This matters more with agents than with people because an agent states completion with total confidence either way. Confidence carries no information, so the check has to be mechanical.

Let it fail loudly

Resist making skills resilient by having them work around problems. A skill that quietly falls back to a different approach when the first fails produces work you cannot reason about, and hides the failure until it surfaces somewhere expensive.

Fail fast, say what failed, stop. A stopped agent with a clear error costs minutes. An agent that quietly took a different path costs however long it takes to notice, plus everything built on top in the meantime.

How to know a skill is working

Not “did it run”. Whether the correction rate dropped.

If you find yourself giving the same feedback after a skill runs, the skill is incomplete and your correction is the missing content. Put it in the file. The skill should get better every time you catch something, and the number of things you catch should fall.

That loop is the whole point. A prompt is a conversation you have again tomorrow. A skill is a conversation you never have twice.

Claude Code skills and plugins: turning a playbook into a command