Skills and Subagents

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

Write a SKILL.md that gets picked for the right tasks. Fix a skill whose vague description never loads, follow the name rules, write a description with what, when and when not, keep the body small with progressive disclosure, and write a reviewer subagent file.

The Skill That Never Loaded

Asha writes a skill to help an AI agent check refund requests against the policy. She puts the steps in a SKILL.md file. Then she asks the agent about a late refund. The agent does not use her skill at all.

A skill with a vague description

---
name: refund-check
description: Helps with refunds.
---

# Refund check

1. Find the order by its number or the customer's email.
2. Check the refund window: 30 days from delivery.
3. If the amount is over ₹5,000, ask for a manager's approval.
4. If the item is damaged, ask for a photo first.

The steps are fine. The problem is the second line. Open the Agent view tab. It lists ten prompts a person might type. The skill is picked for none of them, not even "Why is my refund late?".

At the start of a session, an AI tool reads only the name and description of each skill. It decides from those alone whether a skill fits the task. "Helps with refunds" is too short and too vague to win that choice.

In this lesson, you will learn how a SKILL.md file is built, how to write a description that gets picked for the right tasks and skipped for the wrong ones, and how to write a subagent file.

In simple words: a skill is a folder with a SKILL.md file. Its description is an advert. If the advert is vague, the skill is never used.

TL;DR

• A skill is a reusable set of instructions for one kind of task. It is a folder with a SKILL.md file inside.
• SKILL.md starts with YAML frontmatter. name and description are required.
• The name is lowercase letters, numbers and hyphens, and must match the folder name.
• The description says what the skill does and when to use it, with the words people will actually type.
• Skills load in stages: name and description first, the body only when the task matches, extra files only when needed.
• A subagent file defines a separate helper agent: frontmatter for its name, description and tools, and a body that is its instructions.

A Real-World Example

Think about the list of courses at a college.

You do not read every course's full textbook to choose one. You read the course list: a name and two lines about each course. Then you open the textbook for the one you picked.

AI tools choose skills the same way. The name and description are the course list. The body of SKILL.md is the textbook. A course called "Misc. Topics: helps with stuff" never gets chosen, however good its textbook is.

What You Will Learn

In this lesson, you will learn:

1. What a skill is, and how it differs from AGENTS.md.
2. How a skill folder and its SKILL.md are laid out.
3. The rules for the name field.
4. How to write a description that matches the right prompts and skips the wrong ones.
5. How skills load in stages, and what that means for their size.
6. How to write a subagent file.

Cheat Sheet

A skill that gets picked

---
name: refund-check
description: "Checks a refund request against the refund policy: the 30-day window, the approval limit and damaged items. Use when a refund is requested or late, or when someone wants money back for a damaged parcel. Do not use for shipping, delivery dates or tracking."
---

# Refund check

## Steps

1. Find the order by its number or the customer's email.
2. Check the refund window: 30 days from delivery. After that, offer a voucher.
3. If the amount is over ₹5,000, ask for a manager's approval.
4. If the item is damaged, ask for a photo before you refund.

## Output

Reply with one line: **approve**, **voucher**, **needs approval** or **needs photo**, then the reason.

## More detail

The full policy, with edge cases, is in [the refund policy](references/refund-policy.md).

Open the Agent view. The skill is now picked for all five refund prompts, and for none of the five that are about something else. Open the Checks tab: nothing fires.

What a Skill Is

Always-On Versus On-Demand

In the last lesson, you met the always-on test: does a rule apply to almost every task? If yes, it goes in AGENTS.md. If not, it goes in a skill.

A skill lets you write detailed steps for a task without making every other session pay for them.

The Skill Folder

A skill is a folder. The folder's name is the skill's name. Inside, there must be a SKILL.md file. Other folders are optional.

A skill folder

refund-check/
├── SKILL.md            required: frontmatter + instructions
├── references/         optional: longer docs, read only when needed
│   └── refund-policy.md
├── scripts/            optional: code the agent can run
└── assets/             optional: templates and data files

Where the folder lives depends on the tool:

The box below shows the path for the tool you picked at the start of the course:

The SKILL.md format is the same in every tool. It follows the open Agent Skills specification.

The Name Field

The name has strict rules, from the Agent Skills specification:

• 1 to 64 characters.
• Only lowercase letters a-z, numbers 0-9 and hyphens -.
• It must not start or end with a hyphen, or have two hyphens in a row.
• It must be the same as the folder name.

A name that breaks the rules

---
name: Refund_Check
description: "Checks a refund request against the refund policy. Use when a refund is requested or late."
---

# Refund check

Open the Checks tab. SKL002 fires because of the capital letters and the underscore. SKL003 fires because Refund_Check is not the folder name, refund-check. Change the name to refund-check and both go away.

The Description

What It Does, and When to Use It

The description is the most important line in a skill. It is the only part the tool reads when it chooses which skill to use. The spec says it should describe what the skill does and when to use it, with keywords that help an agent spot the task. It can be up to 1,024 characters.

A good description has three parts:

1. What it does: "Checks a refund request against the refund policy: the 30-day window, the approval limit and damaged items."
2. When to use it: "Use when a refund is requested or late, or when someone wants money back for a damaged parcel."
3. When not to use it: "Do not use for shipping, delivery dates or tracking."

Each part uses the words a person would type: refund, late, money back, damaged, parcel.

How the Agent View Decides

The tool's real choice is made by an AI model reading every skill's description. The Agent view in this course uses a simple, open simulation instead, so you can see the idea at work:

• Words in the prompt that also appear in the "use" part of the description count for the skill.
• Words that appear only in the "Do not use" part count against it.
• The skill is picked when enough words match.

A real model is smarter. It knows "money back" means a refund even if you never wrote "refund". But the lesson is the same: a description full of the right words gets picked, and a vague one does not.

Why "Do Not Use" Helps

A description that is too broad gets picked for tasks it should not handle. A "Do not use" sentence draws the line.

Too broad, then fenced in

---
name: refund-check
description: Checks refund requests and order questions. Use when a customer asks about an order or a refund.
---

# Refund check

Open the Agent view. The skill is picked for the shipping question, because "customer", "asks" and "order" all match. Now add this sentence to the end of the description: Do not use for shipping or tracking. Look again. The shipping question is no longer picked. The refund question still is.

Skills Load in Stages

Skills are built to be cheap until they are needed. The spec calls this progressive disclosure: the tool reads more of a skill only as the task needs more.

So keep SKILL.md itself under 500 lines. Put long policies, tables and examples in references/ files, and link to them from the steps, as the cheat sheet does with references/refund-policy.md. Keep those links one level deep from SKILL.md.

Subagent Files

One Agent per File

A subagent is a separate helper agent with its own instructions and its own tools. The main agent can hand a task to it, such as "review this change", and get back a result. It works in its own context, so its long work does not fill up the main conversation.

In Claude Code, a subagent is a Markdown file in .claude/agents/. The frontmatter is its settings. The body is its system prompt: the instructions it follows.

A reviewer subagent

---
name: code-reviewer
description: Reviews a change for bugs, missing tests and broken project rules. Use after code is written and before it is committed.
tools: Read, Grep, Glob
model: sonnet
---

You review code changes in the order-support repo. You do not edit files.

## Scope

Only the files changed in this task.

## Checks

1. Money is handled as integer paise, never floating point.
2. Every new API route has a test in `test/api/`.
3. Nothing updates or deletes rows in `refund_log`.

## Output format

A list of findings. Each one: the file and line, the problem, and a suggested fix. If there are none, reply "No findings."

The body says three things clearly: what it looks at (scope), what it checks (checks) and what it returns (output format). A reviewer with no output format returns something different every time.

When a Subagent File Is Skipped

Claude Code skips a subagent file, without any warning in the session, if it has no name, has a name but no description, does not start with --- on line 1, or has frontmatter that does not parse.

A subagent that is silently skipped

---
name: code-reviewer
tools: Read, Grep
---

You review code changes. You do not edit files.

Open the Checks tab: SUB001 fires, because there is no description. Add one, and it passes.

Other Tools

Other tools define subagents differently. Codex uses a TOML file in .codex/agents/ instead of a Markdown file. TOML is a simple settings format: key = "value" lines. Codex needs three keys: name, description and developer_instructions (the instructions, like the body of a Claude Code subagent). Here is the same reviewer for Codex:

name = "code-reviewer"
description = "Reviews a change for bugs, missing tests and broken project rules. Use after code is written and before it is committed."
developer_instructions = """
You review code changes. You do not edit files.
Only review the files changed in this task.
Reply with a list of findings: file and line, the problem, and a fix.
"""

The idea is the same in every tool: a name, a description of when to use it, and instructions. Only the file format changes. Your tool's path:

Tools change often. These paths were checked against each tool's docs in October 2026; check again before you rely on them.

Where This Is Used

• Team workflows: a skill per repeated task, such as checking a refund, writing release notes or fixing a flaky test.
• Shared libraries of skills: folders copied between repos, because the format is the same everywhere.
• Reviews: a reviewer subagent that checks every change against the team's rules.
• Long tasks: subagents that search or test in their own context, so the main conversation stays short.

Common mistakes

Quick Check

Exercises

What to Remember

• A skill is a folder with a SKILL.md file: frontmatter, then instructions for one kind of task.
• name and description are required. The name is lowercase with hyphens and matches the folder.
• The description says what the skill does and when to use it, in the words people type, plus "Do not use for …".
• Quote a description that contains : , or the frontmatter breaks and the skill disappears.
• Skills load in stages: metadata first, the body when picked, references only when needed. Keep SKILL.md under 500 lines.
• A subagent file has a name, a description, optional tools and model, and a body that is its instructions.
• Give a subagent a scope, its checks and an output format.

Further Reading

• Agent Skills specification: the SKILL.md format and its field rules.
• Claude Code: subagents: subagent files, fields and locations.
• The Agent Skills course on this site: how to design, test and secure a skill.

Next: Specs and Plans, where you turn a vague ticket into a spec with goals, non-goals and acceptance criteria that an agent can build from.