What a skill actually is

A Claude Code skill is a single markdown file that teaches Claude how to do one specific task the way you want it done. It lives at ~/.claude/skills/<name>/SKILL.md and Claude auto-loads it when the trigger matches the current request.

Think of it as a playbook you hand to a good engineer who is about to start the task. The engineer is smart, so you do not need to teach them how to write code. You do need to tell them the shape of the task, the constraints that apply, the gotchas you have already discovered, and what "done" looks like. That is the skill.

By the end of this guide you will have written your first skill, installed it, triggered it from a real prompt, and understood the design decisions that make the difference between a skill that Claude actually uses and one that sits forgotten.

The four parts of every skill

Every skill is a markdown file with YAML frontmatter. Four things matter:

Name - what the skill is called
Description - when Claude should trigger it
Allowed tools - which tools the skill expects Claude to have access to
Body - the actual instructions for doing the task

The frontmatter controls when the skill fires. The body controls what happens when it does. Getting both right is the whole craft.

Pick a task worth turning into a skill

The first question is which tasks deserve a skill. The criteria:

You do it more than once. A skill is a tax on every session's context load. Writing one for a task you do annually is not worth it. A task you do weekly absolutely is.
It has a consistent shape. Skills encode patterns. If every instance of the task is wildly different, there is no pattern to encode.
You have an opinion about how it should be done. Without an opinion, the skill is just a nudge toward "do a good job," which is not a skill. With an opinion, the skill becomes a style enforcer.
It has failure modes you want to prevent. Skills are where you capture the lessons learned from mistakes. If a task has surprised you in the past, write the skill so future-you does not step in the same hole.

A bad first skill: "write code." Too vague. No opinion. No failure modes.

A good first skill: "add a new HTTP route to our Express API." Specific shape, conventions worth encoding (route handler file, input validation, error pattern, test file), known failure modes.

Write the frontmatter

Let's walk through a concrete skill. Task: adding a new blog post to a Next.js content-markdown repo.

---
name: add-blog-post
description: |
  Trigger when the user asks to add a blog post, write a new article, or
  publish a piece of content. Phrases: "add blog post", "write article",
  "new post", "publish", "add to blog".
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
---

The description is the most important field. It is what Claude reads when deciding whether to load your skill. Lead with the trigger condition ("Trigger when..."). Follow with example phrases.

The common mistake is writing a description that sounds like marketing copy. Skills do not need to sell themselves. They need to be findable by pattern matching. The phrases in the description are literal matches Claude uses to route the request to your skill.

allowed-tools is the declaration of what tools the skill expects to use. It is not a permission system, it is documentation. The skill author is telling the user "if your Claude Code config does not allow these, this skill will not work."

Write the body

The body is a second-person playbook. You are writing instructions to another engineer.

Start with prerequisites. What has to be true before the skill can run? For the blog post example:

## Prerequisites

- Markdown content directory identified (e.g., `content/blog/`)
- Frontmatter shape known (check an existing post for reference)
- Hero image directory identified if the site uses featured images

Continue with steps. Use numbered, imperative instructions. Each step should be one action the agent can verify.

## Steps

1. **Find the content directory.** Glob `content/**/blog*` or check an
   existing post. Confirm with the user if there are multiple candidates.

2. **Read an existing post.** Pick the most recent post and study its
   frontmatter shape. Blog schemas vary: date format, tags array,
   relatedPosts, series fields. Do not guess.

3. **Create the new post file.** Use the slug as the filename:
   `content/blog/<slug>.md`. Never overwrite an existing file.

4. **Write the frontmatter.** Copy the shape from step 2. Fields that
   always matter:
   - title (sentence case, under 70 chars)
   - slug (kebab-case, matches filename)
   - excerpt (one sentence, not a rewrite of the title)
   - date (ISO)
   - tags (array, match existing site conventions)

5. **Write the body.** Open with a lead paragraph, not a heading.
   Use `## H2` for sections, not `#`. Short paragraphs. No em dashes.

6. **Verify frontmatter parses.** Run the site's build or lint step
   if available. If not, grep for any broken frontmatter on existing
   posts and match that pattern exactly.

7. **Tell the user what was added** and where. Include the slug and
   the file path.

The pattern: prerequisites, numbered steps, each step both specific and verifiable. No fluff.

Write the failure-mode section

Every skill that ships should have a "common mistakes" or "anti-patterns" section. This is where you bake in the lessons from past failures.

## Common mistakes to avoid

- Do not use em dashes. Use regular dashes with spaces.
- Do not guess at frontmatter fields. Read an existing post.
- Do not write a post without a date field. Sort order depends on it.
- Do not overwrite existing posts. If the slug collides, pick a new slug.

This is the highest-leverage section of the skill. Every item here is a mistake you, or Claude, or a prior session made before. Future sessions save the time of discovering it again.

Write the output section

End the skill with a specification of what success looks like.

## Output

- New markdown file at `content/blog/<slug>.md`
- Frontmatter matches existing post shape
- File passes the site's build or frontmatter validator
- User receives the slug and file path in the response

This section is both a contract for Claude and a checklist for you when reviewing the skill's output.

Install the skill

Save the file as ~/.claude/skills/add-blog-post/SKILL.md. Claude Code auto-discovers skills under ~/.claude/skills/*/SKILL.md at session start.

To test it, start a new Claude Code session (or /reload in an existing one) and send a prompt that matches the description:

"Add a blog post about our Q2 release"

Claude should load the skill, confirm the prerequisites, and follow the steps. If it does not load the skill, the description's trigger phrases probably did not match. Revise the description and retry.

Test with real prompts

Test a skill with at least three prompts before trusting it:

The exact phrase from the description ("add a blog post")
A paraphrase the user might actually say ("can you write a new post about X")
An edge case (vague or partial request, e.g. "post about the new feature")

For each prompt, check that the skill loads, that Claude follows the steps in order, and that the output matches the spec. If any of these fail, the skill is not ready.

Iterate from failure

The first version of any skill is wrong. You will see Claude skip a step, misinterpret a prerequisite, or invent a variation of the pattern. That is fine. The skill file is a living document. Every failure is a note to add to the "common mistakes" section or a clarification to add to the relevant step.

The most valuable skills in my library are on their fifth or sixth revision. Each revision captures a specific failure mode from real use.

Keep the skill short

Skills that exceed 500 lines are usually too long. They are trying to teach Claude too many things at once and the trigger becomes muddy. When a skill grows past that threshold, split it.

A useful heuristic: if you could not verbally explain the skill to a new engineer in three minutes, it is too big.

The six-line litmus test

Before you ship a skill, read the frontmatter and the first line of the body. If those seven lines answer "when should I use this?" and "what will happen if I do?", ship it. If they do not, rewrite before shipping. The most common skill failure is not that the body is bad but that the top of the file is vague.

Where to go next

Browse real SKILL.md examples at skills.developersdigest.tech for patterns across categories.
Read our context engineering guide for the broader theory behind skills, CLAUDE.md, and memory.
Write a second skill. The gap between zero skills and one is large; the gap between one and three is smaller. Fluency comes with volume.

The skill file is the unit of encoded opinion in Claude Code. Every skill you write is a lesson future-you does not need to re-learn and every other teammate can benefit from. Write them carefully, but write them.