--- title: "How to Write an Agent Skill: A Step-by-Step Guide" url: "https://atlan.com/know/ai-agent/ai-agent-skills/how-to-write-an-agent-skill/" description: "Learn how to write an agent skill: name the SKILL.md frontmatter, structure the steps, bundle resources, validate data sources, then test before shipping." author: "Emily Winks" author_role: "Data Governance Expert" published: "2026-07-16" updated: "2026-07-16T00:00:00.000Z" --- --- Seven steps make up a working SKILL.md, and a 238-skill study found more than 99% still ship with at least one authoring defect. You'll find the same discipline behind agent tooling at Atlan, Alation, Collibra, Databricks, and Informatica: treat the `name` and `description` fields as non-negotiable before you write a single instruction line. **Time to complete:** 2 to 4 hours **Difficulty:** Beginner to intermediate **Prerequisites:** a capability gap already identified, Claude Code or claude.ai with Agent Skills enabled, and read access to the data source **Tools needed:** a text editor, Claude Code or claude.ai, and optionally the `skill-creator` meta-skill | Step | Action | Output | |---|---|---| | 1 | Identify the capability gap | A one-sentence task name and 3 to 5 test queries | | 2 | Write the frontmatter | A `name` and `description` that trigger reliably | | 3 | Structure the body | A lean SKILL.md under roughly 500 lines | | 4 | Bundle scripts and resources | `scripts/`, `references/`, `assets/` as needed | | 5 | Validate the data sources | A checked, owned, current data path | | 6 | Test with held-out queries | Confirmed trigger accuracy | | 7 | Iterate | A revised, re-tested skill | --- ## Why write an agent skill instead of a longer prompt? A skill exists because a long, repeated prompt does not persist across sessions, does not compose with other skills, and does not improve each time you use it. A SKILL.md file does all three. Barry Zhang, who co-created Agent Skills at Anthropic, put it this way: "Skills are organized collections of files that package composable procedural knowledge for agents. In other words, they're folders." That portability is why [skill engineering](https://atlan.com/know/ai-agent/ai-agent-skills/what-is-skill-engineering/) sits above [harness engineering](https://atlan.com/know/what-is-harness-engineering/) and [context engineering](https://atlan.com/know/what-is-context-engineering/) in the prompt-to-skill lineage, a discipline that states plainly it is [not a skills problem](https://atlan.com/know/context-engineering-framework/). A portable procedure is only half the question; the other half is what Step 5 covers. --- ## Prerequisites for writing your first agent skill This is a practitioner checklist for authoring one skill, not the org-wide rollout checklist a platform team uses for a registry, which lives on Atlan's [enterprise skills governance guide](https://atlan.com/know/what-are-enterprise-skills/). Before you open a text editor, confirm: - A named, repeated task, not a vague "we should have some skills" ambition - An environment with Agent Skills enabled (Claude Code or claude.ai) - Read access to whatever table, file, or API the skill will touch - 5 to 10 test queries, including at least one that should *not* trigger the skill ![Seven-step workflow for writing an agent skill, from identifying the capability gap to iterating after testing](https://website-assets.atlan.com/img/how-to-write-an-agent-skill-1-seven-step-workflow.webp "From capability gap to a tested, governed skill") --- ## Step 1: Identify the capability gap your skill will fill Name the repeated task in one sentence, the way practitioner Bibek Poudel's worked examples do (a README writer, a commit-message generator). If you cannot name it in one sentence, it is not narrow enough yet. Write 3 to 5 realistic queries a user would type, including a negative case. Then confirm a skill, rather than a [tool call](https://atlan.com/know/ai-agent/ai-agent-tool-use/) or a subagent, is the right fit, one of the [AI agent primitives](https://atlan.com/know/ai-agent/ai-agent-primitives/) worth distinguishing before you invest in a full [agent harness](https://atlan.com/know/ai-agent/agent-harness-vs-agent-framework/). Skipping this is the most common reason a skill ends up vague, the same discipline [how to build an AI agent harness](https://atlan.com/know/how-to-build-ai-agent-harness/) applies one rung down. Not sure a skill is the right layer yet? See where skills, harnesses, and governed context each do their job before you commit to writing one. Get the AI Context Stack --- ## Step 2: Write the SKILL.md frontmatter, name and description Bibek Poudel, author of "The SKILL.md Pattern," states the converging finding across every source in this research directly: "If your skill does not trigger, it is almost never the instructions. It is the description." Write `name` in lowercase, hyphens only, never "anthropic" or "claude." Write `description` in third person, stating what the skill does *and* when to use it, per [DigitalOcean Community (2026)](https://www.digitalocean.com/community/tutorials/how-to-implement-agent-skills). | Field | Limit | Rules | |---|---|---| | `name` | 64 characters | lowercase letters, numbers, hyphens only; no XML tags; no "anthropic"/"claude" | | `description` | 1,024 characters | non-empty, no XML tags, third person, states what and when | A minimal, correctly scoped frontmatter block: ```yaml --- name: release-notes-writer description: >- Generates release notes from a git commit log. Use when the user asks to summarize recent commits into a changelog entry. --- ``` --- ## Step 3: Structure the body with progressive disclosure Keep the body under roughly 500 lines, per Anthropic's own guidance, and under about 5,000 tokens once activated, per the [Agent Skills open standard's specification](https://agentskills.io/specification.md). Match instruction specificity to task fragility: high freedom for judgment calls, an explicit script for anything fragile. Write workflows and checklists, not an essay, the same three-level model teams building a [context engineering framework](https://atlan.com/know/how-to-build-context-engineering-framework/) apply one rung down: metadata always loaded, body loaded on trigger, bundled files loaded on demand. --- ## Step 4: Bundle scripts and reference resources Deterministic logic belongs in `scripts/`; lookup tables and style guides belong in `references/`, read only when relevant. Anthropic's own production skills for docx, pdf, pptx, and xlsx bundle real executable scripts rather than prose descriptions. A skill paired with a CLI frequently beats an equivalent [MCP](https://atlan.com/know/mcp/why-mcp-matters-for-ai-agents/) call on speed and cost. A skill that must remember what it did last time should log its own actions, the pattern Atlan calls [procedural memory](https://atlan.com/know/semantic-memory-vs-procedural-memory-ai-agents/), one of four types an [agent's memory](https://atlan.com/know/what-is-agent-memory/) covers, and decide whether the fetch should go through [MCP or a direct function call](https://atlan.com/know/mcp-vs-function-calling/). | Tool | Purpose | When you need it | |---|---|---| | Text editor | Write SKILL.md and bundled files | Always | | Claude Code or claude.ai | Run and test the skill | Always | | `skill-creator` meta-skill | Create, Eval, Improve, Benchmark modes | Optional, speeds up Steps 6 to 7 | | Version control | Track changes across iterations | Recommended once the skill ships | --- ## Step 5: Validate the data sources your skill will read from Before you finalize the procedure, check who owns the data your skill reads from, when it was last certified, and whether a conflicting definition exists elsewhere, the step every how-to source in this research skips, Anthropic's own best-practices doc included. Evaluation-first testing confirms the *procedure* produces the right output; it says nothing about whether the *data* it reaches for is correct. A skill can pass every evaluation query and still confidently report a wrong number from a stale table, and the stakes are higher than a one-off script, since a skill is invoked, unreviewed, hundreds of times. Ask three questions: who owns the source, when was it last certified, and does a competing definition exist elsewhere? Then route the read through a [governed context source](https://atlan.com/know/how-to-implement-enterprise-context-layer-for-ai/) rather than a raw table. Atlan's own enterprise skills guidance names the fix: "The skill instructs how. The context layer guarantees what's true," the same argument [why AI agents need an enterprise context layer](https://atlan.com/know/why-ai-agents-need-an-enterprise-context-layer/) and the [data quality failures](https://atlan.com/know/data-quality-ai-agent-harnesses/) both make. A SKILL.md makes the procedure durable across many future invocations, so an unvalidated source risks encoding a bad assumption into a reusable artifact. Is the data behind your skill actually ready? Check readiness before you wire a skill's bundled resources to a live business data source. Check your context readiness --- ## Step 6: Test your skill with held-out queries Write 5 to 7 queries that should trigger the skill and 3 to 5 that should not, none reused from Step 1, then hold out roughly 40% as a validation set to check a fix actually generalizes. This comes from [Anthropic's own post on improving `skill-creator`](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills). If the skill fails to trigger, revisit the description first, the same held-out discipline [testing an AI agent harness](https://atlan.com/know/how-to-test-ai-agent-harness/) applies one rung down. | Query type | Count | Purpose | |---|---|---| | Should-trigger | 5 to 7 | Confirm the description matches real invocations | | Should-not-trigger | 3 to 5 | Confirm no false positives or scope creep | | Held-out validation | Roughly 40% of total | Check whether fixes generalize beyond the tuning set | --- ## Step 7: Iterate based on how Claude actually uses it Use the skill for real and note where it hesitated, misfired, or produced the wrong shape of output. Fix the smallest thing first, usually the description, then re-run the held-out set. Anthropic's own `skill-creator` meta-skill runs four composable sub-agents across Create, Eval, Improve, and Benchmark modes, a faster start than building evaluation tooling from scratch. Treat the first working version as a first draft, not a finished skill. --- ## Why isn't my agent skill triggering? Common mistakes The single most common failure a reader following this tutorial will hit is a skill that "should" trigger and does not. The root cause is nearly always the description, consistent with [a UC Irvine study of 238 real-world skills](https://arxiv.org/abs/2607.01456) (Hong, Imani, and Ahmed, arXiv:2607.01456, 2026), which found more than 99% of published SKILL.md files contain at least one authoring-quality defect. ### Why isn't my Claude skill triggering? The description states what the skill does but not when to use it. Rewrite it in third person, name the triggering scenario, and test it against a query it should *not* match. ### Degrees-of-freedom mismatch A fragile task described with too much latitude produces inconsistent output; a judgment-based task over-specified with rigid steps produces brittle failures. Adjust the freedom level in the opposite direction. ### Context bloat from an oversized body Covering every edge case in the main body instead of splitting into `references/` files (Step 3) slows triggering and bloats context. Audit for rare-case content and move it out. [Agent harness anti-patterns](https://atlan.com/know/agent-harness-failures-anti-patterns/) documents the same failure one layer down. ### Skipping the data-source validation step The skill "works": it loads, follows the procedure, produces formatted output that reads as proof it is correct. Nothing checked whether the table is current or owned. Treat any confidently wrong output as a data-validation gap first, an instructions bug second. --- ## What separates a reliable agent skill from a fragile one? Five practices, ranked by impact. Nail the description first: no other fix moves trigger accuracy as much. Keep the body lean, under roughly 500 lines and 5,000 tokens activated. Match degrees of freedom to task fragility; as Philipp Schmid puts it, "describe what you want, not the path to get there." Evaluate before you write prose, with test queries drafted first. And validate the data source before you finalize the procedure, re-checking owners whenever revised. A skill that clears all five is well-authored; whether it's trustworthy still depends on the data question Step 5 raises. --- ## How does Atlan ground the data an agent skill reads from? A skill can pass every evaluation Anthropic recommends and still be wrong, because evaluation tests the procedure, not the data it reaches for. Teams shipping their first Agent Skills report the skill "working" while the answer is wrong, since it can't know if the table it just queried is stale, deprecated, or uncertified, the same pattern documented in [agent harness data-quality failures](https://atlan.com/know/data-quality-ai-agent-harnesses/) one rung down: the failure is rarely in the control layer, it is beneath it. Atlan's context layer delivers certified metadata, lineage, and access policy through an [MCP server](https://atlan.com/know/mcp/why-mcp-matters-for-ai-agents/), so Step 5's check becomes a live query against a [governed context source](https://atlan.com/know/agent-context-layer/), not a manual audit. Skills map to what Atlan calls procedural memory, alongside the semantic layers a skill's [context graph](https://atlan.com/know/what-is-a-context-graph/) draws from, backed by [AI-ready data and knowledge graphs](https://atlan.com/know/ai-readiness-vs-knowledge-graphs/) and a [semantic layer](https://atlan.com/know/ai-agent/semantic-layer-for-ai-agents/) that defines what a metric means. None of this replaces [governance](https://atlan.com/know/ai-agent-governance/) over who can ship a skill; it answers whether what the skill reads is still true. --- ## Real stories from real customers: MCP-delivered context for AI agents "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 See the context layer live Watch governed context flow into an agent skill via MCP. Watch the Live Demo Series --- ## A tested SKILL.md is not the same as a trustworthy one Passing every evaluation query in this guide proves your skill triggers correctly and follows its procedure. It does not prove the answer is right, since that depends on data this tutorial's testing step never touches. Once shipped, [what are agent skills](https://atlan.com/know/ai-agent/ai-agent-skills/what-are-agent-skills/) is the fuller foundational read, and [skill engineering vs prompt engineering](https://atlan.com/know/ai-agent/ai-agent-skills/skill-engineering-vs-prompt-engineering/) traces why this discipline needed a data-trust step no earlier rung required. Revisit Step 5's checklist periodically: a source current when you wrote the skill can go stale later. Book a Demo --- ## Sources 1. [Skill authoring best practices, Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) 2. [Equipping agents for the real world with Agent Skills, Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) 3. [The SKILL.md Pattern: How to Write AI Agent Skills That Actually Work, Bibek Poudel (Medium)](https://bibek-poudel.medium.com/the-skill-md-pattern-how-to-write-ai-agent-skills-that-actually-work-72a3169dd7ee) 4. [8 Tips for Writing Agent Skills, Philipp Schmid](https://www.philschmid.de/agent-skills-tips) 5. [anthropics/skills GitHub repository](https://github.com/anthropics/skills) 6. [anthropics/skills, skill-creator meta-skill source](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) 7. [Improving skill-creator: Test, measure, and refine Agent Skills, Anthropic](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) 8. [How to implement agent skills, DigitalOcean Community](https://www.digitalocean.com/community/tutorials/how-to-implement-agent-skills) 9. [Claude Skills are awesome, maybe a bigger deal than MCP, Simon Willison](https://simonw.substack.com/p/claude-skills-are-awesome-maybe-a) 10. [Enterprise Skills: A Governance Guide for AI Teams, Atlan](https://atlan.com/know/what-are-enterprise-skills/) 11. [From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills, arXiv](https://arxiv.org/abs/2607.01456) 12. [Agent Skills Specification, agentskills.io](https://agentskills.io/specification.md) --- ## FAQs about writing an agent skill 1. **How do I write a good description for an agent skill?** State it in third person, describing what the skill does and when to use it, not a summary of its contents. Improving the description alone is the single most common fix. 2. **Why isn't my Claude skill triggering?** Almost never the instructions, it is the description. Rewrite it to state the triggering scenario in plain, third-person language, then test it against a query it should NOT match. 3. **How long should a SKILL.md file be?** Keep the body under roughly 500 lines, splitting anything past that into separate reference files. The activated body should stay under roughly 5,000 tokens, per the Agent Skills open standard. 4. **Do I need to write code for a skill, or can it be just markdown?** Markdown alone is enough for many skills. Add `scripts/` only for deterministic logic, and use `references/` for lookup material the skill reads but doesn't execute. 5. **How do I test an agent skill before shipping it?** Write 5 to 10 fresh queries, mixing should-trigger and should-not-trigger cases, and hold out roughly 40% as a validation set to confirm fixes generalize. 6. **Can I use Claude itself to help write a skill?** Yes. Anthropic's own `skill-creator` meta-skill runs four modes (Create, Eval, Improve, Benchmark), a faster start than building evaluation tooling from scratch.