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.

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.

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.


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.

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.
- Describing the job in domain terms instead of the specific outcome, so the description matches too broadly to fire reliably.
- Overloading the description with procedural detail that belongs in the body, which blurs the trigger identity Claude needs.
- Claiming the workflow handles a situation the steps underneath cannot actually cover, so the skill loses trust mid-run.
- Leaving out the boundary of what the workflow will not do, so Claude cannot tell this request apart from a similar one.
- 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]
- 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.
