How to Write a Claude Skill from Scratch

By Yanni Papoutsis | 7 min read | 2026-07-08

To write a Claude skill from scratch, you create a folder containing a SKILL.md file with YAML frontmatter (at minimum a name and a description), write the step-by-step instructions Claude should follow in the body, add any supporting scripts or reference files it needs, then package the folder as a .skill zip and test it in a fresh session. Nothing about this requires a build system or a compiler. A skill is plain text and, optionally, a few scripts.

This post opens a seven-part series on authoring skills in depth. It covers the full build from an empty folder to a working, installable skill. The rest of the series covers triggers, chaining multiple skills together, adding web search, wiring up MCP tool access, testing and eval, and publishing.

TL;DR: A Claude skill is a folder with a SKILL.md file at its root. The YAML frontmatter needs a name and a description -- the description is what Claude reads to decide when the skill is relevant, so write it in the third person with concrete trigger words, not marketing copy. The body of SKILL.md is the instruction set: numbered steps, rules, and examples, written the way you would brief a careful colleague who has never seen the task before. Keep the body lean and push long material (templates, deep reference tables, one-off scripts) into a references/, scripts/, or assets/ subfolder that Claude only opens when it needs to, a pattern called progressive disclosure. Once written, zip the folder with a .skill extension, share it in Cowork or drop it into a plugin's skills/ directory for Claude Code, then test it cold: open a brand new session, type a task the way a real user would phrase it, and confirm the skill actually loads before you trust it with real work.

What is a Claude skill?

A skill is a self-contained instruction set that Claude loads automatically when a task matches its description. Instead of re-explaining a workflow every session, you write it once as a SKILL.md file, and Claude pulls it into context the moment it recognises a matching task.

The minimum a skill needs is one file:

my-skill/
  SKILL.md

Most real skills grow a bit more structure once they carry examples, scripts, or long reference tables:

my-skill/
  SKILL.md
  references/
    edge-cases.md
    style-guide.md
  scripts/
    validate.py
  assets/
    template.docx

Only SKILL.md loads by default. Everything else loads on demand, which is why skills stay cheap to keep around even when you have dozens installed.

What do you need before you start?

Nothing beyond a text editor and access to Claude through Cowork or Claude Code. Skills are markdown and, optionally, small scripts, so there is no dependency install and no framework. If you plan to bundle scripts, have the runtime available (Python, Node, or bash), and if the skill will call external services, know which MCP connectors or tools it depends on so you can document that clearly rather than assume they exist.

How do you write a Claude skill step by step?

The short version: scaffold the folder, write the frontmatter, write the body, add supporting files only if needed, then test and package. Here is each step worked through.

Step 1: Create the folder

mkdir -p my-skill/references

Name the folder for what the skill does, lowercase with hyphens, matching the name field you will put in the frontmatter.

Step 2: Write the SKILL.md frontmatter

name: changelog-writer
description: Writes a structured changelog entry from a diff or a list of commits. Use when the user asks to summarise changes, write release notes, or draft a changelog entry. Trigger on words like changelog, release notes, what changed, version bump.

The description field is doing the real work here. It is the only part of the skill Claude keeps visible before deciding whether to load the rest, so write it like an index entry: what the skill does, plus concrete words a user would actually type. Vague descriptions ("helps with documentation") are the most common reason a skill never triggers, a point covered in more depth in the skill triggers guide.

Step 3: Write the instruction body

The body is plain markdown instructions. Write it the way you would brief a competent colleague who is doing this task for the first time and has no other context.

# Changelog Writer

1. Read the diff or commit list provided.
2. Group changes into: Added, Changed, Fixed, Removed.
3. Write one line per change, imperative mood, no ticket numbers
   unless the user supplies them.
4. Order groups: Added, Changed, Fixed, Removed. Omit empty groups.
5. If the diff touches a config file or migration, add a
   "Notes" section flagging it for manual review.

Never invent a change that is not present in the input.

Concrete rules beat abstract ones. "Never invent a change that is not present in the input" is a rule Claude can actually check itself against; "be accurate" is not.

Step 4: Add references, scripts, and assets (progressive disclosure)

If the skill needs a long style guide, a lookup table, or a script, put it in a subfolder and point to it from the body instead of pasting it inline:

For edge cases (breaking changes, deprecations, security fixes),
see references/edge-cases.md before writing the entry.

Claude opens references/edge-cases.md only when a task actually hits an edge case, so a 2,000-word reference file costs nothing on the 95% of runs that never need it. This is the same discipline covered in the token budget skill guide -- long material belongs in files that load on demand, not in the part of the skill that loads every time.

Step 5: Test in a cold session

Open a new session with no prior context and type a task the way a real user would phrase it, not the way you would phrase it as the skill's author. Confirm three things: the skill loads at all, it loads for the right reasons, and it does not load when the task is actually unrelated.

Step 6: Package as a .skill file

zip -r changelog-writer.skill changelog-writer -x "*.DS_Store"

A .skill file is just the folder zipped with that extension. In Cowork, sharing a .skill file surfaces an install action directly; in Claude Code, the same folder can sit inside a plugin's skills/ directory instead, as covered in the plugin from scratch guide.

Step 7: Install and confirm it triggers

Install the packaged skill, then repeat the cold-session test from Step 5 against the installed version, not your local draft. Skills sometimes behave differently once packaged if a reference path was typed wrong or a script was left out of the zip.

How is a skill different from a plugin?

A skill is one folder with one SKILL.md, built to do one job well. A plugin is a manifest-led bundle that can carry several skills plus slash commands, subagents, and MCP connectors under one plugin.json. Start with a single skill; graduate to a plugin once you have two or more skills that are meant to travel together, the way the Cowork navigator skill and its companion skills do.

What mistakes should you avoid?

The most common failure is a description that reads like a slogan instead of a trigger list. After that: stuffing everything into SKILL.md instead of references/, writing instructions with no concrete rules to check against, and never testing in a genuinely cold session before shipping.

Frequently asked questions

Does a Claude skill require any code?

No. The minimum viable skill is a markdown file with two frontmatter fields and a list of instructions. Scripts are optional and only needed when a task benefits from deterministic code rather than generated reasoning, such as validating a file format.

How big can a SKILL.md file be?

There is no hard limit, but the practical guidance is to keep the body short and move long material into reference files that load on demand. A SKILL.md that reads like a full manual defeats the point of progressive disclosure.

Can I edit a skill after installing it?

Yes. Edit the source folder, re-test in a cold session, then repackage and reinstall. Treat the name field as stable once other skills or documentation reference it, and note changes somewhere you will remember, especially if the description's trigger words change.

About the author

Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.

Next step: Read how skill triggers actually work so your new skill fires reliably, or explore 1,000+ AI tools at yanni.uk/ai-tools.

Sources