The Winning Agent Format Is a Folder Full of Markdown

There is a particular kind of triumph in the AI world that looks unimpressive at first glance. The repository in question contains no model weights, no clever runtime, no distributed anything. It is, at bottom, a collection of folders. Each folder holds a markdown file, maybe some scripts, maybe some reference documents. That is the whole invention — and it is currently eating the agent ecosystem from the inside.

The repo is anthropics/skills, Anthropic’s implementation of what it calls Agent Skills. The README is careful to point readers to the Agent Skills standard itself at agentskills.io, which is the tell: this is not just a demo bucket. It is the reference implementation of a format Anthropic is actively trying to make universal. And by most accounts, the attempt is working — one overview of the standard claims it is now supported by more than 25 agent frameworks, which is a remarkable adoption curve for what is essentially a file-naming convention.

The problem: expertise that dies with your tool

To understand why a folder of markdown deserves attention, you have to understand the mess it addresses. AI coding assistants — Claude Code, Cursor, Gemini CLI, GitHub Copilot — operate in silos. A team that has spent months teaching its assistant the house code-review checklist, the deployment rituals, the unwritten rules of the monorepo, discovers that all of that investment is trapped. Switch tools, and you start from zero. As one writeup of the standard put it, the format is being received as something like npm or pip for AI expertise: a portable, shareable packaging unit for capability.

The deeper problem is architectural. For a couple of years, the default answer to “make the model better at X” was to stuff more instructions into the system prompt. That approach scales badly. Every instruction is loaded on every request, whether or not it is relevant, which wastes the context window and — worse — degrades performance as the prompt bloats into a wall of contradictory guidance. Google’s own explainer on the topic describes engineering teams moving away from monolithic system prompts toward modular, version-controlled skills precisely because monoliths are hard to audit, hard to debug, and expensive to run.

The boring part, which is the good part

So what is a skill, mechanically? A folder. Inside it, a required file called SKILL.md, which has two parts: YAML frontmatter carrying a name and a description, and a markdown body containing the actual instructions. Around that core, optional subdirectories — scripts the agent can execute, reference documents it can read on demand, assets like templates. No build step, no packaging toolchain, no manifest to compile. It is plain text in a predictable layout, which means it diffs cleanly, reviews cleanly, and sits happily in the same repository as the code it describes.

This is where the design earns its keep. The description in the frontmatter is the discovery surface: the agent reads a short summary of what the skill does and when to use it, without loading the body. Google’s documentation breaks the lifecycle into tiers — discovery, where metadata on the order of a hundred tokens per skill is loaded at startup; activation, where the full SKILL.md is read only when a task matches; and execution, where referenced files or scripts are pulled in selectively. The industry term for this is progressive disclosure, and it is the difference between an assistant that knows what it knows and one that recites everything it knows at the start of every conversation.

The scripts directory deserves a mention because it quietly resolves a chronic agent weakness. LLMs are unreliable at producing deterministic output — formatting a spreadsheet cell as currency, say, or extracting form fields from a PDF in exactly the same way twice. A skill can simply hand that job to a Python script. The model decides when to run it; the script guarantees what it produces. Determinism moves out of the weights and into the folder.

What’s actually in the repo

The repository itself is a mixed bag by design. The example skills span creative work (art, music, design), technical tasks (web app testing, MCP server generation), and enterprise workflows (communications, branding). Most are Apache 2.0. The README is candid that these are demonstration material — it carries a disclaimer that implementations and behaviors in Claude may differ from what is shown, and that everything should be tested before being trusted for critical work. That honesty is refreshing; this is a pattern library, not a product.

The genuinely interesting artifacts are the document skills. The folders for docx, pdf, pptx, and xlsx are the ones that power Claude’s document-creation capabilities in production — the features Anthropic ships to paying users. And they are explicitly not open source; the repo calls them source-available, shared as reference material for developers building complex skills. This is a notable split: Anthropic will show you the blueprints of its production machinery, but the license keeps the machinery itself from being freely reused. Whether that lands as generous transparency or as openwashing depends, as usual, on which side of the license you stand.

There is also early evidence of an ecosystem forming around the format. Notion has published partner skills for Claude, and the standard’s boosters claim it has spread beyond coding into legal, finance, and healthcare — the canonical example being a law firm encoding its SaaS contract review process (liability caps, IP rights, termination clauses) as a skill. When a format escapes its home domain, that is usually the signal that it has stopped being a feature and started being infrastructure.

Positioning: not MCP, not fine-tuning

The obvious question is how this relates to everything else in the agent stack. The Model Context Protocol connects agents to live external systems — databases, APIs, the outside world. Skills, by contrast, are procedural memory: how to do a thing, written down. Google’s explainer frames the two as complementary, and the framing holds — MCP is plumbing, skills are playbooks.

Against fine-tuning, the comparison is more pointed. Fine-tuning bakes knowledge into weights: powerful, but expensive to change, opaque, and permanently married to one model. A skill is external, swappable, and editable by anyone who can write markdown. For the large class of “teach the agent our process” problems, that trade is a rout. You do not retrain a model to follow your brand guidelines; you hand it a folder.

It also slots neatly into the broader agent-framework conversation. The framework guides — LangChain’s among them — argue that what separates demo-grade from production-grade agents is reliability, observability, and reproducibility, not prototyping speed. Skills are a small but real contribution to that side of the ledger: a workflow encoded as a skill is version-controlled, auditable, and behaves the same way across runs in a way that an artisanal 4,000-token prompt never will.

The honest caveats

None of this means the format is a solved problem. The security surface is real. A skill is executable-adjacent text that agents load and act on, which makes it a delivery vehicle for supply-chain attacks and indirect prompt injection — a malicious skill published to a shared registry is a poisoned dependency with better manners. Google’s Agent Platform addresses this with sandboxed execution governed by IAM policies, and pre-built security skills exist for secret detection and dependency auditing, but the ecosystem-wide answer is still forming. Anyone who lived through the early days of npm left-pad and typosquatting knows how this movie tends to go once sharing becomes convenient.

There is also the fair criticism that this is, technically, glue. A folder of markdown does not do anything; the intelligence remains in the model, and the format merely organizes what the model is told. That criticism is accurate and misses the point simultaneously. Standards work at this layer almost always looks trivial in hindsight — JSON, YAML, container images. The value is not in any single folder; it is in a million folders that all look the same, so that every agent, every team, and every vendor can exchange expertise without ceremony.

The unresolved tension is governance. Anthropic originated the format and ships the reference implementation, but the standard now lives at agentskills.io and claims support across dozens of frameworks, including competitors’ tooling. Whether the standard stays genuinely neutral — or drifts toward whatever Claude’s runtime happens to support best — is the open question that will determine whether this becomes a public good or a moat with good documentation.

Outlook

Where this heads is fairly legible. Skills registries, skill linters, skill review processes in pull requests, security scanning for shared skills — the entire apparatus that grew up around package management, rebuilt one layer up, for instructions instead of code. The enterprise appeal is obvious: reproducible, auditable agent behavior is exactly what compliance teams have been asking for since the first agent touched a production system.

The repo itself will probably matter less over time, which is arguably the plan. If anthropics/skills succeeds as a reference implementation, it becomes the example everyone copies from rather than the thing everyone depends on — the way nobody thinks about the first JSON parser anymore. For now, it is worth browsing precisely because it is ordinary: a company with some of the strongest models in the field concluding that the most useful thing it could standardize is not intelligence, but the filing system for it.