# How to write a Claude Skill your team will actually use **Author:** John Morabito (Founder, /winston) **Published:** September 20, 2026 **Reading time:** 11 minutes **Canonical:** https://www.winstondigitalmarketing.com/playbooks/how-to-write-a-claude-skill/ Most Skills that fail do not fail on the procedure. The steps are fine. The rules are right. The folder sits in the repository and never runs, because the model never decided it was relevant, or because somebody read two lines of it and went back to doing the job by hand. That is an authoring problem, and it happens in a small number of specific, fixable places: a description written as a summary instead of a trigger, a body that assumes context the reader does not have, a file too long to be worth loading, and a test that got rigged without anyone meaning to rig it. This page is about writing the file. If you are still deciding whether the thing you need is a Skill at all, the prior question is whether the model is missing knowledge or missing access, and that is [Claude Skill or MCP server](https://www.winstondigitalmarketing.com/playbooks/claude-skill-vs-mcp-server/). If you have decided and you want to know which workflows are worth packaging first, that is [Claude Skills for SEO teams](https://www.winstondigitalmarketing.com/playbooks/claude-skills-for-seo-teams/). What follows is how we write the ones we ship. ## The four parts of a Skill A Skill is a folder. Four kinds of things live in it, and each one answers to a different reader. ``` monthly-performance-report/ SKILL.md <- frontmatter plus the procedure references/ voice-guide.md <- read only when the procedure says to report-example.md scripts/ build_windows.py <- run, never read as advice ``` - **The frontmatter.** A name and a description at the top of SKILL.md. The description is the only part the model sees before it decides whether to open the folder at all. - **The body.** The procedure itself, in plain language, read by a model that is already mid-task. - **Reference files.** Material the model reads when the procedure tells it to: a voice guide, a taxonomy, a finished example, a format spec. - **Scripts.** Small programs for the steps that have to come out identical every run. The model runs these rather than reading them for guidance. Most of what goes wrong in authoring is a question of which of those four a given fact belongs in. Most of what goes wrong in adoption happens in the first one. ## The description decides whether any of the rest runs Every other line in the file is read after the decision to use the Skill has already been made. The description is read before it, and it is the model's entire basis for that decision, evaluated against a request it has never seen, with the rest of the folder still closed. Which means a beautifully written procedure behind a vague description is a file nobody opens, and you will never see the failure, because nothing happens. There is no error and no wrong output. The work carries on being done by hand. So write the description as a trigger, not a summary. A summary describes what is inside. A trigger describes the moment you want the folder opened. ``` --- name: monthly-performance-report description: A comprehensive workflow for client reporting. --- ``` That one will sit there for a year. Compare: ``` --- name: monthly-performance-report description: Use when building a monthly client performance report, or when asked to write up last month, do the monthly, pull together how a client did in a period, or summarize performance for a date range. Not for one-off questions about a single campaign. --- ``` Three things separate the second from the first. - **It names the situation, not the artifact.** The model is matching the description against a request, and requests describe situations rather than deliverables. - **It uses the words people actually type.** Your team says "do the monthly." Nobody on earth types "generate a periodic performance summary." Put the real phrasing in, including the sloppy version, because the sloppy version is what you will get at 4pm on a Friday. - **It says where the boundary is.** A line about when not to reach for this is as informative as the trigger, and it is the thing that stops a Skill from firing on every adjacent request until people start ignoring it. The test for a description: cover the rest of the file and read that sentence alone. Could you tell, from those words only, which requests should open this folder and which should not? If you cannot, neither can the model, and it has less context than you do. ## Write for someone reading it cold The body of a Skill gets read mid-task by a reader with no memory of the conversation where you decided any of it. Everything that was obvious in the room is invisible on the page. That is the whole difficulty, and it produces five habits. **Name things all the way.** "The sheet," "the usual export," "our template" resolve to nothing outside your head. Say which file, where it lives, what it is called, and what it looks like when it is the right one. **Put each rule next to the step it governs.** A constraints section at the bottom of the file gets read after the mistake has already been made. If prices have to be copied character for character, that belongs on the line where prices get written, not in a list of principles three screens down. **State the exception, or one will get invented.** "Round percentages to whole numbers" is an instruction that will eventually round a compliance field. "Round percentages to whole numbers, except in the dosage and potency fields, where you copy the value exactly as it appears" is an instruction that holds. Anywhere you would say "well, obviously not in that case," write the case down. **Use the imperative.** "Open the export, drop blank rows, confirm the date range matches the requested period" survives being read cold. "It is generally a good idea to sanity-check the data first" does not survive anything. **Include one finished example.** Half a page of a real output, in a reference file, does more than three paragraphs describing what good looks like. It also gives you something to check the test runs against, which you will want later. ## Say whether you wrote a procedure or a pattern There are two kinds of Skill, and the difference decides what someone should do when they hit a step they would have done differently. A **rigid procedure** is one where deviation is the failure. Compliance checks, anything with a legal or financial consequence, anything whose entire value is that every run comes out the same. These get numbered steps and an explicit line saying the order is not adaptable and the validation step is not optional. A **flexible pattern** is judgment you are trying to transfer. How to structure an argument, what makes a finding worth writing up, how to decide which of twelve issues actually matters. These get principles with examples, plus a line saying the examples illustrate the thinking rather than enumerate the cases. The failure is not choosing. A Skill that reads like a procedure but was meant as a pattern gets followed straight off a cliff on the one job that did not fit the mold. A Skill that reads like a pattern but was meant to be rigid gets improvised around in exactly the place you most needed it not to be. Both are invisible until the run where it matters. The fix costs one sentence near the top of the file. Either "follow these steps in order and do not skip step 4" or "these are patterns rather than a script, so adapt the structure to the piece in front of you." Say it plainly, because a model reading a numbered list will assume the numbers mean something whether you meant them to or not. | Dimension | Rigid procedure | Flexible pattern | |---|---|---| | What it encodes | A process that must repeat exactly | Judgment about how to approach a class of work | | How to write it | Numbered steps, explicit gates | Principles with worked examples | | What to say about deviation | Do not deviate; the order is the point | Adapt to the case; the examples are illustrative | | Good fits | Compliance checks, schema validation, anything with a number in it | Editorial structure, prioritization, what counts as a finding | | Failure when mislabeled | Improvised around on the one run that needed it exact | Followed literally into a case it was never meant for | | What to test | Two runs on the same input produce the same output | Two different inputs produce sensibly different outputs | ## Keep it small enough to be worth loading Loading a Skill spends context that the actual work then does not get to use. Writers treat length as thoroughness. A model treats it as overhead, and the bill lands on the job you were trying to help. The split is mechanical. Read your draft and mark every line the model needs on an ordinary run, the one where nothing unusual happens. Those lines stay in SKILL.md. Everything else is a reference file, named at the point in the procedure where it is needed. Reference files are the right home for long lists like banned terms or a category taxonomy, format specifications, worked examples, and anything you would otherwise find yourself pasting in every single time. The procedure points at them by name at the moment of use: "before drafting, read references/voice-guide.md." That placement matters more than it sounds like it should. A bibliography at the end of the file gets loaded either never or always, and both are wrong. A useful gut check: if you would not read the whole SKILL.md before starting the task yourself, do not ask a model to. ## Scripts for the parts that have to come out identical Anything exact should be a script rather than a paragraph. Parsing an export, arithmetic, computing a date window, validating schema, producing a diff. A model asked to do an exact transform in prose will do it correctly most of the time, and "most of the time" is the wrong reliability standard for a number that goes in front of a client. The signal is whether you would be annoyed to find the step done slightly differently on two runs. If a human doing the same job would open a spreadsheet instead of thinking about it, it is a script. The instruction in SKILL.md then shrinks to one line: run this, and here is what to do with what comes back. This also makes the Skill cheaper to review. A reviewer can read the procedure to check the judgment and read the script to check the math, instead of trying to do both at once against a wall of prose. ## Test it on a request nobody rehearsed The test everybody runs is to open a session, say "use the reporting Skill," and watch it work. That tests the procedure and proves nothing whatsoever about the description, which is the part most likely to be broken. You told it which folder to open. In real use, nobody will. The test that matters is to type the thing you would genuinely have typed. "Can you put together last month for Northside?" Then watch whether the Skill fires on its own. If it does not, you have found the actual defect, and it was never in the steps. Four more worth running before you tell anyone it exists. 1. **The near miss.** A request that sounds related but should not trigger it, like a question about one campaign's spend. Does the Skill stay closed? A Skill that fires on everything gets turned off. 2. **The cold run.** Hand it to somebody who did not write it and let them describe their own job in their own words. Their vocabulary is the vocabulary the description has to match, and it will not be yours. 3. **The interruption.** Start the Skill and throw in something the instructions did not anticipate: a missing column, a client with two brands, a period with no data. Skills break at the edges, not at the top. 4. **The output check.** Read the result against the finished example you included. If you find this step hard, it is because you did not include one. Write down what you changed after each round. In our experience it is nearly always the description, which is a good argument for writing the description last, once you know what the Skill actually turned out to do. ## Version it once more than one person depends on it A Skill only you use can be edited on a whim. The moment a second person runs it, editing it is changing how somebody else's job works, and that deserves the same handling as any other shared thing. - **Keep it in version control.** The diff is what answers "why did this month's report come out different from last month's," which is a question you will get. - **Put a date and a one-line note at the top of SKILL.md.** The model does not care. The person who inherits the file in eight months cares a great deal. - **Update it the same week the process changes.** A Skill describing a process that changed two quarters ago is worse than having no Skill, because it is confidently wrong and nobody thinks to check it. - **Name one owner.** A file that everybody owns goes stale on a predictable schedule. - **Rerun the realistic-request test after any substantial rewrite.** Descriptions drift while you are busy improving the body, and you will not notice until the Skill quietly stops firing. ## Where to start this week 1. Pick a job you have done more than three times and would be irritated to see done differently. That irritation is the specification. 2. Write the steps as you would explain them to a competent new hire who has never seen your files. 3. Cut everything the model does not need on an ordinary run into references/, named at the point of use. 4. Turn every exact transform into a script. 5. Add one finished example, a real one. 6. Write the description last, as a trigger, in the words people actually type. Then test it by typing the request you would really have sent, and hand it to a colleague and watch what happens. If you are not yet sure a job repeats often enough to deserve a folder, a prompt library is the cheaper first stop, and the prompts that get reused are exactly the ones worth promoting into Skills later. That path is in [building a prompt library for your marketing team](https://www.winstondigitalmarketing.com/playbooks/prompt-library-for-marketing-teams/). Writing the procedure down, splitting it into the parts a model should read and the parts it should run, and getting the description right so the thing actually fires, is the work behind our [custom GPTs and Skills service](https://www.winstondigitalmarketing.com/services/ai-marketing/custom-gpts-and-skills/). ## Frequently asked questions ### What makes a Claude Skill get used instead of ignored? The description in the frontmatter, far more than the quality of the procedure. That description is the only part of the file the model reads before deciding whether to open the folder, so it is evaluated against a request it has never seen with everything else still closed. A vague description means a Skill that never fires, and the failure is silent: no error, no wrong output, just the work continuing to be done by hand. Write the description as a trigger rather than a summary, name the situation instead of the deliverable, include the sloppy phrasing your team actually types, and state where the boundary is so it does not fire on every adjacent request until people stop trusting it. ### How long should a SKILL.md file be? Short enough that you would read the whole thing before starting the task yourself. Loading a Skill spends context the actual work then does not get to use, so length that reads as thoroughness behaves as overhead, and the cost lands on the job. The split is mechanical: mark every line the model needs on an ordinary run where nothing unusual happens, keep those in SKILL.md, and move everything else into reference files that the procedure names at the exact point they are needed. Long lists, format specifications, worked examples, and anything you would otherwise paste every time all belong in references rather than in the main file. ### What should the description field of a Claude Skill say? It should describe the moment you want the folder opened, not what is inside it. Name the situation rather than the artifact, because the model is matching against a request and not a deliverable category. Use the words people genuinely type, including the informal version, since "do the monthly" is what you will get on a Friday afternoon and not "generate a periodic performance summary." Add a line about when not to use it, because a stated boundary stops the Skill from firing on every related request. The check is to cover the rest of the file and ask whether that sentence alone tells you which requests belong to it. ### Should a Claude Skill be a rigid procedure or a flexible pattern? It depends on the work, and the real mistake is not saying which one you wrote. Write a rigid procedure when deviation is itself the failure: compliance checks, anything with a legal or financial consequence, anything whose value is that every run comes out the same. Write a flexible pattern when you are transferring judgment, like how to structure an argument or decide which findings matter. Then state the choice in one sentence near the top, because a model reading a numbered list will assume the order is binding whether you intended that or not. Mislabeled rigid Skills get improvised around exactly where precision mattered, and mislabeled flexible Skills get followed literally into cases they were never meant for. ### How do you test a Claude Skill? Not by telling it to use the Skill. That proves the procedure runs and says nothing about the description, which is the part most likely to be broken, because you supplied the decision the model is supposed to make on its own. Instead type the request you would genuinely have sent and watch whether the Skill fires unprompted. Then run the near miss, a related request that should not trigger it, to confirm it stays closed. Run a cold test with a colleague who did not write it and uses their own vocabulary. Interrupt a run with something the instructions did not anticipate, since Skills break at the edges rather than the top. Finally, read the output against the finished example you bundled.