--- title: "What Are Agent Skills? SKILL.md, Structure, and How They Work" url: "https://atlan.com/know/ai-agent/ai-agent-skills/what-are-agent-skills/" description: "Agent Skills package a reusable AI procedure in a SKILL.md file. Learn the frontmatter rules, progressive disclosure, and how 40+ platforms use the format." author: "Emily Winks" author_role: "Data Governance Expert" published: "2026-07-15" updated: "2026-07-15T00:00:00.000Z" --- --- An Agent Skill packages a repeatable procedure into a `SKILL.md` file your agent loads without a rewrite, the same format Atlan, Anthropic, Cursor, GitHub Copilot, and Snowflake Cortex Code support, one of 40-plus platforms. Atlan's context layer asks what most guides skip: whether that data is trustworthy, since a 2026 study found 99%+ of SKILL.md files carry an authoring flaw. --- | Field | Value | |---|---| | What It Is | A folder standard (`SKILL.md` plus optional `scripts/`, `references/`, `assets/`) packaging a reusable procedure | | Key Benefit | Progressive disclosure keeps roughly 100 tokens loaded per skill, so context cost stays flat as libraries grow | | Best For | Repeated, well-defined agent tasks, not one-off requests | | Adoption | About 40 platforms as of mid-2026, including Claude, OpenAI Codex, GitHub Copilot, and Snowflake Cortex Code | | Core Components | YAML frontmatter (`name`, `description`), a `SKILL.md` body under 500 lines, optional bundled folders | | Known Risk | Over 99% of published `SKILL.md` files carry at least one "skill smell," 36% of community skills carry a security flaw | Inside Atlan AI Labs and the 5x Accuracy Factor See how governed context, not just a better-structured procedure, drove a 5x accuracy gain in real production agent systems. Download E-Book --- ## What is an agent skill? An Agent Skill is a folder containing a `SKILL.md` file that teaches an AI agent a specific, repeatable procedure, from formatting a report to querying a particular database schema. It bundles instructions with optional scripts, reference docs, and templates, so the agent follows the same procedure every time it recognizes the task, instead of re-explaining it each conversation. Anthropic published the concept in ["Equipping agents for the real world with Agent Skills"](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (October 2025). Barry Zhang, Member of Technical Staff at Anthropic, framed it this way: "Building a skill for an agent is like putting together an onboarding guide for a new hire." Two months later, [agentskills.io published the open specification](https://agentskills.io/home), stewarded by the Agentic AI Foundation, turning a Claude-specific mechanism into a portable standard. A skill is not a single tool call, and it is not a fully autonomous [agent harness](https://atlan.com/know/what-is-an-agent-harness/). It sits between the two: a reusable procedure a capable agent applies at the right moment, then sets aside once the task is done. That distinction matters for how a skill fits [the rest of the discipline](https://atlan.com/know/ai-agent/ai-agent-skills/what-is-skill-engineering/), how it compares to [context engineering versus prompt engineering](https://atlan.com/know/context-engineering-vs-prompt-engineering/), and how it relates to [tools and the Model Context Protocol](https://atlan.com/know/ai-agent/ai-agent-skills/agent-skills-vs-mcp/), covered later. --- ## How does a SKILL.md file work? A `SKILL.md` file has two required frontmatter fields, followed by a Markdown body kept under 500 lines. Progressive disclosure loads metadata first, the body on trigger, and bundled files only when referenced, so an unused skill costs almost nothing to keep installed. ### YAML frontmatter: the required fields | Field | Max Length | Rules | |---|---|---| | `name` | 64 characters | Lowercase letters, numbers, hyphens only; cannot include "anthropic" or "claude" | | `description` | 1,024 characters | The trigger text the agent matches against, out of potentially hundreds installed. Too vague and the skill never fires; too broad and it fires on the wrong tasks | ### Progressive disclosure: the three-level loading model Progressive disclosure is what makes large skill libraries affordable. The runtime loads three levels as each becomes necessary: | Level | What Loads | Token Cost | When It Loads | |---|---|---|---| | Level 1 | Frontmatter metadata | About 100 tokens | Always loaded, for every installed skill | | Level 2 | The `SKILL.md` body | Under 5,000 tokens | Loaded only when the description matches the task | | Level 3+ | Bundled `scripts/`, `references/`, `assets/` | Effectively zero until accessed | Loaded only when the body points the agent there | A team running 50 installed skills pays roughly 5,000 tokens of standing context, not 50 times each skill's full body. [Per Anthropic's Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), that split keeps skills cheap to install as a library grows. ### Bundled resources: scripts, references, and assets Three optional folders sit alongside `SKILL.md`: **`scripts/`** for executable code, **`references/`** for longer documentation the agent reads only when it needs depth (the same separation a broader [context engineering framework for AI agents](https://atlan.com/know/context-engineering-for-ai-agents/) applies at a wider scale), and **`assets/`** for templates the skill produces or consumes. Structural rigor is not a data-quality guarantee. A schema a skill's script queries against can drift the same way an [agent harness](https://atlan.com/know/data-quality-ai-agent-harnesses/) component's schema drifts. [A systematic study of `SKILL.md` as a software artifact](https://arxiv.org/abs/2607.01456v1) found over 99% of 238 real-world skills contain at least one "skill smell." Aaron Imani, a co-author, notes skill smells "rarely disappear as skills evolve," the same failure-cataloging instinct behind research on [agent harness failures and anti-patterns](https://atlan.com/know/agent-harness-failures-anti-patterns/). A skill can satisfy every rule above and still carry a flaw the taxonomy would flag. --- ## Why are teams building agent skills? Teams build Agent Skills when the same task keeps getting re-explained to an agent, the procedural version of the problem [AI agent memory](https://atlan.com/know/what-is-agent-memory/) solves for facts and conversation history. Enterprise adoption is already visible: [Atlassian, Canva, Cloudflare, Figma, Notion, Ramp, Sentry, Stripe, and Zapier all ship skills through Anthropic's own directory](https://agentman.ai/blog/agent-skills-ecosystem-report-2026), and Anthropic added organization-wide skill management and audit trails for Team and Enterprise plans in February 2026. The ecosystem backs that up: [agentskills.io lists roughly 40 adopting products](https://agentskills.io/home), from Cursor and VS Code to Databricks Genie Code. Quality varies: [SkillsBench, the first peer-reviewed benchmark built for the format, aggregated 47,150 skills and found curated libraries raised average task pass rates by 16.2 percentage points over no skills at all](https://arxiv.org/abs/2602.12670), a gap wide enough that it sparked its own [Hacker News debate](https://news.ycombinator.com/item?id=47040430) over whether the benchmark tested self-generated skills fairly. A skill earns its keep on a genuinely repeated task, per the Hacker News discussion on ["you're probably using Agent Skills wrong."](https://news.ycombinator.com/item?id=48624327) The [agent context layer](https://atlan.com/know/agent-context-layer/) an agent operates against does not change that, only whether the output is trustworthy once the skill triggers, a question [AI agent governance](https://atlan.com/know/ai-agent-governance/) treats as a standing requirement. --- ## Creating an agent skill: a quick overview Creating a skill starts with a real, repeated task, not a blank template. The short version: name the trigger, write the `SKILL.md` body, bundle only what the agent needs, and test before shipping. 1. Identify a genuinely repeated task, per the note above, rather than authoring from a single session 2. Write the frontmatter (`name`, `description`) and a focused `SKILL.md` body 3. Bundle only what is needed in `scripts/`, `references/`, or `assets/` 4. Test the skill against real runs before treating it as finished, the same [AI agent observability](https://atlan.com/know/ai-agent-observability/) discipline any production agent component needs For the full step-by-step, including validating the data a skill acts on before encoding the procedure, see [How to Write an Agent Skill](https://atlan.com/know/ai-agent/ai-agent-skills/how-to-write-an-agent-skill/). ![Four steps to create an agent skill: identify a repeated task, write frontmatter and body, bundle only what's needed, test before shipping](https://website-assets.atlan.com/img/what-are-agent-skills-1-creating-a-skill-flow.webp "Turn a repeated workflow into a reliable, reusable agent skill") --- ## Agent skills vs. tools vs. MCP A tool is a single discrete action an agent can call. [MCP](https://atlan.com/know/what-is-atlan-mcp/) is the connection layer that gives an agent access to external systems and data. A skill is neither: it is the reusable procedure that tells the agent how to use tools and MCP connections well, repeatedly, a distinction that matters to [agent engineering](https://atlan.com/know/agent-engineering/). Tuana Çelik, Senior Developer Relations Engineer at LlamaIndex, draws the practical line: MCP servers "are quite effective at predictable and precise execution" for ["deterministic API calls with fixed schemas,"](https://www.llamaindex.ai/blog/skills-vs-mcp-tools-for-agents-when-to-use-what) whereas skills suit procedures that need judgment. | Question | Tools | MCP | Agent Skills | |---|---|---|---| | What is it | A single callable action | A connection and access layer | A reusable, packaged procedure | | Grain | Discrete, atomic | Infrastructure-level | Task-level, composable | | What it needs to be reliable | A correct schema | A correct auth path | Trustworthy underlying data (see below) | None of these three layers is trustworthy by default: a tool is only as good as its schema, an MCP connection only as good as its auth path, a skill only as good as the data behind it. See [Agent Skills vs MCP](https://atlan.com/know/ai-agent/ai-agent-skills/agent-skills-vs-mcp/), [Agent Skills vs Tools](https://atlan.com/know/ai-agent/ai-agent-skills/agent-skills-vs-tools/), [MCP vs. function calling](https://atlan.com/know/mcp-vs-function-calling/), and [when to use MCP instead of a plain API](https://atlan.com/know/when-to-use-mcp-vs-api/) for the fuller comparisons. AI Agent Context Readiness Checklist Check whether the data your skills, tools, and MCP connections will act on is actually ready for production agent use. Check Readiness --- ## How Atlan approaches agent skills Atlan treats Skills the same way it treats any other context asset: versioned, tested, and governed through a Build, Test, Review, Approve, Deploy, Learn lifecycle inside the [Context Engineering Studio](https://atlan.com/know/context-engineering-framework/), the same discipline behind [how to build a context engineering framework](https://atlan.com/know/how-to-build-context-engineering-framework/). A `SKILL.md` file can pass every structural check above and still be only half the story: what it reads is the other half. Atlan's [Enterprise Data Graph](https://atlan.com/know/what-is-a-context-graph/) exists so a skill can pull certified, current context at the moment it runs, rather than trust that whatever table it was pointed at during authoring is still accurate months later. [Governed Context for Agent Skills](https://atlan.com/know/ai-agent/ai-agent-skills/governed-context-for-agent-skills/) makes the full case for why the data layer under a skill matters as much as the procedure itself. --- ## Real stories from real customers: context behind every agent skill "We're excited to build the future of AI governance with Atlan. All of the work that we did to get to a shared language at Workday can be leveraged by AI via Atlan's MCP server...as part of Atlan's AI Labs, we're co-building the semantic layer that AI needs with new constructs, like context products." — Joe DosSantos, VP of Enterprise Data & Analytics, Workday Watch Now "Atlan is much more than a catalog of catalogs. It's more of a context operating system...Atlan enabled us to easily activate metadata for everything from discovery in the marketplace to AI governance to data quality to an MCP server delivering context to AI models." — Sridher Arumugham, Chief Data & Analytics Officer, DigiKey Watch Now Neither quote is about skill authoring specifically, but both point at the same shift: a procedure is only as good as the context operating system feeding it. See the Context Layer in Action Watch a live walkthrough of how Atlan certifies the data your agents, tools, and skills read at runtime. Watch the Demo --- ## Why the file is only half the story Agent Skills give agents a portable, token-efficient way to reuse a procedure. Every source that defines the format, Anthropic's own docs, the open standard at [agentskills.io](https://agentskills.io/home), the skill-smells research, grades the file: is the frontmatter valid, is the body under 500 lines, does the description trigger correctly. None asks whether what the skill reads is still true. That is not a hypothetical gap. [Snyk's ToxicSkills audit scanned 3,984 skills](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/) in February 2026 and found 36% carried at least one security flaw. A skill can pass every check in that audit and still confidently return a wrong answer, because the table it queried was stale, deprecated, or never certified. A structurally flawless `SKILL.md` is still only the procedure layer. What decides its output is the [governed context layer](https://atlan.com/know/business-context-layer/) underneath it, the same principle behind [the context layer for harness engineering](https://atlan.com/know/context-layer-harness-engineering/), the question [Governed Context for Agent Skills](https://atlan.com/know/ai-agent/ai-agent-skills/governed-context-for-agent-skills/) takes on directly. **What to explore next:** - [What Is Skill Engineering?](https://atlan.com/know/ai-agent/ai-agent-skills/what-is-skill-engineering/): the broader lineage this page sits inside - [The SKILL.md File Explained](https://atlan.com/know/ai-agent/ai-agent-skills/skill-md-file-explained/): a deeper structural cut at the format - [What Is Harness Engineering?](https://atlan.com/know/what-is-harness-engineering/): the discipline a skill often runs inside - [Context Infrastructure for AI Agents](https://atlan.com/know/context-infrastructure-for-ai-agents/): the maturing layer beneath skills and harnesses - [Semantic Layer Explained](https://atlan.com/know/semantic-layer/): how it relates to skill and harness context - [How to Build an AI Agent Harness](https://atlan.com/know/how-to-build-ai-agent-harness/): construction guidance for that layer - [How to Implement an Enterprise Context Layer for AI](https://atlan.com/know/how-to-implement-enterprise-context-layer-for-ai/): the data side of what this page seeds - [Harness Engineering vs Prompt Engineering](https://atlan.com/know/harness-engineering-vs-prompt-engineering/): a neighboring discipline compared - [What Are Enterprise Skills?](https://atlan.com/know/what-are-enterprise-skills/): a related governance treatment at the enterprise layer - [Agent Memory Architectures](https://atlan.com/know/agent-memory-architectures/): how memory and skills both encode agent knowledge Book a Demo --- ## FAQs about agent skills ### 1. What is the difference between an agent skill and a tool? A tool is a single discrete action an agent calls with a fixed schema. An Agent Skill is a reusable procedure, packaged as a `SKILL.md` file plus optional resources, that tells the agent how and when to use tools to complete a job. ### 2. What is the difference between agent skills and MCP? MCP is the connection layer that gives an agent access to external systems and data. An Agent Skill is the procedure layer: it packages the judgment for a task, and can call MCP connections as part of that procedure. ### 3. What goes in a SKILL.md file? A `SKILL.md` file requires a `name` field (max 64 characters) and a `description` field (max 1,024 characters), followed by a Markdown body recommended to stay under 500 lines, plus optional `scripts/`, `references/`, and `assets/` folders. ### 4. What is progressive disclosure in AI agents? Progressive disclosure is the three-level loading model Agent Skills use to control context cost. Level 1 metadata stays loaded for every installed skill. Level 2, the `SKILL.md` body, loads only when a task triggers it. Level 3 bundled files load only when referenced. ### 5. Are agent skills only for Claude? No. Agent Skills became an open standard in December 2025 through agentskills.io. About 40 platforms support it now, including OpenAI Codex, GitHub Copilot, and Snowflake Cortex Code. ### 6. Are agent skills safe? What are the security risks? Not automatically. A Snyk audit of 3,984 skills found 36% contained at least one security flaw. Risk concentrates in community-published skills; review scripts and dependencies before installing, the same way you would a new software dependency. ### 7. What's the difference between the agent skills open standard and Anthropic's Skills Directory? The open standard at agentskills.io defines the portable file format any client can implement. Anthropic's Skills Directory is one distribution channel built on that format. --- ## Sources 1. Agent Skills Overview, Claude Platform Docs. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview 2. Equipping agents for the real world with Agent Skills, Anthropic. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills 3. anthropics/skills, GitHub. https://github.com/anthropics/skills 4. Skill authoring best practices, Claude Platform Docs. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices 5. Agent Skills Overview, agentskills.io. https://agentskills.io/home 6. From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills, arXiv. https://arxiv.org/abs/2607.01456v1 7. Securing the Agent Skill Ecosystem / ToxicSkills research, Snyk. https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/ 8. Skills vs MCP tools for agents: when to use what, LlamaIndex. https://www.llamaindex.ai/blog/skills-vs-mcp-tools-for-agents-when-to-use-what 9. Agent Skills ecosystem report, agentman.ai. https://agentman.ai/blog/agent-skills-ecosystem-report-2026 10. SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks, arXiv. https://arxiv.org/abs/2602.12670 11. SkillsBench discussion thread, Hacker News. https://news.ycombinator.com/item?id=47040430