5 SKILL.md Body Writing Rules Hidden in Anthropic's Docs

A Skill only needs two lines of YAML frontmatter to exist. But how you write the body determines whether the output is excellent or mediocre.

After cross-referencing Anthropic’s official documentation and engineering blog, I’ve distilled the operating mechanics and body writing principles into five rules. This deep dive started because my own Skills would intermittently fail to load, and I spent a holiday weekend tracing the root cause.

If You Don’t Understand Skill Execution Order, Your Body Design Will Fail

Skills don’t get injected into the conversation like a prompt. At startup, only the name and description are loaded into the system prompt.

When a user request matches the description, Claude uses the Bash tool to read the full SKILL.md. Only then does it load reference files and scripts as needed. Anthropic’s engineering blog calls this structure “progressive disclosure.”

• Stage 1: Only metadata (name + description) is always loaded. About 100 tokens per Skill.
• Stage 2: The SKILL.md body enters the context window only on match.
• Stage 3: Files in the scripts and references folders load at actual point of use.
• When scripts run, the code itself doesn’t enter the context. Only the output is consumed.

Without understanding this structure, you’ll pack the body with unnecessary information and miss what actually matters.

Writing “When to Use” in the Body Wastes Tokens

Many people add a “When to Use This Skill” section to the body. After building my own Skills, I found this completely useless. The body is only read after the Skill has already been triggered.

“When to use” belongs exclusively in the description. Anthropic’s official skill-creator repo makes this explicit.

• The description is the sole trigger mechanism (Claude doesn’t reference “when to use” content in the body)
• Descriptions have a 1,024 character limit. Writing in third person improves discovery accuracy.
• The body should contain task rules, procedures, and expected output formats.
• Delete sentences like “Use this Skill when…” from the body.

Keep the Body Under 500 Lines and Split the Rest

The first line of Anthropic’s guide states that the context window is a shared resource. Once a Skill loads, it shares tokens with conversation history and the system prompt.

The official recommendation is to keep the body under 500 lines and extract detailed content into separate files. The SKILL.md acts as a table of contents, and reference files serve as individual chapters.

• Body under 500 lines recommended (stated in Anthropic best practices)
• Link reference files only one level deep from SKILL.md
• With two or more levels of nested references, Claude may only read the first 100 lines via head -100
• Add a table of contents at the top of any reference file over 100 lines

Write as if Claude Is Already Smart

Explaining what a PDF is in the body wastes tokens. There’s a principle Anthropic’s guide emphasizes repeatedly:

“Don’t write what Claude already knows.”

A concise 50-token code example outperforms a 150-token conceptual explanation. In my tests on the same PDF extraction task, the lean body produced noticeably better accuracy than the verbose one.

• Ask yourself for every sentence: “Is this explanation worth the tokens?”
• Replace conceptual explanations with code examples + expected output formats
• Categorize task freedom into three levels (high/medium/low) to calibrate instruction intensity
• Set low freedom for tasks like DB migrations. Set high freedom for code reviews.

Embed Verification Loops in the Body for Better Quality

Execute → verify → fix → re-verify. This is the most practical body pattern Anthropic recommends. Embedding checklists in the body noticeably reduces the chances of Claude skipping steps.

The official guide also notes that strong language like “MUST filter” achieves higher compliance than “always filter.”

• Spell out steps in checklist format for complex tasks
• Include script verification → error fix → re-verification loops in the body
• Use “MUST” instead of “always”: Claude’s compliance rate improves
• Write specific error messages so Claude can self-correct

The Bottom Line

The description decides when a Skill fires. The body decides how it performs. The moment you mix these two roles, the Skill neither triggers reliably nor produces quality output.

A great Skill is like great onboarding documentation. The most powerful documents start from the assumption that the reader is already smart.