Skill Anatomy

By the Syncfusion DevTutorials team · Last updated October 22, 2026

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.

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:

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.

---
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.

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.

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:

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:

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

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

## 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

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.