# Skill Anatomy

Course: [Agent Skills](https://www.devtutorials.ai/learn/agent-skills) · Section: Agent Skill Fundamentals
Source: https://www.devtutorials.ai/learn/agent-skills/foundations/skill-anatomy

> The parts of a skill: the folder layout, the SKILL.md file, YAML front matter fields, the body sections that make a skill dependable, the optional references, scripts, templates and examples folders, and building your first hello-skill.

## Every Skill Has the Same Shape

**Skill anatomy** = the parts a skill is made of and where each part goes. In this lesson, you will learn the parts of a skill and build your first one.

Every skill uses the same layout.

That makes it easy for an agent to find three things:

- the skill's name
- when to use it
- the steps to follow

It also makes skills easy for people to read, review and change.

**Simple lesson:** if every skill has the same shape, the agent knows where to look.

### A Real-World Example

A recipe card has a fixed layout.

The dish name is at the top. Then come the ingredients, the steps and a serving tip.

You can pick up any card and find what you need. A skill works the same way for an agent.

Click the button and open the **Library** tab.

- **At the top:** the front matter, between two `---` marks.
- **Below it:** the body, with one heading per section.
- **Under the editor:** the checker. It tells you if a rule is broken.

**Simple lesson:** a skill is one folder with one main file, `SKILL.md`.

## What You Will Learn

In this lesson, you will learn:

1. How a skill folder is laid out.
2. What goes in the `SKILL.md` file.
3. The front matter fields, both required and optional.
4. The body sections that make a skill work well.
5. What the optional folders are for.
6. How to build your first skill, `hello-skill`.

**Use the Library tab while you read**

- Every skill in the DevKit follows the layout in this lesson.
- The checker under the editor checks the rules as you type.

## The Skill Folder

### Folder Layout

**Skill folder** = a folder that holds everything one skill needs.

Name the folder after the skill. Use lowercase letters, with hyphens between words.

Only one file is required:

| Item | Required | What it is for |
| --- | --- | --- |
| `SKILL.md` | **Yes** | The front matter and the main instructions |
| `references/` | No | Long detail the agent reads only when a step needs it |
| `scripts/` | No | Code the agent can run for exact checks |
| `templates/` | No | Starting files the agent fills in |
| `examples/` | No | Sample inputs and the outputs you want |
| `assets/` | No | Other files, like images or data |

Start with only `SKILL.md`. Add folders only when the skill really needs them.

A small skill is easier to read and to fix than a big one.

**Simple lesson:** one file is enough to start.

### Where Skill Folders Live

Skill folders sit inside a **skills folder** that your coding tool looks in. **Skill Installation** (lesson 5) shows the exact folders for each tool.

## The SKILL.md File

### Two Parts in One File

`SKILL.md` is a plain Markdown file with two parts.

```markdown
---
name: commit-writer
description: Writes a conventional commit message for staged changes. Use when someone asks for a commit message. Do not use for release notes.
---

# Commit Writer

## When to use
- The user asks for a commit message for a diff or staged changes.

## Workflow
1. Pick one type: feat, fix, refactor, docs, test, chore, perf or ci.
2. Write a subject under 60 characters, imperative mood, no full stop.
```

**Front matter** = the lines between the two `---` marks at the very top.

- It is written in **YAML**.
- **YAML** = a simple `key: value` format.

**Body** = everything after the second `---`.

- It is normal Markdown, with headings, lists and code.

The agent reads the front matter of **every** skill when it starts. So keep it short.

It reads the body only when the skill **fires**, which means when the agent picks it.

Watch the file split into its two parts:

The front matter is read for every skill. The body is read only for the one that fires.

**Simple lesson:** the front matter helps the agent choose. The body tells it what to do.

## YAML Front Matter

### Required Fields

Two fields are required.

| Field | Rules | Tip |
| --- | --- | --- |
| `name` | Lowercase letters, numbers and single hyphens. Up to 64 characters. Same as the folder name | Name the job: `pr-review`, not `helper2` |
| `description` | 1 to 1024 characters | Say **what** the skill does **and when** to use it |

Add "Do not use for…" when another skill could be mixed up with this one.

**Important:** the agent picks a skill by reading its description. A weak description means the skill never runs.

**YAML is picky.**

- A colon inside a value can break it in some tools. If a description has `: ` in it, wrap it in quotes.
- Keep each field on one line until you know your tool allows more.

**Simple lesson:** a good name names the job. A good description says what and when.

### Optional Fields

The open format also has a few optional fields:

| Field | What it does |
| --- | --- |
| `license` | The license the skill is shared under, like `MIT` |
| `compatibility` | What the skill needs, like "Requires Python 3 and git" |
| `metadata` | Extra data, like `author` or `version` |
| `allowed-tools` | Tools the skill may use without asking (new, and not every tool supports it) |

Some tools add their own fields. For example, a tool may let a skill run only when you call it by name.

Check your tool's docs before you use those. Most tools ignore fields they do not know.

**Simple lesson:** you only need `name` and `description` to start.

## The Skill Body

### Body Sections

The body is free Markdown. But skills that work well usually use the same sections:

| Section | What it answers | Example line |
| --- | --- | --- |
| **When to use** | Which requests is this for? | The user asks for a commit message |
| **Inputs** | What does the agent need first? | A diff or a short note about the change |
| **Workflow** | What are the steps, in order? | 1. Pick one type… 2. Write the subject… |
| **Output format** | What must the reply look like? | One heading: `## Commit message` |
| **Examples** | What does good look like? | `fix(auth): refresh expired tokens before retrying` |
| **Do not use** | Which requests are not for this skill? | Release notes (use release-note-helper) |
| **Final checks** | What to check before replying? | Subject is under 60 characters |

These sections tell the agent:

- when to use the skill
- what it needs
- which steps to follow
- what the reply should look like
- what to check before it finishes

**Write the workflow as numbered steps.**

- Models follow lists better than paragraphs.
- When something goes wrong, you can point to "step 3".

**Simple lesson:** the same seven sections make a skill clear and easy to check.

### Keep SKILL.md Short

Keep only the steps the agent needs every time. Move long detail into other files, and name each file in a step. **Loading and Context Cost** (lesson 3) explains why.

**Simple lesson:** every extra file needs a step that points to it.

## Optional Folders

### references/

Use `references/` for detail that is needed only sometimes.

For example:

- an API style guide
- a list of error codes
- a security checklist

The agent reads a reference file only when a step tells it to. That keeps the skill small.

### scripts/

Use `scripts/` for checks that must be exact.

A model can miscount letters. A script can't.

A good script:

- is small
- does one thing
- prints a clear result
- is explained in `SKILL.md`

```text
## Final checks
- Run scripts/check_notes.py with the notes as input. It prints OK or the missing headings.
```

### templates/ and examples/

**Template** = a starting file with blanks to fill in. For example, a pull request layout.

**Example** = a real input together with the output you want.

Examples are one of the best ways to show a model what "good" means.

Click the button and open the **Library** tab.

- **The file chips** above the editor move you between `SKILL.md`, the style guide and the script.
- **Workflow step 7** points to the style guide.
- **The final checks** point to the script.

**Simple lesson:** put detail in references, exact checks in scripts, and samples in examples.

## Build Your First Skill

### hello-skill

Your first skill is simple on purpose. It greets the user and lists the skills in the DevKit.

It has every required part, and nothing extra.

Watch `hello-skill` being built, one fix at a time:

Each fix removed one problem. At the end, every check was OK.

Click the button and open the **Library** tab. It now has a `hello-skill` folder.

- **The name** is valid and matches the folder.
- **The description** says what and when.
- **The body** is missing a few sections. That is fine for a first try.

Now add `## Inputs`, `## Examples` and `## Do not use`, then press **Save**.

Then open the **Activation** tab and type "hello, which skills do I have?". Your new skill should fire.

**Simple lesson:** build the smallest skill that works, then improve it.

### Installing It for Real

To use `hello-skill` in your own editor, follow the steps in **Skill Installation** (lesson 5).

## TL;DR

1. **Skill folder** = a folder named after the skill. It must hold a `SKILL.md`.
2. **SKILL.md** has two parts:
   - **Front matter** = `name`, `description` and optional fields, between `---` marks.
   - **Body** = the instructions, in Markdown.
3. `name` = lowercase, hyphens, up to 64 characters, same as the folder.
4. `description` = what the skill does and when to use it, up to 1024 characters.
5. Good bodies use the same sections:
   - when to use, inputs, workflow, output format
   - examples, do not use, final checks
6. Keep `SKILL.md` short. Put extra detail in other folders:
   - `references/` → long detail
   - `scripts/` → exact checks
   - `templates/` and `examples/` → layouts and samples
7. Every extra file must be mentioned in `SKILL.md`, or the agent won't open it.

## Common Mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| A name that doesn't match the folder | "The folder name doesn't matter." | Use the same name for both. | Some tools reject the skill, and people get confused. |
| Capitals or underscores in the name | "`PR_Review` is fine." | Use lowercase and hyphens: `pr-review`. | The checker rejects the name. |
| A vague description | "Helps with stuff" is enough. | Say what the skill does and when to use it. | The agent can't match it to any request. |
| Forgetting the closing `---` | "The front matter ends by itself." | Close it with a second `---` line. | The file is not read correctly. |
| A wall of text instead of sections | "One long paragraph says it all." | Use headings and numbered steps. | The agent skips steps, and you can't point to one. |
| Files the body never mentions | "The agent will find the file." | Point to each file from a step or a check. | The agent never opens the file. |
| Putting everything in SKILL.md | "One big file is simpler." | Move long detail into `references/`. | The skill gets slow to load and hard to read. |

## Check Your Understanding

## Exercises

These exercises help you practise the parts of a skill.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- A skill is a folder named after the skill, with a required `SKILL.md`.
- `SKILL.md` has front matter and a body.
- The name is lowercase with hyphens, and matches the folder.
- The description says what the skill does and when to use it.
- Good bodies use the same seven sections.
- Keep `SKILL.md` short. Put extra detail in other folders.
- Every extra file must be mentioned in `SKILL.md`.

Next: **Loading and Context Cost**. You will see what loads into the agent's memory, and when.