Denshin / Blog / AI
What goes into a good Claude skill
A skill is a folder with a SKILL.md file, and most of its quality comes from a few unglamorous choices: a description that matches real requests, short instructions, scripts for anything with a right answer, and testing it like code.
Denshin Engineering · Product & Engineering · 18 October 2026 · 4 min read
A skill, in the Claude sense, is a folder. That is the least exciting and most useful thing to understand about it. Inside the folder is a file called SKILL.md, and optionally some scripts, reference documents and templates. When a request matches what the skill is for, Claude reads the instructions and follows them. When it does not, the skill costs almost nothing.
Anthropic published the format as an open standard in December 2025 (the spec lives at agentskills.io), and a long list of agent tools now read it, including Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI and VS Code. So a skill you write today is not tied to one product, which is a good reason to write it carefully.
The anatomy
quotation-drafting/
SKILL.md
references/
rate-card.md
terms-and-conditions.md
scripts/
calculate_totals.py
assets/
quotation-template.docx
SKILL.md opens with a short YAML header. Two fields are required: a name (up to 64 characters) and a description. Below that is ordinary Markdown, which is where the instructions go.
---
name: quotation-drafting
description: Draft a customer quotation from an enquiry using our rate card,
standard terms and GST rules. Use when asked to prepare, price or revise a
quotation or proposal for a customer.
---
The reason the format works is what the spec calls progressive disclosure. At startup the agent loads only each skill's name and description, roughly a hundred tokens apiece. The full instructions load when a task matches. Files in references/ or scripts/ load only when the instructions point to them. You can install dozens of skills without stuffing the context window, which is the wall every long system prompt eventually hits.
The description is the trigger
The most common reason a skill "doesn't work" is that it never runs. The model decides whether to use a skill from the description alone, so the description has to read like the requests people will actually type. Name the task, use the nouns your team uses, and say when to reach for it. "Helps with sales documents" will rarely fire. The quotation example above will.
If there is a neighbouring skill it could be confused with, say when not to use it as well.
Keep SKILL.md short
The instructions file should read like a page you would hand a capable new colleague on their first day: the steps, the order, the usual mistakes, and where to look for more. Everything bulky goes in reference files. The full rate card, the terms, the style guide, the list of forty product codes: separate files, each mentioned by name in SKILL.md with a line about when it is needed.
A rough test: if your SKILL.md scrolls for more than a few screens, it is probably doing the reference files' job.
Put the deterministic parts in scripts
Models are good at reading an enquiry and deciding which line items apply. They are less trustworthy at adding up eleven numbers across two tax rates. Anything with a single right answer (totals, date arithmetic, file conversion, checking a GSTIN format, pulling data from an API) belongs in a script the skill tells the agent to run. The script gives the same answer every time, and you can test it like any other code.
Show what good looks like
One real example of a finished output does more than a page of adjectives. If the skill produces something (a quotation, a test report, release notes), include a good example. If there is a common failure, add a short bad example with a note on what is wrong with it. Strip anything confidential first.
Treat it like code
A skill is a piece of your process written down in a form a machine will follow literally. It deserves what code gets: version control, a named owner, a changelog when the rate card or the policy changes, and a review before it reaches the whole team. A skill that still encodes last year's pricing is worse than no skill, because it is confidently wrong.
Testing is not complicated. Collect ten or so real requests, some that should trigger the skill and some that should not, and run them. Check that it fires when it should, stays quiet when it should, and that the output is something you would actually send. Repeat after every meaningful edit.
What not to make into a skill
A skill that is just a prompt with a title ("You are an expert marketer, write great copy") adds nothing the model was not already doing. The ones worth having carry something the model cannot know on its own: your process, your documents, your rules, your tools. If you could delete the skill and get the same output by asking nicely, delete it.
Be careful with skills from elsewhere, too. A skill can ship scripts that run on your machine, which makes a third-party skill closer to a dependency than a document. Read it before you install it, as you would any package. The wider risk is covered in our prompt injection checklist.
Building skills around a team's own processes is part of our Claude Skills work, but the format is simple enough that most teams can write a first one in an afternoon. Start with the task someone explains to a new colleague every month.
Tags: Claude Skills, Agent Skills, Claude, AI Agents
All posts · Work with Denshin