Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Write your first Claude Code Skill from scratch: SKILL.md, scripts, and verification

A Claude Code Skill is a folder with a SKILL.md: frontmatter that says when to use it, a short body that says how. This guide walks through writing one from scratch — the changelog-entry example, where to put it, and the three checks that prove it works.

A person checking off items in a notebook checklist beside a laptop, a cup of coffee and a calculator on a wooden desk

Where this guide sits: how it differs from the Skill articles already published

First, a boundary statement, so this guide does not collide with what is already published. The site already carries agent-skills-vs-prompts, which is a comparison piece: when to use a Skill and when to use a prompt. It does not teach you how to write one. There is also build-first-mcp-server-guide, which teaches you to build an MCP server from scratch — a different extension mechanism. MCP connects an agent to external tools and data sources; a Skill captures a workflow and knowledge for the agent. They solve different problems. And there is a news article introducing the Ponytail Skill, which presents a finished Skill product rather than a writing tutorial.

This guide is a hands-on tutorial: writing a working Claude Code Skill from scratch, end to end — when it is worth writing, how to write SKILL.md, how to organise scripts and reference files, where to put it, how to verify that it actually gets invoked, and the five most common mistakes. By the end, you should be able to write your first Skill for the workflow you repeat most, within an hour, and know how to tell whether it is any good.

The sources are two official documents: Claude Code's Skills documentation (code.claude.com/docs/en/skills.md) and the Agent Skills open standard (agentskills.io). The mechanisms mentioned here — file locations, invocation, progressive disclosure, dynamic context injection — all come from those two documents. The practical advice (how short a Skill should be, when to split files) is derived from those mechanisms, and the text says which parts are documentation and which parts are advice.

When a Skill is worth writing: three signals

Not all repeated work deserves a Skill. Claude Code's documentation gives a direct test: write a Skill when you keep pasting the same instructions, the same checklist, or the same multi-step procedure into chat. Another signal is when a section of your CLAUDE.md has grown into a procedure rather than a fact — facts belong in CLAUDE.md, loaded with every session; procedures belong in a Skill, loaded only when used.

More concretely, any of three signals is enough to start. The first is "I have said this three times already". Every release, for example, you tell the agent the same thing: run the tests, check the CHANGELOG, confirm the version bump, then ship. By the third time, that paragraph belongs in SKILL.md, not in chat. The second is "this flow has a fixed order, and getting the order wrong causes damage". A release checklist that must run tests first, then look at database migrations, and only then publish is a perfect Skill candidate: a person dictating it from memory can skip a step; a file cannot. The third is "every new person (or every new session) has to be taught again". When everyone on the team has to explain "this is how our release process works" to the agent separately, that knowledge lives only in people's heads. Write it as a project Skill, commit it, and nobody has to teach it again.

The reverse is also true, and there are three cases where a Skill is not worth writing. One: the flow will only run once. Writing a Skill costs time too; for a one-off, saying it clearly in chat is cheaper. Two: the flow changes every day. A Skill's value lies in stability; if today's steps are obsolete tomorrow, maintenance costs more than dictating each time. Wait until the flow settles. Three: the thing is a fact, not a procedure. "This project uses pnpm, not npm" fits in one line of CLAUDE.md. It does not need a Skill.

A simple test: if you can say in one sentence "every time we do X, we follow steps A, B, C", and A, B, and C will not change for the next month, write it. If you cannot say that, or the steps change weekly, do not write it yet.

What a Skill actually is: one card plus one folder

According to the Agent Skills open standard, a Skill is at its core a folder containing a SKILL.md file. That file has two parts: YAML frontmatter between --- markers, which tells the agent what the Skill is and when to use it, and Markdown content below, which is the instruction the agent follows when the Skill runs. The folder can also hold scripts (scripts/), reference material (references/), and templates (assets/). The structure looks like this:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Skills work through "progressive disclosure", in three stages. Stage one is discovery: at startup, the agent loads only each Skill's name and description — just enough to know when it might be relevant. Stage two is activation: when a task matches a Skill's description, the agent reads the full SKILL.md into context. Stage three is execution: the agent follows the instructions, optionally running bundled code or loading referenced files as needed. In other words, the body of SKILL.md costs almost no context until the Skill is actually used. That is why you can keep many Skills installed without choking your context: the discovery cost is a name plus one sentence.

That mechanism sets the first rule of writing Skills: the description is the most important part, and the body is second. If the description is bad, the agent will not recognise the Skill at discovery time, and however good the body is, nobody will ever read it. Claude Code's documentation says it plainly: the description helps Claude decide when to load the Skill automatically. So when you write a description, do not write "a very useful tool". Write what the Skill does and when to use it, and include the trigger situations — for example, "use when the user asks what changed, wants a commit message, or asks to review their diff".

The second rule is that the SKILL.md body should be short, with detail pushed into references/. The body only loads after activation, so a long body eats a large chunk of context at once; and when an agent reads a very long instruction, it tends to execute the first half and drop the second. The right shape is: the body says what to do, in what order, and what counts as done. Commands, tables, and long background go into files under references/, and the body just says "read references/xxx.md when you need it". Scripts work the same way: do not paste a whole script into the body; put it in scripts/ as an executable file and write "run scripts/check.sh" in the body.

Writing a Skill from scratch: the changelog-entry example

Here is the full flow, using a genuinely usable example. Suppose your project needs a CHANGELOG entry with every release, and you want the agent to draft one from the current changes — fixed format, consistent wording. The Skill will be called changelog-entry.

Step one: create the folder. A personal Skill (only for you, available in all projects) lives under ~/.claude/skills/; a project Skill (committed to the repository, shared with the team) lives in .claude/skills/ at the project root. Start with a personal Skill for this example; decide later whether to move it into a project:

mkdir -p ~/.claude/skills/changelog-entry

Step two: write SKILL.md. Two parts. First the frontmatter — name and description are required:

---
name: changelog-entry
description: Draft a CHANGELOG entry from uncommitted changes. Use when the user asks to write a changelog entry, summarize what changed for a release, or prepare release notes from the current diff.
---

## Current changes

!`git diff HEAD --stat`

## Instructions

1. Read the diff summary above. If it is empty, say there are no uncommitted changes and stop.
2. Group the changes by area (feature, fix, docs) based on the files touched.
3. Draft one bullet per group, in the past tense, naming what changed and why it matters to users. Do not invent changes that are not in the diff.
4. Ask the user to confirm or edit before writing anything to CHANGELOG.md. Never write to the file unprompted.

Three things in there are worth explaining. First, the description states what it does and when to use it, and deliberately lists three trigger phrasings (write a changelog entry, summarise changes for a release, prepare release notes from the diff), because users phrase the same request differently each time — the more trigger phrasings in the description, the higher the chance the agent recognises it at discovery time. Second, the line !`git diff HEAD --stat` is dynamic context injection: Claude Code runs the command and substitutes its output before the agent sees the Skill, so the agent reads the diff summary already inlined rather than a vague instruction to "go and check the diff". The answer is grounded in the actual working tree. Third, step 4 deliberately adds a guardrail: drafting is the agent's job, writing to the file is the human's decision.

Step three: decide whether to add scripts and reference files. This example is simple enough not to need a script. But if your changelog has a fixed format — every entry must carry an issue number, say — put the format in references/format.md and add one line to the body: "follow the format in references/format.md". If your project requires tests to pass before a changelog is written, add scripts/precheck.sh and write "run scripts/precheck.sh first; stop if the tests fail". The rule is: the body should fit on one screen. Anything longer gets split out.

Step four: test. Open a Git project with some changes, start Claude Code, and invoke it directly first: type /changelog-entry and see whether it drafts the entry the way you specified. Then test automatic triggering: ask the same thing in different words, for example "what changed in this release, write me a changelog entry", and see whether the agent loads the Skill on its own. Test both ways: direct invocation checks "are the instructions right"; automatic triggering checks "is the description clear enough". If automatic triggering does not fire, the problem is almost certainly in the description — go back and add trigger scenarios instead of rewriting the body.

Progressive disclosure in three stages: at startup only the name and description load, on a matching task the full SKILL.md is read, and during execution scripts and reference files load as needed

Where to put it: personal, project, or plugin

Location decides who can use the Skill. Claude Code's documentation lists several. A personal Skill goes in ~/.claude/skills/ and works in all your projects on the machine — but cloud sessions (Cowork, scheduled cloud tasks) do not read your machine's personal Skills; to use one there, enable it for your claude.ai account. A project Skill goes in the repository's .claude/skills/, is committed, and everyone who pulls the repo gets it. In a monorepo you can also place .claude/skills/ in a subdirectory, where it applies only to sessions started in or below it. A plugin Skill travels with its plugin and is available wherever the plugin is enabled, invoked with the plugin prefix, for example /plugin-name:skill-name.

A practical habit: keep a new Skill in your personal location for two weeks first. Once you are sure it is genuinely useful and its steps are stable, move it into the project to share. Doing it the other way round causes trouble: a half-finished Skill committed to the project interrupts the whole team, and every edit has to consider everyone else's use. Personal first, project second is the cheapest order.

When names clash, there is a precedence order: enterprise beats personal, and personal beats project. Your own Skill replaces a bundled command of the same name, but not its aliases. If you write a project Skill called code-review, it replaces the built-in /code-review, but the built-in alias /review still runs the built-in one. Also, do not name a folder synced, and do not start a name with anthropic-skills — both are reserved and will not load.

One more placement detail: the loading direction also matters. In a monorepo, Claude loads project skills from the directory you start in, up through its parents to the repository root; when you read or edit files in a subdirectory, that subdirectory's skills load too. Worktrees behave the same way: from version 2.1.277, if a worktree has no project skills of its own, Claude loads the ones from the main checkout. So where a skill actually takes effect depends not only on where you put it, but also on which directory you started Claude in. Thinking about that when you write the skill beats discovering later that it shows up where it should not.

Verification and maintenance: done is not the end

A finished Skill needs to pass three checks. The first is direct invocation: does /changelog-entry run, and is the output in the format you want? The second is automatic triggering: phrase the same request three different ways and see whether the agent finds the Skill on its own. If it misses once out of three, go back to the description — more trigger scenarios, written more concretely, raise the hit rate. The third is the "newcomer test": ask someone who has never used the Skill (or start a fresh session and pretend you do not know it exists) to get the agent to do the task from the task description alone, and see whether the agent reaches for the Skill by itself. If it fails the third check, the Skill only works for the person who wrote it — the description is hiding jargon only you know.

Claude Code's built-in /doctor command helps with part of this. It reports Skills that are never used, Skills that duplicate content in CLAUDE.md, and suggests moving procedures that have grown inside CLAUDE.md into Skills. /doctor prompt-audit checks your CLAUDE.md files, Skills, and other configuration for outdated or conflicting instructions. Make it a habit: run /doctor once a month, delete Skills nobody uses, and fix conflicting instructions.

The easiest maintenance mistake is "write it and forget it". The flow changes, the Skill does not follow, and the agent keeps working from outdated steps — and you will hardly notice, because it still looks like it is working normally. So every Skill needs a shelf-life mindset: when the flow changes, update the Skill immediately; when nobody uses the flow any more, delete the Skill. Deleting a Skill costs nothing; keeping an outdated one is genuinely expensive, because it re-teaches the wrong procedure to the agent every time it fires.

Five common mistakes

The first is a vague description. "Helps you be more productive" or "handles various development tasks" says nothing, and at discovery time the agent has no way to judge when to use it. A description should read as "what it does + when to use it", ideally with trigger scenarios. A usable test: read the description to a colleague who does not know the Skill. Can they say "oh, this is for before a release"? If yes, it passes. If not, rewrite it.

The second is stuffing everything into SKILL.md. Some Skills run to over a thousand words of body text — background, history, commands, caveats. An agent reading that far starts dropping steps near the end. The body should hold only the skeleton: what to do, in what order, what counts as done. Details, tables, and long background go into references/; scripts go into scripts/; the body names the files.

The third is hardcoding project paths into a personal Skill. A personal Skill loads in every project, so "go to /Users/xxx/myproject to find the config" breaks the moment you switch projects. Personal Skills should hold only generic flows. Project-specific paths, commands, and conventions go into project Skills — or get resolved with dynamic context injection (for example !`git rev-parse --show-toplevel`) instead of being written in literally.

The fourth is using a Skill for a job that belongs to something else. If you need live data from an external tool, consider an MCP server first. If it is a single fixed command, a command file under .claude/commands/ is enough — command files now share the same frontmatter as Skills, and the old format still works. A Skill's place is "multi-step procedure plus knowledge you reuse". Do not use it to do a command's or an MCP server's job.

The fifth is writing a Skill and never verifying it. Direct invocation works, so you assume it is done — but automatic triggering was never tested. The result is a Skill that only gets used when you remember to call it by name; the agent itself never thinks of it. Remember the three checks: direct invocation, automatic triggering with rephrased requests, and the newcomer test. Only when all three pass is the Skill actually finished.

Which Skill to start with

Do not start with the most complicated flow. Pick the thing you repeated three or more times this week, with fixed steps and a low cost of getting it wrong: a pre-release checklist, writing commit messages, tidying a diff, preparing release notes. Write one, run it for two weeks, see whether it genuinely saves time, then write the second. The goal of the first Skill is not "write a perfect Skill" but "complete the loop once": write, test, fix, test again.

If you already have a checklist sitting in some document, that is an even better starting point: move the checklist into SKILL.md, add a description, attach one dynamic-context line (for example !`git status --short`), and you already have a working Skill. The rest is gradual polish: a sharper description, a cleaner body, a script added here and there. A Skill is a tool that gets smoother with use, not a piece of work finished in one sitting.

One last reminder: a Skill's real value is not in writing it, but in it being used. A perfectly written Skill that is never triggered automatically might as well not exist. In the two weeks after writing one, watch deliberately: does the agent reach for it on its own, without you naming it? If yes, your description is right, and the Skill has grown from "your notes" into "the agent's tool". If not, go back and fix the description, not the body — most Skills fail because of those two lines of description, not the dozens of lines of body underneath.

Views 5Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding
Real photo: a Casio scientific calculator on a wooden desk showing 123456789 + 987654321 = 1111111110, beside handwritten math notebooks, a pen, a mug, and a laptop edge
Guide
Don't let 0.1 + 0.2 break your bill: JavaScript numbers and Math, explained plainly

Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.

Tool TipsFrontend EngineeringAI Coding
Real photo: a woman in an office sticking colorful sticky notes in rows on a white wall, holding a pink note in her hand
Guide
Stop shimming with margins: Flexbox one-dimensional layout, explained plainly

Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.

Developer WorkflowFrontend EngineeringAI Coding