# How to Write an AI Agent Skill

> Source: <https://reinvently.co.uk/blog/how-to-write-ai-agent-skill/>
> Published: 2026-10-19 23:00:00+00:00

[← All posts](https://reinvently.co.uk/blog/)

Skills began as an Anthropic format for Claude and are now an [open specification](https://agentskills.io/specification). Claude Code and GitHub Copilot both load them, and vendors have started shipping their own: Microsoft's [azure-skills](https://github.com/microsoft/azure-skills) repository packages skills for Azure work alongside the Azure MCP Server.

The format is simple, so writing a skill is quick. Writing one that helps is harder. Many early skills restate what the model already knows about Python or SQL, which costs context and adds nothing. The useful ones encode knowledge the model could not have picked up in training: your definitions, your processes and the mistakes you have watched agents make.

This guide is also available as a [12-slide deck](#get-slides) to share with your team.

## What a Skill Is

A skill is a directory. The only required file is `SKILL.md`, which holds YAML frontmatter between two `---` lines and then instructions in Markdown. The [Agent Skills specification](https://agentskills.io/specification) also defines three optional folders: `scripts/` for code the agent can run, `references/` for documentation it reads on demand, and `assets/` for templates and data files.

Microsoft's azure-ai skill uses only two of these:

```
azure-ai/
├── SKILL.md          # frontmatter and instructions (required)
└── references/
    └── sdk/          # 14 SDK guides, read only when needed
```

Two frontmatter fields are required. `name` is up to 64 lowercase letters, digits and hyphens, and must match the folder name. `description` is up to 1,024 characters and should say what the skill does and when to use it. Optional fields include `license`, `compatibility`, a free-form `metadata` map and an experimental `allowed-tools` list.

### How a skill differs from an MCP server

An MCP server hands an agent a fixed set of tools: query this database, call that API. A skill tells the agent how to use what it has: which steps, in what order, what to avoid and what you prefer. Coding agents already have a terminal and file access. When they fail, the missing piece is usually knowledge rather than a tool. Skills can bundle scripts as well, so they can add abilities, but most of their value is in the guidance.

## How Agents Load a Skill in Three Stages

Agents do not read every installed skill in full. They load each one progressively, which is what lets you install dozens without filling the context window. Anthropic's engineering team [describes the same three levels](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) as the specification.

1. **Metadata, always loaded.** At startup the agent reads each skill's name and description, about 100 tokens per skill. This is how it decides whether a skill applies.
2. **Instructions, on invocation.** When the user calls the skill or the agent judges it relevant, it reads the whole`SKILL.md` body. The specification recommends keeping that under 5,000 tokens and 500 lines.
3. **References, when needed.** Files under`references/` ,`scripts/` or`assets/` are read only when the task calls for them.

Write each level so it tells the agent when to read the next. The description says when to load the skill; the body says when to open each reference file. A reference the body never mentions will rarely be read.

In practice, every line in the body is a recurring cost. Claude Code's [documentation](https://code.claude.com/docs/en/skills) notes that once a skill is invoked, its body stays in context for the rest of the session.

## Writing a Description That Triggers Correctly

The description is the only part of the skill that is always in context, so it does more work than anything else in the file. It fails in two directions.

| Description | What happens | 
|---|---|
| Helps with Azure. | Too vague. The agent cannot tell when it applies, so it rarely loads. | 
| Use for anything involving Azure, the cloud or AI. | Overpromises. It loads for tasks it was not written for and crowds out better guidance. | 
| Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. … WHEN: AI Search, query search, vector search, … | Names what it covers and the phrases that should trigger it. Abridged from Microsoft's azure-ai skill. | 

Put the main use case first and include the words a user would actually type. Microsoft ends its descriptions with an explicit `WHEN:` list of trigger phrases, which is a pattern worth copying. Claude Code truncates the combined description at 1,536 characters in its skill listing, so the opening sentence matters most.

## What Belongs in a Skill and What Does Not

Models already know the major languages and frameworks, and they can read `--help` output and error messages. That kind of technical guidance gets less useful with each model release. What a model cannot learn from training data is how your organisation works.

A useful test is to imagine a technically excellent new hire. They can write SQL on their first day. They do not know that your "active customer" excludes trial accounts, that your financial year starts in April, or that the reporting warehouse is a day behind the operational database. Those facts belong in a skill.

| Put in | Leave out | 
|---|---|
| Definitions, processes and preferences specific to your organisation | General knowledge the model already has, such as Python basics | 
| Mistakes you have watched agents make, and the correction | Anything the agent can find cheaply by reading files or running a command | 
| Guidance reused across projects, or needed only for some tasks | Rules for one repository: put those in its agent instructions file | 

More is not safer. Long, prescriptive skills can confuse an agent as easily as they help it, and they make it harder to spot which instruction caused a bad result.

## Worked Example: Microsoft's azure-ai Skill

The [azure-skills](https://github.com/microsoft/azure-skills) repository is Microsoft's official agent plugin for Azure, MIT licensed and installable in GitHub Copilot CLI and Claude Code. Its azure-ai skill, abridged:

```
---
name: azure-ai
description: Use for Azure AI: Search, Speech, OpenAI, Document
  Intelligence. ... WHEN: AI Search, query search, vector search, ...
license: MIT
metadata:
  author: Microsoft
  version: "1.2.2"
---
# Azure AI Services
| Service | Use When | MCP Tools | CLI |
...
## MCP Server (Preferred)
...
If Azure MCP is not enabled: run /mcp and enable Azure MCP.
SDK guides: references/sdk/
```

Five choices in it are worth borrowing:

- **Explicit triggers.** The description ends with a`WHEN:` list, so the agent matches on the user's own words.
- **One routing table.** Each service is mapped to when to use it, its MCP tools and its CLI, so the agent picks a route without exploring.
- **A preferred path and a fallback.** Use the Azure MCP tools, such as`search_query` ; if the server is not enabled, tell the user to enable it through`/mcp` .
- **Detail on demand.** Code-level guidance sits in 14 reference files under`references/sdk/` , split by service and language, and is read only when needed.
- **Versioned like code.** A version number in the metadata and a Git history behind it.

What it encodes is what a model could not guess: Microsoft's own tool names, its preferred route and how to recover when that route is missing. It does not try to teach the agent Python.

## Installing, Invoking and Versioning a Skill

A skill only works properly when it is installed where the agent's harness looks for it. Pasting the file into a prompt or pointing the agent at it loses progressive disclosure and the harness's own handling.

| Harness | Project skills | Personal skills | 
|---|---|---|
| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` | 
| GitHub Copilot | `.github/skills` ,`.claude/skills` or`.agents/skills` | `~/.copilot/skills` or`~/.agents/skills` | 

Users can invoke a skill directly, for example by typing `/azure-ai` in Claude Code, or let the agent load it when the description matches. For skills with side effects, such as deploying or sending messages, Claude Code's `disable-model-invocation: true` field stops the agent from running them on its own.

Keep skills in Git next to the code or data model they describe, review changes to them as you would code, and give each one an owner. A skill that drifts from the system it describes gives confident, wrong guidance. Anthropic also [advises](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) installing skills only from trusted sources and auditing any bundled scripts first, since a malicious skill can direct an agent to leak data.

## Iterate on Real Tasks, Then Cut

Do not try to write the complete skill up front. Anthropic's advice is to "start with evaluation": run the agent on representative tasks, find where it struggles, and build the skill to close those gaps.

1. **Run.** Give an agent a real task you already know how to do.
2. **Observe.** Note where it made wrong assumptions or got stuck.
3. **Add.** Write guidance for that gap only.
4. **Re-test.** Run the same task again with the skill installed.
5. **Cut.** Remove or rephrase anything that did not change the result.

Repeat the loop, and revisit skills when you change models. Each release needs less help, and guidance a newer model no longer needs is pure cost.

### Before you share a skill

- The description names what the skill covers and when to use it.
- Every line passes the new-hire test.
- Detail lives in `references/` , and the body says when to read each file.
- It is installed in the harness, kept in Git and has an owner.
- You have tested it on a real task and cut what did not help.

## Get the slides

This guide as a 12-slide deck (PDF), with the worked example and checklist, ready to share with your team. Enter your email and we will send you the download link. We will occasionally send you new research too; unsubscribe in one click. See our [privacy policy](https://reinvently.co.uk/privacy/).

## Agent Skills FAQ

### What is the difference between a skill and an MCP server?

An MCP server gives an agent a fixed set of tools: what it can do. A skill gives it context: which steps to take, in what order, what to avoid and what your organisation prefers. Skills can bundle scripts too, so the line is not absolute, but most skills are written guidance.

### How long should a SKILL.md file be?

The Agent Skills specification recommends keeping `SKILL.md` under 500 lines and the body under about 5,000 tokens. Move detail into files under `references/` and tell the agent when to read each one.

### Should guidance go in a skill or in the repository's agent instructions?

If the guidance applies to one repository only, put it in that repository's agent instructions file. Use a skill for guidance that is reused across projects or only needed for some tasks.

**Sources.** [Agent Skills specification](https://agentskills.io/specification); Anthropic, [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (16 October 2025); Anthropic, [Claude Code skills documentation](https://code.claude.com/docs/en/skills); GitHub, [About agent skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills); Microsoft, [azure-skills](https://github.com/microsoft/azure-skills) and its [azure-ai SKILL.md](https://github.com/microsoft/azure-skills/blob/main/skills/azure-ai/SKILL.md) (version 1.2.2, checked 20 October 2026).

*New research and engineering guides land here first. [Sign up for email updates](https://reinvently.co.uk/contact/).*

[← All posts](https://reinvently.co.uk/blog/)