1. A procedure you were tired of repeating
A skill is a folder of instructions. The main file is SKILL.md, with a name and a description, plus any notes or scripts the procedure needs. Claude sees the name and the description all the time. It loads the rest only when it uses the skill. That is cheaper than pasting the same page into every session.
A custom command is a saved prompt you invoke by name. You pay a step, and you get predictability. A skill the model invokes by itself is more flexible and less predictable. Choose on purpose. Do not make everything automatic because the menu looked empty.
2. The description is the trigger
Claude decides whether to use a skill from the name and the description. Say what it does and when. List the situations, the phrases, and the file types. Skills usually fail by not triggering, not by triggering too often.
Test it. Try realistic requests, including some that should not trigger it. If it misfires, fix the description, not the body. The body never ran.
3. Write it from your work, not from a blank prompt
Do not ask a model to invent a skill from nothing. The draft will be generic. Start from a workflow you have actually done: a review comment you keep making, a release check, an interview that ends in a plan. Dictate the steps in your own words, or let Claude interview you, and only then let it structure the file.
The model already knows how a popular framework works. It does not know how your team reviews, deploys, or reports. A skill earns its place by capturing what is specific. The useful starters are boring: interview me, then write the plan; review this as a skeptical senior and rank the findings; run the tests and say what changed.
4. Read it, then cut it
Read every line of a skill you adopt, including one a teammate or a model wrote. Unread skills are a common reason agents misbehave. Treat a third-party skill as software you are installing. It can run code and see files.
Keep the main file short. The guide’s aim is roughly five hundred lines or fewer, and shorter is better. Put the steps in the main file and the long reference beside it, to be read only when needed. For a fragile calculation, give Claude a script to run instead of asking it to improvise the arithmetic. Delete lines like “be thorough.” Delete a line and see if anything changes. If nothing changes, the line was decoration.
5. What to try next
Pick one correction you have made twice. Write the steps while you still remember them. Give it a description a stranger could match. Try one request that should trigger it and one that should not.
When the work splits across people or folders, isolate it: parallel work, and the tools you connect.