Best Practices for Writing SKILL.md Files for Claude: The Complete 10-Step Guide

A well-crafted SKILL.md file uses valid YAML front-matter for discovery, structured sections for deterministic activation, and stays under 5,000 tokens to ensure reliable loading across Claude.ai, Claude Code, and the Claude API.

Claude Skills are self-contained instruction packages that tell an LLM how to solve a specific class of tasks. The SKILL.md file serves as the single source of truth driving behavior across the entire Claude ecosystem. According to the ComposioHQ/awesome-claude-skills repository, following a standardized 10-step workflow ensures your skills are discoverable, safe, and performant.

The 10-Step SKILL.md Checklist

1. Define Metadata with Valid YAML Front-Matter

Every skill must begin with a YAML front-matter block containing name and description keys. This metadata block is how Claude discovers the skill and decides whether to load its body—approximately 100 tokens are streamed at session start.

In template-skill/SKILL.md, the canonical structure looks like this:

---
name: my-skill
description: One-sentence summary of what the skill does and when to use it.
---

Critical: Missing or malformed front-matter keys render the skill invisible to Claude. Use head SKILL.md to verify formatting before committing.

2. Write a Clear Title

Use a level-1 heading (#) that repeats the skill name exactly as defined in the front-matter. This improves readability when the full file loads and helps humans quickly locate the relevant section.

3. Provide a Purpose Paragraph

Immediately following the H1, explain what problem the skill solves and when to invoke it. This context helps Claude make activation decisions and lets users understand scope without reading every line.

4. List "When to Use" Bullet Points

Enumerate at least three concrete use-cases in a bullet list. Specificity guarantees deterministic activation and prevents over-generalization that wastes the context window.

For example:

## When to Use This Skill

- Summarize long documents
- Extract key insights from meeting transcripts
- Generate a concise briefing for a stakeholder

5. Enumerate Capabilities

Use a numbered list to detail core actions the skill performs. This helps Claude break complex tasks into reusable steps and simplifies debugging.

Example structure from skill-creator/SKILL.md:

## What This Skill Does

1. **Parse** the input text using Claude's built-in tokenizer.
2. **Identify** headings and bullet points.
3. **Produce** a short TL;DR summary.

6. Give "How to Use" Examples

Provide two usage tiers:

• Basic Usage: A minimal prompt that triggers the skill
• Advanced Usage: A richer prompt with optional parameters

Real-world examples teach Claude the expected input format and serve as regression tests.

## How to Use

### Basic Usage

Summarize the following article:

### Advanced Usage

Summarize the article and output a bullet list of key takeaways, limiting each bullet to 12 words.

7. Include a Full Example

Show a complete User prompt and Expected Output block. This end-to-end illustration can be copied directly into test suites.

## Example

**User**: Summarize the quarterly earnings call transcript.
**Output**:
- Revenue grew 12% YoY...
- Net profit increased...
- Guidance for next quarter...

8. Add Attribution (Optional)

Cite the original workflow or author if the skill adapts an existing process. This encourages community credit and respects intellectual property.

**Inspired by:** Jane Doe's internal briefing workflow

9. Offer Tips and Common Pitfalls

Include a short bullet list of best-practice hints and edge-case handling. This reduces unsafe or destructive actions, satisfying the safety requirements documented in CONTRIBUTING.md.

10. Keep the File Under ~5,000 Tokens

Prevent context window exhaustion by splitting very large bodies into auxiliary scripts/ or references/ directories. As implemented in ComposioHQ/awesome-claude-skills, progressive loading only streams metadata initially, but the full body must still fit within Claude's context when invoked.

Architectural Guidelines and Safety Standards

Modular Folder Layout

Each skill lives in its own directory (skill-name/) containing a mandatory SKILL.md and optional sub-folders: scripts/, templates/, and resources/. This canonical layout is defined in the repository's README.md under the Skill Structure section.

Progressive Loading Model

Only the metadata and short description are streamed at session start; the full body loads on demand. This architecture requires concise front-matter and efficient file organization to minimize latency.

Safety Guards for Destructive Operations

Embed explicit confirmation steps for any destructive operation (e.g., file deletion, network calls). Reference the safety checklist in CONTRIBUTING.md to ensure compliance with community standards.

## Example

**User**: Delete `temp/report.pdf`.
**Claude**: The file `temp/report.pdf` exists. Please type **YES** to confirm deletion.
**User**: YES
**Claude**: File deleted successfully.

Complete SKILL.md Templates

Minimal Template

This template from template-skill/SKILL.md provides the foundation:

---
name: my-skill
description: One-sentence summary of what the skill does and when to use it.
---

# My Skill

A detailed description of the skill's purpose and the problem it solves.

## When to Use This Skill

- Summarize long documents
- Extract key insights from meeting transcripts
- Generate a concise briefing for a stakeholder

## What This Skill Does

1. **Parse** the input text using Claude's built-in tokenizer.
2. **Identify** headings and bullet points.
3. **Produce** a short TL;DR summary.

## How to Use

### Basic Usage

Summarize the following article:

### Advanced Usage

Summarize the article and output a bullet list of key takeaways, limiting each bullet to 12 words.

## Example

**User**: Summarize the quarterly earnings call transcript.
**Output**:
- Revenue grew 12% YoY...
- Net profit increased...
- Guidance for next quarter...

**Inspired by:** Jane Doe's internal briefing workflow

Advanced Example with Safety Confirmation

This example demonstrates safe file deletion patterns:

---
name: safe-file-delete
description: Deletes a file after explicit user confirmation.
---

# Safe File Delete

Removes a file from the local filesystem only after the user explicitly confirms the action.

## When to Use This Skill

- Cleaning up temporary build artifacts
- Removing stale log files
- Purging large data dumps after processing

## What This Skill Does

1. **Check** whether the target file exists.
2. **Prompt** the user for a "YES" confirmation.
3. **Delete** the file if and only if confirmation is received.

## How to Use

/safe-file-delete:delete path/to/file.txt

## Example

**User**: Delete `temp/report.pdf`.
**Claude**: The file `temp/report.pdf` exists. Please type **YES** to confirm deletion.
**User**: YES
**Claude**: File deleted successfully.

Summary

• YAML front-matter is mandatory: Include valid name and description keys in every SKILL.md to ensure discoverability.
• Structure drives activation: Use specific "When to Use" bullets and numbered capability lists to help Claude determine when to invoke the skill.
• Token limits matter: Keep files under 5,000 tokens and offload large content to scripts/ or resources/ directories.
• Safety requires explicit gates: Always include confirmation steps for destructive operations as specified in CONTRIBUTING.md.
• Examples serve as tests: Provide basic, advanced, and full end-to-end examples to define expected input/output formats.

Frequently Asked Questions

What happens if the YAML front-matter is malformed?

Claude will not recognize the skill. The skill becomes invisible to the system, preventing activation across Claude.ai, Claude Code, and the API. Always validate front-matter with head SKILL.md before submitting.

How specific should "When to Use" bullet points be?

Provide at least three concrete scenarios. Abstract descriptions cause over-generalization and unnecessary invocations, while specific use-cases ensure deterministic activation and conserve context window space.

Can I include external scripts or resources in my skill?

Yes. Store auxiliary files in scripts/, templates/, or resources/ subdirectories within your skill folder. This keeps the main SKILL.md under the 5,000-token limit while preserving functionality, following the modular layout defined in the repository's README.md.

Where should I reference the safety requirements for destructive operations?

Cite the safety checklist in CONTRIBUTING.md and embed explicit confirmation steps directly in your skill's capability list. For file deletion, network calls, or data modification, always require user confirmation before execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}