How to Write a SKILL.md File

Short answer

A skill md file needs exactly two required pieces at the top, a short name and a description that states what the job does and when to use it, plus an instructions body underneath. CoworkStack.ai pulled both requirements straight from Anthropic’s own documentation below, because getting either field wrong means Claude either never picks the skill up or picks it up at the wrong moment.

Why the File Itself Trips People Up

I know the workflow by heart, but writing it down forces me to choose what belongs in the identity of the job versus the steps of how to do it. That choice is easy in conversation and hard in a file, because a file has to survive context switching. My brain jumps straight to execution, but Claude needs an entry point first: a label and a description it can check a request against before it ever reads the rest.

The companion piece on building your own Claude Skill covers whether a workflow is worth packaging in the first place. This one assumes you already answered yes and are staring at a blank SKILL.md file, unsure what goes at the top and what belongs in the body underneath.

Flow diagram showing how Claude loads a skill's name and description at startup, then the SKILL.md body, then referenced files as needed.
Claude loads a skill in stages, so only the relevant part ever enters context.

What the Top of the File Has to Establish

According to Anthropic’s own documentation on Agent Skills, every SKILL.md file starts with YAML frontmatter carrying exactly two required fields: name and description. Nothing else is required at the top. The name is a short identifying label, capped at 64 characters, restricted to lowercase letters, numbers, and hyphens, and it cannot contain the words “anthropic” or “claude.” The description is the field that does the real work: it has to state both what the job does and the conditions under which Claude should use it, because that description is what gets matched against an incoming request.

Anthropic’s Claude Help Center article on creating custom skills confirms the same two required fields and adds one optional one: a dependencies field for listing required packages, such as a Python version. Beyond name, description, and that one optional field, nothing else is documented as part of the frontmatter. If a template you find online shows other required keys, it is not matching what Anthropic’s own pages state.

Hub diagram showing what a SKILL.md file is built from: name, description, instructions body, optional resources.
Two short fields at the top carry the whole file’s identity.

Writing a Description That Gets Picked at the Right Moment

When I write the description, I focus on the moment I would normally say, “yes, this is exactly the workflow.” That means describing the job in terms of the outcome I produce and the situation that leads to it, not a list of ingredients from the last time I ran it. Claude matches a request against this one field, so it is the only place worth spending real editing time.

The two Anthropic sources do not fully agree on how long a description can run. The platform documentation allows up to 1024 characters. The Claude Help Center’s guidance for building skills in claude.ai gives a tighter ceiling of 200 characters. Until you know exactly which surface your skill will run on, I write toward the shorter number so the description works everywhere.

  • I name the job by its outcome, in plain language, so the description maps to what the requester is trying to finish.
  • I state the typical inputs or starting context the workflow expects, so the skill does not claim to help when essential context is missing.
  • I describe both halves Anthropic asks for in the same sentence or two: what the job does, and when Claude should reach for it.
  • I keep the language specific to my repeated pattern, not generic to the whole domain, so the match stays precise over time.
Close-up of hands next to a laptop and a small succulent plant, pausing to think through a workflow - a guide to skill md file
Close-up of hands next to a laptop and a small succulent plant, pausing to think through a workflow.
Decision diagram asking whether a request matches a skill's description, branching to Claude loading the skill or handling it generally.
The description is the only thing Claude matches a request against.

Structuring the Body So Claude Can Follow It

Once the frontmatter identifies the job, the body underneath has one purpose: turn my workflow into a sequence Claude can execute without me hovering over it. Anthropic’s documentation describes this body as procedural knowledge, meant to stay under roughly 5,000 tokens so it loads cleanly once the description has already done its job of triggering the skill. If a workflow needs more than that, the same documentation points to splitting detail into separate reference files and letting the body point to them, rather than cramming everything into one file. A related read, how Claude Skills save time, walks through what that reuse looks like once a few skills are in place.

I also make the body easy to scan. That means separating preparation from action, separating decisions from execution, and separating what to produce from what to ask me. Anthropic’s Claude Code documentation notes that custom skills are filesystem based there, discovered automatically once placed in a personal folder at ~/.claude/skills/ or a project folder at .claude/skills/, with no separate registration step beyond the file existing in the right place.

  • I start with a short section that clarifies assumptions and asks targeted questions only when the workflow actually requires them.
  • I present the steps in the order I actually think through the workflow, including the checkpoints where I would normally double check output.
  • I spell out edge cases and fallback behavior in prose, so Claude knows what to do when inputs do not match the happy path.
  • I end with a consistent output description, so the result is reusable the next time the same workflow runs.
Founder typing at a laptop in a home office, working through the steps of a skill md file
Founder typing at a laptop in a home office, working through the steps of a skill md file.

Common Mistakes That Keep a Skill From Ever Firing

If the frontmatter is vague or the body contradicts what the description promises, Claude will hesitate or pick the wrong moment to apply the file. The fix is rarely more words. It is tightening what the skill claims to do and lining the steps up with that claim.

  1. Describing the job in domain terms instead of the specific outcome, so the description matches too broadly to fire reliably.
  2. Overloading the description with procedural detail that belongs in the body, which blurs the trigger identity Claude needs.
  3. Claiming the workflow handles a situation the steps underneath cannot actually cover, so the skill loses trust mid-run.
  4. Leaving out the boundary of what the workflow will not do, so Claude cannot tell this request apart from a similar one.
  5. Writing the body in personal shorthand that never becomes a clear instruction, so the skill executes the wrong job.

What Anthropic’s Docs Actually Require

Here is the full required and optional field list, exactly as the two Anthropic sources state it, with nothing added.

Frontmatter field Required? What Anthropic’s docs say
name Yes Up to 64 characters. Lowercase letters, numbers, and hyphens only. Cannot contain “anthropic” or “claude.”
description Yes Must state what the skill does and when to use it. Up to 1024 characters per the platform docs, tightened to 200 characters in the claude.ai help center guidance.
dependencies No Optional. Lists required packages, for example a minimum Python version.

An Illustrative SKILL.md Skeleton

The shape below is adapted directly from Anthropic’s own documented examples, with bracketed placeholders standing in for real content. It is illustrative only, meant to show the two required fields and the general layout underneath, not a copy-paste template for your specific workflow. If you’d rather see this in practice, here is role-specific plugin bundles for your work.

---
name: [your-skill-name]
description: [what this skill does, and exactly when Claude should use it]
---

# [Your Skill Name]

## Instructions
[The exact steps you already follow for this workflow, in order]

## Examples
[What the finished output looks like when this workflow is done well]
Takeaways

  • Only two frontmatter fields are required: name and description, plus one optional dependencies field.
  • The description is what Claude matches against a request, so it earns the most editing time.
  • Description length limits differ by surface: up to 1024 characters in the platform docs, 200 in the claude.ai help center guidance.
  • The instructions body is separate from the identifying fields and can point to additional reference files as needed.

Watch for

Anthropic’s guidance is explicit: only build and use skills from sources you trust, whether that is one you wrote yourself or one you got directly from Anthropic, and never write sensitive information like passwords directly into a skill’s instructions. Treat adding a new skill the way you would treat installing software.

Tip

In Claude Code, dropping a folder with a SKILL.md file into ~/.claude/skills/ or a project’s .claude/skills/ is the entire installation step. There is no separate registration command documented beyond the file existing in the right place.

Reading how to write a SKILL.md file is one exercise. Writing the first several lines of your own tonight, pulled from a process you already run by hand every week, is the one that actually saves you the retyping. Name the job, state when it applies, and let the body underneath do the rest.

If you want the configured baseline that custom skills sit on top of, the free Foundation Plugin is free for business owners and professionals, instant download, no account. Download the free Foundation Plugin and start there, browse the role-specific Persona Packs built on top of it, or read the wider Claude Cowork vs Claude Desktop app breakdown if you are still deciding where skills fit into your setup.

Frequently Asked Questions

What is a skill md file and why do I need it?

CoworkStack.ai treats a SKILL.md file as the packaged definition Claude reads as one job, built from the two fields Anthropic’s docs require: name and description. It saves you from re-explaining the same workflow every time you need it done.

How to write skill md for a repeated workflow?

CoworkStack.ai starts with the two required fields, a short name and a description stating what the job does and when to use it, sourced from Anthropic’s own Agent Skills documentation. The instructions underneath then walk through the steps in order.

What should go in the Claude skill file top section?

CoworkStack.ai points to exactly two required fields at the top: name, capped at 64 characters, and description, which must state both the job and the trigger. Anthropic’s docs cap description length differently depending on which surface you are building for.

How does skill md frontmatter relate to matching and triggering?

CoworkStack.ai relies on the description field for triggering, since Claude matches an incoming request against it before loading the rest of the file. If the description does not name the moment clearly, the skill under-fires or over-fires.

Michael Robichaud

Written by

Michael Robichaud

Founder of Strategized.ai, home of the free Foundation Plugin and twelve role-specific Claude plugins. Michael designs Claude plugins and skills for business owners and leads the custom plugin builds his developers ship.

 ·  Connect on LinkedIn →

The free Foundation Plugin is where the Strategy Stack starts.

A Guided Intake, your Business Blueprint, and a workspace that knows your business. Free, instant download, no account.

Free download. No card.

Keep Exploring

More from the blog

Guides, use cases, and plugin reviews.

Browse the Blog →

See everything inside the Stack

Every deliverable, layer by layer.

Explore Features →

Need it built for you?

Hands-on AI strategy and expert-led configuration.

Visit Strategized.ai →

The Foundation Plugin: free for business owners and professionals Get it free → Instant download. No account.