Agent Skills Explained: How They Work and How to Create One

Agent SkillsAI AgentsAI Workflow

June 27, 2026

Agent Skills Explained: How They Work and How to Create One

By Synthex

AI agents are useful until they have to repeat the same specialized workflow again.

Then the weak spots show up. You explain the same constraints. You paste the same checklist. You remind the agent which tool to use. You correct the same mistake. You ask for the same output format.

Agent Skills are a way to package that repeatable knowledge so the agent can load it when the task needs it.

This guide is based on the Agent Skills documentation. The short version is simple: an Agent Skill is a folder with a SKILL.md file inside it. That file tells a compatible agent what the skill is for, when to use it, and how to do the work.

You do not need to understand the whole specification before creating your first useful skill. Start with one repeated workflow, one clear description, and one small file.

What you'll learn

What Agent Skills are.
What goes inside a SKILL.md file.
Why the description matters so much.
How progressive disclosure keeps skills from filling the context window too early.
How to structure a useful first skill.
When to add scripts/, references/, or assets/.
How to test whether a skill triggers at the right time.
How to evaluate whether a skill actually improves output quality.
What tool builders need to support if they want Agent Skills to work.

What this is really about

An Agent Skill is not just a longer prompt.

It is a small, portable instruction package for a specific kind of work.

For example, you might create a skill for:

Cleaning messy CSV files.
Reviewing privacy-sensitive copy.
Preparing a client handoff.
Extracting structured data from PDFs.
Creating a consistent weekly report.
Checking a design against a brand system.
Running a safe migration checklist.

The point is not to make the agent smarter in a general way. The point is to give it specific procedural knowledge it would not reliably infer on its own.

A good skill answers: "When this kind of task appears, what does the agent need to know so it stops guessing?"

That makes skills especially useful for work that has:

Repeated steps.
Fragile commands.
Domain-specific rules.
Known edge cases.
Required output formats.
Validation steps.
Scripts or templates that should be reused.

The simplest possible Agent Skill

At minimum, a skill is a folder with a SKILL.md file:

monthly-report/
└── SKILL.md

Inside SKILL.md, you need YAML frontmatter at the top, followed by normal Markdown instructions.

---
name: monthly-report
description: Use this skill when the user asks to create a monthly report from notes, metrics, or status updates. It helps organize inputs into a clear summary, risks section, decisions section, and next steps.
---

## Workflow

1. Identify the reporting period.
2. Collect the available notes, metrics, and decisions.
3. Separate confirmed facts from open questions.
4. Create a concise report with:
   - Summary
   - Progress
   - Risks
   - Decisions
   - Next steps
5. End with anything that still needs human review.

That is enough to be useful.

The frontmatter tells the agent what the skill is called and when to consider it. The body tells the agent what to do after it activates the skill.

The important parts of SKILL.md

The Agent Skills specification defines the core shape of a skill.

For beginners, the most important fields are:

Part	Required	What it does
`name`	Yes	The short identifier for the skill
`description`	Yes	Tells the agent when this skill should be used
Body Markdown	Yes	Gives the actual instructions
`license`	No	Describes licensing if needed
`compatibility`	No	Notes environment requirements
`metadata`	No	Extra key-value information for clients
`allowed-tools`	No	Experimental field for pre-approved tools

The name should be lowercase, hyphenated, and match the folder name. Keep it simple:

name: csv-cleanup

The description is more important than it looks.

It is not just a summary for humans. It is the main clue the agent uses to decide whether to load the skill.

Weak:

description: Helps with reports.

Better:

description: Use this skill when the user wants to turn notes, metrics, meeting updates, or project status into a clear monthly report with summary, risks, decisions, and next steps.

The better version includes the user intent, adjacent phrases, and the expected result. That gives the agent more chances to recognize the right moment.

How skills load without wasting context

The core design idea is progressive disclosure.

That means the agent does not load every full skill at the start of a session.

Instead, it usually works in three stages:

Stage	What loads	Why it matters
Discovery	Skill names and descriptions	The agent can see what skills exist
Activation	The full `SKILL.md` body	The agent gets instructions only when needed
Execution	Referenced scripts, assets, or docs	Extra resources load only when the task calls for them

This is why the description has so much weight. It is the first thing the agent sees. If the description is too vague, the skill may never activate. If it is too broad, the skill may activate for tasks where it does not belong.

Think of the description as the skill's front door.

What to put in the skill body

The skill body should contain what the agent needs to do the task well.

Useful sections include:

Workflow: the order of operations.
Inputs: what the agent should look for before starting.
Output format: the exact structure the final answer or file should follow.
Gotchas: mistakes the agent is likely to make.
Validation: how the agent should check its own work.
Scripts: bundled commands the agent can run.
References: when to load deeper documentation.

Avoid filling the skill with general advice the agent already knows.

Weak:

Handle errors carefully.
Use best practices.
Make the output professional.

Better:

## Gotchas

- If the input has missing dates, put those rows in `needs-review.csv` instead of guessing.
- If two client names look similar, keep both and add a note in the review section.
- Never overwrite the original input file. Write cleaned output to `output/cleaned.csv`.

Specific corrections are much more useful than polite advice.

A practical folder structure

Small skills can be one file.

Larger skills can include supporting folders:

client-handoff/
├── SKILL.md
├── scripts/
│   └── collect-files.py
├── references/
│   └── handoff-checklist.md
└── assets/
    └── handoff-template.md

Use these folders when they actually reduce complexity.

Folder	Use it for
`scripts/`	Reusable executable code
`references/`	Longer documentation the agent should load only when needed
`assets/`	Templates, examples, schemas, or other reusable files

Keep the main SKILL.md focused. If it becomes a giant manual, the agent may struggle to find the part that matters.

The better pattern is:

If the client asks for a formal handoff, read `assets/handoff-template.md` before writing the final document.

That tells the agent exactly when to load the extra file.

How to write a good description

A skill only helps if the agent knows when to use it.

Good descriptions usually do three things:

Say when to use the skill.
Name the kind of user intent it supports.
Include nearby words a real user might type.

Use this pattern:

Use this skill when the user wants to [outcome], especially when they mention [common inputs, files, tools, or situations]. It helps with [main steps or deliverables].

Example:

description: Use this skill when the user wants to clean, analyze, summarize, or visualize tabular data from CSV, TSV, Excel, or spreadsheet exports. It helps inspect columns, handle missing values, create derived fields, generate charts, and produce a short findings report.

Notice what this does:

It says when to use the skill.
It covers several ways the user might describe the task.
It focuses on the outcome, not the internal implementation.
It stays specific enough to avoid triggering on every data-related request.

Test whether the description triggers

Do not assume the description works because it sounds clear.

Make a small list of test prompts:

Prompts that should trigger the skill.
Prompts that should not trigger the skill.

For example, a spreadsheet analysis skill should probably trigger for:

I have a CSV of store sales. Can you find the top products and make a chart?

It should probably not trigger for:

Can you write a database import script for this CSV?

Both mention CSVs. Only one is really an analysis task.

Start with about 20 realistic prompts if you are serious about tuning the description: roughly half positive and half negative. Include casual language, file paths, vague phrasing, and near-misses.

Then run the prompts through the agent and watch whether the skill activates. Because model behavior can vary, run each prompt more than once if the skill matters.

Test whether the skill improves the result

Triggering is only the first test.

A skill can activate correctly and still produce weak output.

To evaluate quality, compare results:

Run	Purpose
Without the skill	Baseline
With the skill	Current behavior
With an older version	Regression check

For each test case, define:

The prompt.
Any input files.
The expected output.
A few assertions that can be checked.

Good assertions are concrete:

The output file is valid JSON.
The report includes at least three risks.
The chart has labeled axes.
The cleaned CSV preserves the original row order.

Weak assertions are fuzzy:

The output is good.
The report sounds professional.
The chart looks nice.

Some things still need human review. Writing quality, visual judgment, and taste are not always clean pass/fail checks. Use assertions for objective checks, then add human review for the parts that require judgment.

When to add scripts

Scripts are useful when the workflow needs repeatable execution, not just instructions.

Use scripts/ when:

A command has several fragile flags.
The same transformation runs often.
The task needs parsing, validation, or file generation.
You want consistent error messages.
You want a dry run before changing files.

For small one-off tool calls, you may not need a bundled script. A pinned command can be enough:

npx markdownlint-cli2@0.15.0 "**/*.md"

For anything more complex, a script is usually safer.

Agent-friendly scripts should:

Avoid interactive prompts.
Accept input through flags, stdin, or environment variables.
Provide useful --help output.
Print structured data to stdout when possible.
Send warnings and progress messages to stderr.
Use meaningful exit codes.
Support --dry-run for risky operations.
Be idempotent when retries are possible.

This matters because agents read script output to decide what to do next. A clear error message can save an entire failed loop.

How clients support Agent Skills

If you are building an agent or tool that supports skills, the lifecycle is straightforward in concept:

Discover skill folders.
Parse each SKILL.md.
Disclose the skill catalog to the model.
Activate the full skill when relevant.
Manage skill context over time.

Local agents can scan project-level and user-level folders. The common cross-client convention is .agents/skills/, although each client may also have its own native folder.

At discovery time, the client usually loads only:

name
description
the path or location of the skill

When the model decides a skill is relevant, the client can either let the model read the SKILL.md file directly or provide a dedicated activation tool that returns the skill content.

The important implementation detail is trust.

Project-level skills come from the folder or repository the agent is working in. If that folder is untrusted, loading its instructions silently can be risky. A skills-compatible client should think carefully about trust prompts, permissions, filtered skills, and diagnostics.

A simple first skill to build

If you have never made a skill, start with something boring and useful.

Good first candidates:

Weekly status report.
Invoice summary.
Client handoff.
CSV cleanup.
Meeting notes cleanup.
Blog outline review.
File naming cleanup.

Avoid starting with:

A huge "do everything" skill.
A fragile deployment skill.
A skill that sends emails or changes production data.
A skill that needs many tools before you understand the basic shape.

Here is a simple first-skill checklist:

Pick one repeated task.
Create a folder with the same name as the skill.
Add SKILL.md.
Write a specific name and description.
Add a short workflow.
Add one output template.
Add a gotchas section.
Test 5 prompts that should trigger it.
Test 5 prompts that should not trigger it.
Improve the description before adding more complexity.

That order keeps the work small enough to understand.

Common misunderstandings

"A skill is just a prompt"

Not quite.

A prompt is usually a one-time instruction. A skill is a reusable package with metadata, activation logic, instructions, and optional resources.

"A good skill should explain everything"

No.

A good skill explains what the agent would otherwise get wrong. If the agent already knows something reliably, leave it out. Extra context has a cost.

"The description is just documentation"

No.

The description is the activation signal. If it is weak, the skill may sit unused.

"Scripts make a skill better by default"

No.

Scripts help when execution needs consistency. They add maintenance cost. Use them when they reduce mistakes, not because the folder feels more serious with code in it.

"If the skill works once, it is done"

No.

A skill should be tested against varied prompts and edge cases. The useful question is not "did it work once?" The useful question is does it improve results reliably?

What to do first

Start here:

Choose one repeated workflow.
Write the simplest SKILL.md that could help.
Make the description specific enough to trigger.
Add one workflow, one output format, and two or three gotchas.
Test whether the skill activates.
Test whether output improves compared with no skill.
Add scripts or reference files only after the basic skill proves useful.

That is enough for a first version.

Agent Skills are not about stuffing every possible instruction into one folder. They are about giving agents the right reusable knowledge at the right moment, without loading everything all the time.

Final takeaway

Agent Skills are a practical way to turn repeated agent guidance into something portable, testable, and easier to reuse.

Start with one narrow workflow. Write a clear description. Keep the main SKILL.md focused. Add gotchas, templates, and validation. Use scripts only when they make execution safer or more consistent. Then test both sides: whether the skill triggers and whether it actually improves the result.

That is the useful version of skills: not a folder full of vague advice, but a small working memory for a specific kind of task.