Skip to content
Veomark

How to write a SKILL.md agents will actually use

Published · Veomark editorial

Short answer

A SKILL.md needs a YAML frontmatter block with two required fields: name (lowercase letters, numbers, and hyphens only, 64 characters or fewer, and not containing "anthropic" or "claude") and description (a non-empty, third-person sentence of 1,024 characters or fewer that states both what the skill does and when to use it). Keep the body under roughly 500 lines and move detail into separate reference files linked directly from SKILL.md. Test the skill on a real task before you rely on it — passing these structural rules does not mean an agent will select or follow it correctly.

The two required fields

Anthropic's Skill authoring best-practices documentation specifies exactly two required frontmatter fields. name: 64 characters or fewer, lowercase letters/numbers/hyphens only, no XML-style tags, and cannot contain the words "anthropic" or "claude" — that restriction is specific to Anthropic's own Skill platform, not a universal rule. description: non-empty, 1,024 characters or fewer, no XML tags, and written in third person ("Extracts text from PDF files..." rather than "I extract..." or "You can use this to..."). The description is what an agent matches against dozens or hundreds of other skills' descriptions to decide whether to load this one, so state both what it does and when to use it in the same sentence.

Kimi Code CLI's bundled skill-creator skill documents the same name constraints (lowercase, hyphens, under 64 characters) independently, which is why this guide treats them as the practical baseline across hosts rather than a Claude-only quirk. Run a draft through Veomark's SKILL.md structure checker to catch these mechanically before you install anywhere.

Keep the body short; push detail into reference files

Only a skill's name and description load into context at startup — roughly 100 tokens per skill, regardless of how many skills exist. The full SKILL.md body loads only when the skill is triggered, and any files it references load only when the agent actually reads them. Anthropic's guidance is to keep SKILL.md's body under about 500 lines and split anything longer into files like reference.md or examples.md, linked directly from SKILL.md — not nested two levels deep, since agents may only partially read a file referenced from another referenced file.

Match the instruction's specificity to how fragile the task is: open-ended judgment calls (a code review) can use plain prose; a fragile, must-not-vary operation (a database migration) should specify the exact command to run and tell the agent not to modify it. Anthropic frames this as "degrees of freedom" — narrow bridge versus open field.

Test before you ship it

A structurally valid SKILL.md is not a working one. Anthropic's recommended process is evaluation-first: run the target model on a representative task without the skill, note what it got wrong or needed to be told, write three or so evaluation scenarios covering those gaps, then write the minimum SKILL.md content that passes them — rather than writing exhaustive documentation for problems that may never come up. Test with every model you plan to use it with; a skill tuned for Opus can under-explain for Haiku, and a skill written for Haiku can over-explain for Opus.

Two real, well-documented starting points if you'd rather adapt an existing skill than start from a blank file: Superpowers' writing-skills meta-skill, and Kimi Code CLI's own skill-creator, which walks through the same plan → write → package → iterate sequence for Kimi specifically.

Where the rules differ by host

SKILL.md itself is a genuinely cross-host open standard — Anthropic published it, and Claude Code, Cursor, Codex CLI, OpenCode, and other agents read the same folder-plus-frontmatter shape. But enforcement differs: Grok Build's own documentation states it "accepts model, effort, license, and compatibility and does not apply them" — meaning it tolerates extra fields other hosts use without validating them itself. The reserved-word rule on "anthropic"/"claude" is Anthropic's own constraint; a skill aimed only at Kimi or Grok would not be rejected for using those words, though avoiding them keeps the same file portable.

Don't confuse SKILL.md with AGENTS.md. AGENTS.md is a separate, free-form convention with no required frontmatter or fixed schema — see what each host actually reads for AGENTS.md, CLAUDE.md, and GEMINI.md for how that one is (and isn't) portable across Claude Code, Codex, and Gemini CLI.

Frequently asked questions

Does a valid SKILL.md guarantee Claude will use it correctly?

No. Structural validity (frontmatter present, name and description within limits, reasonable body length) is a prerequisite, not a guarantee. Whether an agent selects the skill for a given request depends on how well the description matches the actual task, and whether it follows the instructions correctly depends on the model and the instructions' clarity. Test on real tasks before relying on a skill.

What happens if my SKILL.md body is over 500 lines?

Nothing breaks automatically, but Anthropic's own guidance says performance degrades: every token in a loaded SKILL.md competes with conversation history and other context. Move detail — API references, edge-case handling, long examples — into separate files linked directly from SKILL.md, and let the agent read them only when needed.

Can I use the same SKILL.md for Claude Code, Codex, and Kimi Code CLI?

Often yes for the file itself, since all three read the same folder-plus-frontmatter format, but installation and discovery mechanics differ per host — check each host's current documentation rather than assuming identical behavior. Superpowers is a real example of one skill set documented to work across five hosts by its own publisher.

Is there a tool to check this automatically?

Veomark's SKILL.md structure checker runs these frontmatter, length, and path checks in your browser. It only checks structure — it cannot confirm that an agent actually selects or follows the skill.

Sources checked for this guide

Verified against the sources above as of 2026-09-18. Vendor documentation and product availability can change after that date — check the current source before relying on a specific command or claim.

Related resources

Related tool

More guides