How to write a Claude Code skill (and the gotchas the docs skip)

I put off Claude Code skills for six months because the docs made them sound like a framework. Then I opened one and it was a markdown file. One file, a few lines of YAML, done.

If you already keep a CLAUDE.md and a memory folder, you're most of the way there. This is the from-scratch guide: what a skill actually is, how to write one, the gotchas that aren't in the docs, and a real, non-trivial example (a memory system I packaged as a skill in an afternoon).

TL;DR

• A Claude Code skill is a folder with one SKILL.md file inside it. That's the whole mechanic.
• The description field is the trigger. Spend most of your writing time there, not on the body.
• The minimum viable skill is about 30 lines. References, templates, and scripts are optional add-ons.
• I packaged my memory system, UAMOS, as a skill: 4 layers, 5 modes, version-controlled. The lessons are at the end.

What a skill is, mechanically

Four parts, three of them optional:

1. A folder at ~/.claude/skills/<name>/ for a global skill, or <project>/.claude/skills/<name>/ for a project-local one.
2. A SKILL.md file inside it. Required.
3. YAML frontmatter at the top with name and description. Required.
4. Markdown instructions below the frontmatter that tell Claude what to do once the skill fires.

Optionally, you add one or more of these. None are required for a working skill:

• references/: docs Claude reads when it needs depth, but never copies.
• templates/: files Claude copies into a project, usually with placeholders.
• scripts/: code Claude runs when a prompt isn't enough.

The mental model that helped me: a skill is to Claude what a cron job is to a server. It sits as files on disk and fires automatically when its trigger condition is met. You don't call it explicitly. You talk to Claude normally and it picks the right skill.

How to create one, step by step

Here is a complete, working skill in 30 lines:

---
name: my-skill
description: Run when the user says "do X", "perform Y", or asks for a Z report. Used for ABC purpose.
---

# My Skill

You are a specialist in [whatever]. Your job: [one sentence].

## Steps

1. Read the file at [path].
2. Do [thing].
3. Output [format].

## Hard rules

- Never [the thing that would break trust].
- Always [the thing that compounds].

Save that to ~/.claude/skills/my-skill/SKILL.md, restart Claude Code, and ask for "do X." It fires. That's the entire create-a-skill loop. The hard part isn't the syntax. It's writing a description that actually triggers, which is the first and most important best practice.

Best practices nobody put in the docs

I burned a few hours on each of these.

The description is the trigger, so write it for the matcher

When Claude starts a session, it reads the description of every installed skill and matches your request against them. The description does two jobs at once:

• It tells you, the human, what the skill does.
• It tells Claude, the matcher, when to fire it.

My first version of a skill had the description "Manages my project operations." Claude never fired it. Not once. I rewrote it to list the literal phrases I'd type ("set up the project here", "audit this", "rebuild the index") and it fired on the first matching request. Abstract summaries don't match concrete requests. Spend 80% of your effort here. The body is for Claude to follow after the skill is already firing; the description decides whether it fires at all.

One skill, one purpose

Your first skill will be tempted to do five things. Resist. If you find yourself writing three workflows that don't share state, those are three skills, not one. A bloated description has to cover too much, so it matches inconsistently, and editing one part risks breaking the others. When several skills need the same knowledge, put it in one shared skill they all read, rather than copying it into each.

Know the difference between references and templates

This one bites people. Templates are files Claude copies into your project, usually with placeholders to fill in. References are files Claude reads for context but never copies. Folder naming carries the meaning: put scaffolds in templates/, put background docs in references/. Get it backwards and Claude will either write a reference doc into your project (wrong) or treat a scaffold as read-only and never produce the output (also wrong).

Skills don't auto-reload

If you edit a SKILL.md mid-session, the running Claude Code instance is still using the version it loaded at startup. Restart the session to pick up changes. I lost 20 minutes debugging "why isn't this rule firing" before I realized this. The same applies to brand-new skills: they're discovered at session start.

Version-control your skills folder

A skill is codified workflow. If ~/.claude/skills/ isn't version-controlled, every machine you work on runs a slightly different version of it, and you stop trusting them. I keep mine in my notes vault and symlink. Committing the folder to a personal repo works just as well. Doing neither is how skills quietly drift apart across machines.

The worked example: building UAMOS as a skill

Most of my skills are a single file. UAMOS is the one that needed all the optional parts, so it's the best example of how the pieces fit.

UAMOS (Universal AI Memory Operating System) is the layer that gives a project memory: it loads consistent context, rules, and an index before any AI session writes code, so the agent stops reinventing things that already exist. It's stack-agnostic. I run it on a React Native codebase, but the same skill installs on Node or Python, because the structure is the same and only a couple of stack-specific rules get swapped at install time.

It's four layers, and each one is a precondition for the next:

Read top to bottom:

• Indexing tells the agent where everything lives, so it stops running blind grep and glob.
• Memory bank keeps state across sessions in 9 tiered files (hot, warm, cold).
• Rules constrain what the agent is allowed to write, in three tiers.
• Agents split the work across 5 specialists, each loading only the layer it needs.

The relation is the part that matters: indexing prevents the agent from hallucinating files that don't exist, memory keeps state across sessions, rules constrain the diff, agents specialize the workflow. Pull one layer out and the others degrade.

The file tree

UAMOS uses every optional part of the skill spec:

~/.claude/skills/uamos/
├── SKILL.md                    # the brain: modes + hard rules
├── references/                 # docs Claude READS, never copies
│   ├── 4-layer-architecture.md
│   ├── 7-point-checklist.md
│   └── memory-tiering.md
└── templates/                  # scaffolds Claude COPIES into a project
    ├── CLAUDE.md
    ├── globalRules.md
    ├── context_map.md
    ├── memory/   (9 tiered starter files)
    └── rules/    (3 critical rule files)

The SKILL.md holds the modes and the hard rules. The references/ files explain the system in depth so the SKILL.md can stay short and point at them when a question needs detail. The templates/ files are working scaffolds with {{PROJECT_NAME}} placeholders that get filled in during install. Keeping depth in references means the skill loads light every session and only pulls the heavy explanation when a mode actually needs it.

The modes and the commands that trigger them

A single skill can package several related workflows as modes, each with its own trigger phrases. UAMOS has five, and I drive them in plain language:

• init ("set up UAMOS here") interviews me with five questions about the project, then scaffolds the full folder structure and inventories the existing code.
• audit ("audit my memory bank") walks the current setup and reports staleness with a status table, flagging a Hot tier that hasn't been touched this week or an inventory that's drifted from the real file count.
• reindex ("reindex this codebase") rebuilds the inventories after a batch of new code ships.
• progress / decide / learn ("append progress", "capture a decision", "capture a lesson") write dated, append-only entries to the right memory file. Memory is sacred here: nothing overwrites, and the skill never writes the progress log unless I trigger it.
• migrate ("migrate this project to UAMOS") is init for a codebase that already has code: it indexes first, preserves any existing AI rules, and fills in the memory bank from the real structure.

Modes are how you package related-but-distinct workflows in one skill without splitting it into five skills with overlapping descriptions. UAMOS is honestly borderline on the one-skill-one-purpose rule, but the modes share enough underlying knowledge of the same file structure that splitting them felt worse than keeping them together. Make that call on purpose, not by accident.

What it cost and what it returned

The skill took an afternoon to build, most of it on the templates, not the SKILL.md. On the project I've run it on longest, the numbers after a month:

• Context spend: down roughly 91%, because the agent stops searching blindly.
• Hallucinated edits: down roughly 93%, because it stops inventing things that already exist.
• Setup cost: about a day for the full install, an hour or two for a minimal one.

The part that compounds is the feedback loop. A recurring problem in the progress log becomes a new rule. A non-obvious pattern I had to work out gets logged so I don't relitigate it next month. Each session makes the next one cheaper, and that only works because skills are plain files reading and writing other plain files. No database, no orchestration engine.

When a skill is overkill

Skills are for workflows you run by hand more than three times. A heavyweight skill like UAMOS is overkill in some cases and worth it in others:

• Overkill for: a throwaway script, a solo prototype you'll abandon in a week, or any codebase you won't reopen.
• Worth it for: long-lived projects, code that more than one AI tool touches, and anywhere consistency across sessions matters more than raw speed in a single one.

Two honest caveats beyond that:

• Auto-trigger isn't perfect. Even with a sharp description, Claude occasionally misses the match, and the fallback is to invoke the skill by name.
• Skills rot. An inventory drifts, a rule stops being true when the stack changes. Plan on a periodic audit, or you'll stop trusting the system, which defeats the point.

Where to start

Don't build something like UAMOS first. Start small.

1. Pick one workflow you run by hand more than three times a month. One specific thing, not "everything I do with Claude."
2. Create ~/.claude/skills/<name>/SKILL.md and write the 30-line skeleton from earlier.
3. Spend most of your effort on the description. List the literal phrases you'd type to trigger it.
4. Restart Claude Code and test by saying one of those phrases word for word.

If it fires, you have a skill. Build the next one when you catch yourself doing the same thing by hand a fourth time. The memory layer can wait until you have a project worth remembering across sessions.

I write Code Meet AI, one issue per week on AI-native mobile development. The UAMOS skeleton bundle (the SKILL.md, the 9-file memory bank, and the 3 critical rule templates) goes out to subscribers.

FAQ

What is a Claude Code skill in one sentence?

A folder at ~/.claude/skills/<name>/ containing a SKILL.md file with YAML frontmatter (name and description) and markdown instructions, which Claude loads at session start and fires when your request matches the description.

How do I create a Claude Code skill from scratch?

Create the folder, add a SKILL.md, write YAML frontmatter where the description lists the actual phrases you'd say to trigger it, write your instructions below, and restart your Claude Code session. The minimum viable skill is about 30 lines.

Why isn't my skill firing?

Almost always the description. Claude matches your request against it to decide what to fire, so an abstract description ("manages my project") won't match a concrete request ("set up the project here"). Rewrite it with the literal phrases you'd type, then test by saying one of them verbatim. Also remember skills don't reload mid-session, so restart after editing.

What's the difference between references and templates in a skill?

References are files Claude reads for context but never copies. Templates are files Claude copies into your project, usually with placeholders. Put background docs in references/ and scaffolds in templates/. Confusing the two is one of the most common skill-authoring mistakes.

Can one skill do more than one thing?

Yes, through modes: distinct workflows packaged in one skill, each with its own trigger phrases. UAMOS has five (install, audit, reindex, append-to-memory, migrate). Use modes when the workflows share underlying knowledge. When they don't, make them separate skills.