Agent Skills

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

Why an agent does the same job differently each time, and how a SKILL.md fixes it: a description that says when to load it, and steps that say how. You write a skill that loads on the right requests, stays quiet on decoys, and gets every step done.

What Agent Skills Are

A skill is a written recipe for one job. The agent loads it when that job comes up.

In this lesson, you will learn when a job needs a skill. You will also learn how a skill gets picked, and how to write one.

Some jobs have several fixed steps.

The team does the same steps every time.

For example, to add a new ticket status, the team always does three things:

• Add the label in src/lib/status.ts.
• Add a test case for it.
• Add a row to docs/statuses.md.

Ask the agent to add a status three times.

You get three different results. Each one is missing something.

A Real-World Example

Think of a coffee shop with a new barista.

The menu board says "Flat white". That name tells the barista when a recipe applies.

Behind the counter is a recipe card:

1. Two shots of espresso.
2. Steam the milk to 60 °C.
3. Pour a thin layer of foam.

The barista does not read every card before each order. They read the order and find the matching card.

Then they follow it.

Every flat white tastes the same.

A skill works the same way:

• The description is the menu name. It decides when the skill is used.
• The steps are the recipe card. They make the result the same every time.

Click the button and run it. Then switch Bug version in Settings and run it again.

• The files it changes: a different set each time.
• The last message: it says "Done." every time.
• On the .NET project: the job is "add a field to orders". The agent forgets the migration, or gives it a bad name. A migration (EF Core) = a small script that updates the database tables.

The agent can do every step. It just does not know this team's recipe.

Simple lesson: without a recipe, the same job comes out different every time.

What You Will Learn

In this lesson, you will learn:

1. What a skill is, and when a rules line is not enough.
2. How a skill gets loaded.
3. How to write a description that matches the right requests.
4. How to write steps that the agent follows every time.
5. Skills for backend, frontend and testing.

With a Skill and Without One

Watch the Difference

Here is the same agent and the same request, run twice.

The first run has no skill. The second has one.

Step through all four frames.

• Frame 1: the job and its three parts.
• Frame 2: no skill. The agent does one part and stops.
• Frame 3: with the skill, it does every part. The ticks show each one.
• Frame 4: all three requests. The skill gets every part done each time.

Only the skill changed. The agent stayed the same.

Skills or Rules?

A rules line is good for one fact.

• "Run pnpm test before done."
• "Never edit .env.production."

A fact applies to every task. So it lives in the root rules file.

A skill is good for a job. A job has several steps and comes up again and again:

• Adding a status, a field or an endpoint.
• Writing release notes.
• Adding a database migration.

Put every recipe in the rules file, and it grows too long. A skill keeps the recipe out of the way until the job comes up.

Simple lesson: facts go in the rules file. Jobs go in skills.

How a Skill Gets Loaded

The Description Decides When

At the start of a session, the tool reads only the name and the description of each skill. This is cheap.

When a request comes in, the model reads those descriptions and decides which skill fits.

Only then are its steps read.

Progressive disclosure = show a little at the start, and the rest only when it is needed.

Match a Description

Step through all three frames.

• The same words: words that the request and the description share.
• Loads or stays off: green loads, red stays off.
• Frame 3: a decoy = a request that should not load the skill. The broad description loads anyway.

What Makes a Good Description

• Say when to use it: "Use when someone asks to add a new ticket status."
• Use the words that people use when they ask for the job.
• Say when not to use it, if a similar job exists.
• Do not list the files that the skill touches. Those words show up in other requests too.

Simple lesson: describe the job in the asker's words, not the files.

Inside a SKILL.md

Two Parts

A skill is one file called SKILL.md, in its own folder.

The format is the same in all three tools. Only the folder changes.

Here is the skill for adding a ticket status:

---
name: add-ticket-status
description: Use when someone asks to add, create or need a new ticket status.
---

1. Add the status and its label to src/lib/status.ts.
2. Add a test case for it in src/lib/status.test.ts.
3. Add a row for it to docs/statuses.md.
4. Run `pnpm test` and make sure it passes.

Front matter = the part between the two --- lines. It holds the name and the description.

Body = the steps below it.

The Steps Say How

Step through all four frames.

• The two colours: the front matter and the body.
• Frame 2: only the short front matter is read at the start.
• The notes on each step: what the agent will do with it.
• The red line: a vague step. The agent finds nothing to do.

Write the steps as a numbered list. Make each step one action, with the file or the command it needs.

"Make sure everything is good" gives the agent nothing to do. Name the file or the command.

Lab Exercise: Write a Skill

Now write a real skill in the lab.

On the React project, the job is "add a ticket status". On the ASP.NET Core project, it is "add a field to the Order model", with its EF Core migration.

Click the button to open the skill file. The check runs three things:

1. Real requests: the skill must load for all 3.
2. Decoys: it must not load for 3 decoy requests.
3. Every step: on all 3 versions, the agent must finish the whole job.

Simple lesson: a good skill loads on the right requests and gets every step done.

Skills for Each Part of the Team

Most teams write skills for the jobs they repeat. For example:

---
name: new-component
description: Use when someone asks to create or add a new React component.
---

1. Create src/components/<Name>/<Name>.tsx using the design tokens.
2. Export it from src/components/index.ts.
3. Add <Name>.test.tsx with one render test.
4. Run `pnpm test` and `pnpm lint`.

---
name: add-order-field
description: Use when someone asks to add, create or need a new field, column or property on the Order model.
---

1. Add the property to the Order model in Pricing.Api/Models/Order.cs.
2. Add an EF Core migration: `dotnet ef migrations add Add<Field>`.
3. Run `dotnet test` and make sure it passes.

A planning skill can even end with "Stop and ask a person to approve the spec."

Testing Skills

A test-writing skill must make tests that fail before the fix and pass after it.

The lab checks when a skill loads and whether its steps get done. It does not grade the tests a skill writes. Try that part in your own project.

A test that passes either way checks nothing.

For example, a bug shows "1250 tickets" instead of "1,250 tickets":

• "It returns a string" passes on the broken code too. It is useless.
• "It shows 1,250 tickets" fails on the broken code. It catches the bug.

Put "the test must fail on the old code" in the skill's steps.

Simple lesson: a good test fails on the old code and passes on the new code.

TL;DR

1. Skill = a recipe in a file called SKILL.md, loaded when its job comes up.
2. Description = the line that says when to use the skill.
3. Steps = the numbered list that says how to do the job.
4. Progressive disclosure = the tool reads descriptions at the start, and steps only when a skill loads.
5. Decoy = a request that should not load the skill.
6. Rules line or skill = one fact goes in rules. A job with several fixed steps goes in a skill.

Common mistakes

Check Your Understanding

Exercises

These exercises practise the two parts of a skill, and when to write one.

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

What to Remember

• A skill is a recipe: a description that says when, and steps that say how.
• The tool reads only descriptions at the start. It loads the steps when a request matches.
• Describe the job in the words that people use. Do not list file names.
• Number the steps. Name the file or the command in each one.
• A test-writing skill must make tests that fail before the fix and pass after it.

Further Reading

• Skill Issue: Harness Engineering for Coding Agents, by HumanLayer: skills as one of the main harness levers.
• Harness engineering, by Software Mansion: skills next to a short AGENTS.md.
• awesome-harness-engineering, by walkinglabs: more skill examples.
• The Agent Skills course on this site goes deeper into how skills are routed.

Next: Tests and Linters. You will make the agent check its own work and fix its own mistakes.