How to Write an AI Agent Skill Skills, an Anthropic format for Claude that is now an open specification at agentskills.io, are loaded by both Claude Code and GitHub Copilot, and Microsoft has shipped its own azure-skills repository packaging skills for Azure work alongside the Azure MCP Server. The guide states that a skill is a directory whose only required file is SKILL.md, holding YAML frontmatter with a required name of up to 64 lowercase letters, digits and hyphens matching the folder name and a required description of up to 1,024 characters, plus optional scripts/, references/ and assets/ folders. Agents load skills in three stages — roughly 100 tokens of metadata per skill always loaded, the SKILL.md body read on invocation and recommended to stay under 5,000 tokens and 500 lines, and reference files read only when needed — and Claude Code's documentation notes that once a skill is invoked its body stays in context for the rest of the session. ← 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/