Title: Agent Skills: The Little Markdown Files Teaching Your Coding Agent Your Job Slug: agent-skills-explainer Categories: Software Development, Artificial Intelligence Excerpt: A skill is just a folder with a Markdown file in it — and it’s quietly become the standard way to teach AI coding agents how your project works. This week, Anthropic handed the whole format to a neutral foundation. Here’s what a skill is, why it caught on, and why you should write one.
The news in one paragraph
On October 22, at the AGNTCon + MCPCon conference in San Jose, the Agentic AI Foundation (AAIF) — the Linux Foundation body that already hosts the Model Context Protocol — announced four new projects, including Anthropic’s Agent Skills. Anthropic isn’t just contributing code; it’s donating the Agent Skills name, logo, GitHub organization, and the agentskills.io domain, so the standard is no longer owned by any one company. Linux Foundation announcement · Anthropic’s announcement
If you use a coding agent — Claude Code, Cursor, GitHub Copilot, VS Code, Codex, or any of the 70-plus platforms Anthropic says have integrated the format — you’ve probably already bumped into skills without knowing it. Time to understand the thing that’s been quietly doing your onboarding.
What a skill actually is
A skill is a folder. That’s the whole trick:
my-skill/
├── SKILL.md # required: metadata + instructions
├── scripts/ # optional: code the agent can run
├── references/ # optional: docs it reads on demand
└── assets/ # optional: templates, data files
The SKILL.md file starts with a small YAML frontmatter block with exactly two required fields: a name (lowercase, hyphenated) and a description — what the skill does and, crucially, when to use it. The rest of the file is plain Markdown: the steps, the conventions, the things to check. Something like:
---
name: code-review
description: Review a pull request against this project's standards. Use when asked to review code or a PR.
---
# Code review
1. Check for security issues first, then error handling.
2. Flag naming that breaks the project's conventions.
3. Run the test suite and report what passed and failed.
No runtime, no package manager, no registry account. If your agent can read files, it can in principle use a skill.
Why it caught on: progressive disclosure
The clever part isn’t the format — it’s the loading. The agent doesn’t stuff every skill into its context window. At startup it sees only each skill’s name and description, roughly 100 tokens apiece. It loads the full SKILL.md body only when a task matches the description, and it touches the scripts and reference files only if the job actually needs them. Claude Code’s Agent SDK docs describe the same flow
That means you can have dozens of skills installed without bloating the agent’s working memory, and the agent only “learns” the playbook for the job in front of it. It’s the difference between a colleague who has read every manual in the building and one who knows which shelf to reach for.
Anthropic built skills while developing Claude Code, after finding that the agent handled general knowledge work fine but lacked the procedural knowledge real business tasks need — the house style, the deployment checklist, the quirks of an internal API. Within weeks of the October 2025 launch, developers had published thousands of skills on GitHub and written loaders for Codex, Cursor, and OpenCode. Anthropic published the format as an open standard in December 2025, and by its own count the ecosystem has since grown to 1 million published skills and nearly 280 million installations.
Why handing it to a foundation matters
A standard owned by one company is a risk for everyone else building on it. Donating Agent Skills to the AAIF — where engineers from Anthropic, Google, OpenAI, and others will maintain it as individuals — means rivals can help shape it and users worry less about lock-in. Anthropic’s David Soria Parra put it plainly: “We’re donating Agent Skills to the AAIF to ensure that anyone building with skills can shape what’s next.”
The same announcement shows the pattern spreading. The AAIF’s four new projects cover four layers of the agent stack: Agent Skills (how agents gain capabilities), OpenAI’s Open Responses (one shared format for talking to models across providers), Hugging Face’s OpenEnv (shared training environments for agents), and Alibaba’s OpenSandbox (contained environments for agents to run in). Together with MCP, the Agent2Agent protocol, AGENTS.md, and the rest, the foundation went from three projects at launch in December 2025 to ten in under a year.
The catch: vet skills like scripts
Because a skill can include a scripts/ folder that the agent may execute, installing a random skill from the internet deserves the same caution as piping a stranger’s install script into your shell. Read the SKILL.md before you install it, check what the scripts do, and prefer skills from authors or projects you already trust. The format is deliberately simple — which is also what makes it easy to audit.
Write your first skill this week
Pick one thing you explain to every new collaborator (or every new agent session): your code review checklist, your release process, how you write a changelog entry. Write it down once as a SKILL.md in your project’s skills folder, with a description that says exactly when it applies. The next time you — or anyone on your team, using a different agent — hit that task, the playbook is already on the shelf.
That’s the real story behind this week’s announcement: the most useful AI infrastructure of the last year isn’t a bigger model. It’s a folder of Markdown files, written once, readable everywhere.
Links to explore further: