Most of what sits in a skill folder is not a skill. It is an organisation, copied out by hand into files. And that is not sloppiness; it is what happens when the only place you have to put organisational clarity is a folder.
A skill.md should answer one question. How is this work done well? That fits in one Markdown file, and it should be cheap to change, because craft improves every week as new data emerges. The rules about who may decide what and guardrails are a different thing entirely. They need to change differently.
This is still a practical guide to writing SKILL.md files. It is for anyone working with AI, not just developers. It just draws a harder line than most guides do. That line is why skill libraries stop rotting, and it is one of the quieter reasons agent projects stall.
Is Your Organisation Ready for AI Agents?
Eight dimensions of role clarity, distributed authority, living governance, and accessible data. Find out in a few minutes.
A SKILL.md file is a plain Markdown file that tells a role-filler how to do a specific piece of work the way your organisation wants it done. It opens with a small metadata block, a name and a description, then continues as ordinary Markdown. The agent reads the description all the time, and the body only when the work calls for it. That is the whole format.
--- name: seo-and-geo-specialist description: Defines the SEO and GEO standards every content role must implement, and audits pages for compliance. Use when reviewing content before publishing, running a technical SEO audit, implementing schema, or tracking whether pages get cited by AI search engines. --- # SEO & GEO Specialist ## Use when ... ## Core standards ... ## Examples ...
The standard set by Anthropic adds optional folders around it: references/ for detail loaded on demand, scripts/ the agent runs without reading, assets/ for templates and schemas. At Nestr, we see the problems with this, as it only works when there is only one person keeping track of all of it, and knows exactly what is in what skill, or everyone works in the codebase as a developer.
Anthropic introduced Agent Skills in October 2025 and published the specification as an open standard in December 2025, with governance of the standard under the Linux Foundation's Agentic AI Foundation, alongside MCP.
Open a mature skill folder and sort every line into three piles. Craft, tools, governance. It takes 20 minutes and it is uncomfortable.
Craft is the smallest pile and the only one that belongs in the file: the standards, the technique, the worked examples, the output shape. How the work is done. Tools are the second pile, and they are honest. A script the agent executes, a schema it fills, a template it starts from. What you can use to do the work effectively. Then comes the third pile. Who owns this work, what this role may decide alone, what it must never do, who to hand off to, who maintains this file.
That third pile is your organisation and governance structure. It ended up in a folder because there was nowhere better to put it.
| What the folder holds | What it actually is | Where it belongs |
|---|---|---|
| The SKILL.md body | The craft: how this work is done well | The one file |
| Description and "use when" | Discovery of the craft | The one file |
| scripts/ and assets/ | Tools the agent runs or fills | The tool layer, reached through MCP |
| "Never do X" | A constraint on authority | A policy |
| "This role owns the live site" | A domain | The role |
| "Hand off to the Editor when done" | An accountability | The role |
| Changelog | Version history | The system's own record |
Because the failure everyone reports as a technology problem is usually an organisational problem, and a skill file is where authority goes to hide.
The scale first, as setup rather than argument. Gartner expects over 40% of agentic AI projects to be cancelled by the end of 2027, citing escalating costs, unclear value and inadequate governance (Gartner, June 2025). RAND (2024) found the single most common root cause of AI project failure is a misunderstanding about purpose and domain context. Deloitte (2026) put mature frameworks for governing autonomous agents at 21% of organisations, against 74% planning to deploy within two years. None of that is a model capability story.
Now watch how a skill file feeds it. Craft and authority sit in the same document, so nobody reviews the document for authority. An agent's boundary becomes a line item somewhere past the worked examples, and it widens one helpful edit at a time. That is permission creep, and it is invisible precisely because the file it lives in is supposed to be edited freely.
The two layers were never meant to move at the same speed. Craft should be cheap to change. You find a better way to structure an article, you edit the skill, you use it that afternoon. No proposal, no meeting, no ceremony. Speed is the point.
Authority should only change through a clear process and visibly. In a living system, a policy or an accountability moves through a process: someone raises a tension, proposes a change, and anyone can object with a reasoned argument for how it would cause harm. What comes out is a governance record with a timestamp, an author, and every prior version still readable. That trail is not bureaucracy. It is how an organisation keeps evolving its structure toward its purpose without anyone quietly rewriting the rules.
It is also what you will be asked to produce. The EU AI Act (Regulation (EU) 2024/1689) requires record-keeping and traceability from high-risk systems, and "the agent did it" is no answer when nobody can show which human role authorised what. Worse, a trail cannot be built backwards. Every month of agent work governed only by file edits is a month you cannot reconstruct.
So put a guardrail in a skill file and see what you have. It changes when somebody edits the file. No proposal, no test for harm, no record. A folder can't govern. I mean that literally: nothing in a folder can be objected to. And the mistake runs the other way just as often, where craft ends up written into policy and nobody can fix a heading rule without a governance meeting.
Because context is not free, and more instructions make the agent worse, not better.
Anthropic's engineering guidance frames context as a finite attention budget: find the smallest set of high-signal tokens that produce the outcome you want. Overfill it and you pay for those tokens on every message, before any work happens. You also degrade the model. Liu and colleagues (2024) found performance is highest when relevant information sits at the start or end of the context, and drops when the model must dig it out of the middle. A follow-up from Chroma across 18 models called the same effect context rot.
This is the drift you feel when a long-running agent forgets its earlier instructions. It is not laziness. It is structural.
Skills solve it through progressive disclosure: load a little, then more only if needed. Metadata is always loaded, roughly 100 tokens for a name and description. The body loads only when the agent decides the skill is relevant, and best practice keeps it under 500 lines. Analysis of more than 40,000 published skills found the median runs around 1,400 tokens, with 90% under 4,000. Five skills loaded in full might cost 12,500 tokens at every session start. The same five, disclosed progressively, cost around 300 until one is needed.
That is the move from prompt engineering to context engineering, and onward to harness engineering. Our piece on context engineering for AI agents makes the longer argument.
Yes. The evidence is unusually clean. SkillsBench (2026), a benchmark across 86 tasks in 11 domains, found focused skills of two to three modules outperform a single comprehensive file. Curated skills raised average pass rates by 16.2 percentage points, with the largest gains in convention-heavy domains: healthcare and manufacturing above 40 points, general software engineering around 4.5. Skills help most where your organisation does things its own way. Which is to say, where your judgement lives.
So split along the seams of the work. One skill per process or knowledge area. Split again when the body passes 500 lines, moving rarely-needed detail into a reference the agent loads only when the task calls for it. But do not over-split, because near-duplicate descriptions confuse selection.
One seam looks like a skill problem and is not. If you are splitting a file because two roles need different halves of it, the work is already divided and the file was pretending otherwise. Give each role its own skill, and let shared craft sit at circle level where both can reach it. The same logic is why smaller roles suit agents better, which we cover in the guide to building an AI agent team as a solo founder.
It reads descriptions. In the base implementation there is no clever algorithm: no embeddings, no classifier, no keyword matcher. The runtime gathers every skill's name and description, and the model chooses from those alone.
Which is why an index earns its place once you pass a handful of skills. A good index is a map of the craft. One line per skill, saying what it covers and when to reach for it, so any role can find what exists without loading anything. Research on large libraries supports this: AgentSkillOS and SkillRouter, both 2026 preprints, found flat lists cause routing collapse as libraries grow, and hierarchical organisation consistently outperformed flat.
The test is simple. If a line in your index would still be correct after you reorganised the circle, it belongs there. If reorganising would falsify it, the structure should be answering it.
Six things.
name and description. A type field earns its place: process for procedures, knowledge for domain expertise, doctrine for principles consulted before decisions.Notice what is absent. No changelog, because a living system keeps its own history and a hand-written one is a worse copy. No purpose, no accountabilities, no escalation path. And no guardrails section, which is the one that stings.
Anything answering who the role-filler is, what it is responsible for, what it may decide, or where its authority ends. This belongs in constantly adapting governance records.
A role's purpose is its reason for being, or why it exists: "surface insights that ground our content in what the audience actually needs". That is identity, not technique. Accountabilities are ongoing work the organisation can expect from a work, written as recurring activity: "monitoring industry trends and summarising findings weekly for the Content Strategist". Domains are what the role controls exclusively, the production branch or the published site. Policies grant or constrain authority: "the Content Writer may publish drafts but not live pages". All four belong in the governance records, not in a skill file.
Guardrails are the hard case, because they feel like craft. Never publish schema that misrepresents content. Never block the AI search bots that drive citations. They read like technique and behave like law. The tell is what happens when someone disagrees. A standard gets improved by whoever owns the craft. A guardrail has to be argued with, and that argument deserves a record.
Two tests keep the line clean. Would this survive a change of method? Find a better way to write articles and the writing skill changes, while the Content Writer's purpose, its accountability and its publishing policy all stand. Second: could someone reasonably object to it? Technique gets improved. Authority gets consented to. The minimum a role needs before an agent can energise it is in our MCP setup guide.
Because it is compact, familiar to the model, and readable by the people who own the craft. Multi-model testing has found Markdown uses materially fewer tokens than JSON for the same content, on the order of a third less. Models have also seen enormous quantities of it, so purpose-built formats that look more efficient often score worse on comprehension. And a non-technical domain expert can open a SKILL.md file and fix the voice rule without learning a syntax.
The description is the only thing an agent reads when deciding whether to use a skill. Not the body. If it is vague, the skill never loads and the agent improvises from general knowledge.
The rule: say what the skill does and when to use it, in the third person, in the words a real situation would contain. "Helps with content" is weak. The SEO example at the top of this article is strong, because it names triggers an agent will actually meet, including the case where someone says "I'm about to publish this" without naming the skill.
A practical test, which Anthropic's own skill-creator automates: write down about 20 situations before shipping, some that should trigger the skill and some that should not, and check the description separates them. Nine times out of 10, when a skill is not firing, the fix is there.
By giving drift an owner. A skill that was right in March is subtly wrong by June, and a library nobody tends becomes a pile of confident, stale instructions.
We give this its own role. Our Skills & Standards Auditor (energized by an AI agent) watches for skills that have fallen out of date with the field or with each other, roles holding an accountability with no supporting skill, and reviewers flagging the same defect again and again. That last one usually means the skill is the problem, not the role-filler.
Crucially, the Auditor does not rewrite skills alone. It surfaces the drift with evidence and raises a tension, and the role that owns the skill makes the change. The rhythm that surfaces these signals is the tactical meeting.
One warning from that role's own anti-patterns, because it catches everyone. Do not confuse freshness with correctness. A 90-day-old skill can be right, and a one-week-old skill can be wrong. Age is a signal to check, not a verdict.
Some skills encode how to think rather than what to do, and they matter most as agents take on more. Andrej Karpathy described the failure well in a coding context: models pick one interpretation without checking, do not surface tradeoffs, and quietly overcomplicate things. Our AI Agent Operating Principles turn that into doctrine. State your assumptions. Produce the minimum output that solves the problem. Touch only what the task requires.
Hold the line here too. Doctrine that shapes how you approach work is craft. Doctrine that determines what you may decide is a policy. "Prefer the simplest solution that works" is the first. "Any change to authentication needs a second reviewer" sounds identical and is the second.
At Nestr, we added this to the personality description of the AI role-filler. We assign those to specific roles, so those roles can act through that personality type when energizing a specific role. We do notice though that, when it comes to judgement if something serves purpose, human role-fillers are still very important, which is what I wrote about in "humans are how the organisation feels the world". Skills carry the craft. People carry the purpose.
No, not by default. A SKILL.md file is treated roughly the way a system prompt is, and a skill can bundle scripts with filesystem and API access. That is power, and it cuts both ways.
The 2026 audits are sobering, and worth reading carefully. Cisco's AI Defense team scanned around 31,000 agent skills and found 26% contained at least one vulnerability. Snyk, scanning roughly 4,000, found 36% with detectable prompt injection. Several of the loudest figures come from vendors selling scanning tools, so treat the percentage as a range. The qualitative point holds.
Install only from sources you trust, read the file and any bundled scripts first, pin versions, and sandbox anything that runs code. Then do the governance part: decide which role may adopt a third-party skill, and hold that as a policy. Installing an unreviewed skill from a stranger is a decision, so it deserves an owner and a record.
If you're reading this, you probably already have a few skills and are experimenting with AI agents. Assuming this is true, the first step is to get clarity on the role of the agent. What is its purpose, as a nested purpose of the overall organisation? What are its accountabilities?
After that is clear, you can add your clear skill file with only the elements needed for that agent to do its work in the right way. Watch it run for a week. When the agent makes the same mistake twice, evolve the skill rather than the prompt.
Our guide to safely experimenting with AI agents in your team walks through the wider pattern, and the do's and don'ts of deploying your first agent covers the culture your first skill quietly sets for every skill after it.
The model is not the bottleneck. The clarity you give it is, and most of that clarity is not craft at all. It is who decides what, held somewhere it can be seen, questioned and traced.
None of this needs a new file format. It needs us to keep the craft light enough to improve this afternoon, and to keep authority somewhere every change leaves a record. That is work we can start this week, one role at a time.
We built Nestr so a role, its policies and its skills live in one structure that agents read through MCP, with every governance change logged and visible to everyone in the organisation. The rest of the folder was never craft. So we stopped writing it.
Nestr is the governance layer where human sensors and AI synthesis sit inside the same living structure. Roles, accountabilities, domains, policies and skills, all version-controlled and reachable by your agents through MCP, so every role-filler works from a shared understanding of how the work is done and why it matters.
Build the working layer for human and AI role-fillers
Nestr is where roles, policies and skills live in one structure your agents read through MCP, with every governance change logged.
One file per skill, yes, and sometimes multiple per role. The file holds the craft, which turns out to be small once you stop putting authority in it. What grows is the number of skills, not the size of any one.
An accountability is ongoing work the organisation expects from a role. A skill is how that work is done well. Change the method and the skill changes while the accountability stands, which is the fastest test for where a line belongs.
Yes, as a one-line-per-skill map so any role can find what exists. Keep roles, triggers and handoffs out of it. Those live in the structure, and duplicating them means maintaining your organisation twice.
People, with agents drafting. SkillsBench (2026) found agent-written skills gave no benefit on average, while curated ones lifted pass rates by 16.2 percentage points. Deciding what is worth encoding cannot be delegated.
.png){kind=logo}
