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-BookWhat is an agent skill?
Permalink to “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” (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, 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. 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, how it compares to context engineering versus prompt engineering, and how it relates to tools and the Model Context Protocol, covered later.
How does a SKILL.md file work?
Permalink to “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
Permalink to “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
Permalink to “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, that split keeps skills cheap to install as a library grows.
Bundled resources: scripts, references, and assets
Permalink to “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 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 component’s schema drifts. A systematic study of SKILL.md as a software artifact 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. A skill can satisfy every rule above and still carry a flaw the taxonomy would flag.
Why are teams building agent skills?
Permalink to “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 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, 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, 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, a gap wide enough that it sparked its own Hacker News debate 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.” The 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 treats as a standing requirement.
Creating an agent skill: a quick overview
Permalink to “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.
- Identify a genuinely repeated task, per the note above, rather than authoring from a single session
- Write the frontmatter (
name,description) and a focusedSKILL.mdbody - Bundle only what is needed in
scripts/,references/, orassets/ - Test the skill against real runs before treating it as finished, the same 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.
Agent skills vs. tools vs. MCP
Permalink to “Agent skills vs. tools vs. MCP”A tool is a single discrete action an agent can call. 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.
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,” 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, Agent Skills vs Tools, MCP vs. function calling, and when to use MCP instead of a plain 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 ReadinessHow Atlan approaches agent skills
Permalink to “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, the same discipline behind how to build a 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 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 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
Permalink to “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
"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
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 DemoWhy the file is only half the story
Permalink to “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, 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 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 underneath it, the same principle behind the context layer for harness engineering, the question Governed Context for Agent Skills takes on directly.
What to explore next:
- What Is Skill Engineering?: the broader lineage this page sits inside
- The SKILL.md File Explained: a deeper structural cut at the format
- What Is Harness Engineering?: the discipline a skill often runs inside
- Context Infrastructure for AI Agents: the maturing layer beneath skills and harnesses
- Semantic Layer Explained: how it relates to skill and harness context
- How to Build an AI Agent Harness: construction guidance for that layer
- How to Implement an Enterprise Context Layer for AI: the data side of what this page seeds
- Harness Engineering vs Prompt Engineering: a neighboring discipline compared
- What Are Enterprise Skills?: a related governance treatment at the enterprise layer
- Agent Memory Architectures: how memory and skills both encode agent knowledge
FAQs about agent skills
Permalink to “FAQs about agent skills”1. What is the difference between an agent skill and a tool?
Permalink to “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?
Permalink to “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?
Permalink to “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?
Permalink to “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?
Permalink to “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?
Permalink to “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?
Permalink to “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
Permalink to “Sources”- Agent Skills Overview, Claude Platform Docs. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Equipping agents for the real world with Agent Skills, Anthropic. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- anthropics/skills, GitHub. https://github.com/anthropics/skills
- Skill authoring best practices, Claude Platform Docs. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Agent Skills Overview, agentskills.io. https://agentskills.io/home
- From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills, arXiv. https://arxiv.org/abs/2607.01456v1
- Securing the Agent Skill Ecosystem / ToxicSkills research, Snyk. https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/
- 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
- Agent Skills ecosystem report, agentman.ai. https://agentman.ai/blog/agent-skills-ecosystem-report-2026
- SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks, arXiv. https://arxiv.org/abs/2602.12670
- SkillsBench discussion thread, Hacker News. https://news.ycombinator.com/item?id=47040430
