What Is the SKILL.md File in a Claude Skill?

The SKILL.md file is the mandatory core document that defines a Claude Skill's metadata, activation conditions, and executable workflow steps within the ComposioHQ/awesome-claude-skills framework.

The SKILL.md file in a Claude Skill serves as the centralized instruction manual and metadata repository that powers the ComposioHQ/awesome-claude-skills ecosystem. Located in the root of every skill folder, this single markdown document tells Claude when to activate a workflow and exactly how to execute it. By separating lightweight YAML front-matter from detailed procedural content, the file enables efficient lazy loading across thousands of potential skills.

Structure of the SKILL.md File

YAML Front-Matter (Metadata)

The file begins with YAML front-matter containing the name and description fields. According to the repository's README.md (lines 89-93), this header constitutes approximately 100 tokens and represents the only portion Claude loads during initial skill discovery. This minimal footprint allows the agent to evaluate relevance without exhausting context windows.

Markdown Body (Instructions)

Following the front-matter, the markdown body contains the full instruction set: detailed workflows, usage conditions, guardrails, and examples. As documented in README.md (lines 91-97), Claude streams this content only after determining the skill matches the user's request, maintaining optimal token efficiency.

Skill Folder Architecture

A typical skill folder structure follows this pattern:

skill-name/
├── SKILL.md          # Required - core instructions and metadata

├── scripts/          # Optional - helper utilities

├── templates/        # Optional - document templates

└── resources/        # Optional - reference data files

This structure appears in README.md (lines 89-100). While SKILL.md is the only required file, developers can bundle supporting assets like Python parsing scripts or document templates that Claude retrieves on demand.

Creating a SKILL.md File

Minimal Skill Template

The template-skill/SKILL.md file demonstrates the bare minimum structure:

---
name: template-skill
description: Describe what this skill does in one sentence.
---

Replace this with detailed instructions for the skill.

Production-Ready Example

The invoice-organizer/SKILL.md provides a complete implementation with sections for "When to Use", detailed instructions, and real-world scenarios. A functional quick-note skill looks like:

---
name: quick-note
description: Takes a short user prompt and creates a markdown note file.
---

# Quick Note

## When to Use

- Jotting down ideas
- Capturing meeting bullet points

## Instructions

1. Receive the user's text.
2. Save it as `notes/YYYY-MM-DD-quick-note.md`.
3. Return the file path.

## Example

User: "Note the project deadline is Oct 15."
Claude: "Created `notes/2024-10-15-quick-note.md`."

Installing and Using Skills

To use an existing skill like invoice-organizer, place the folder in Claude Code's skill directory:

mkdir -p ~/.config/claude-code/skills/
cp -r invoice-organizer ~/.config/claude-code/skills/

When invoking via the Claude API, reference the skill by its folder name:

import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_KEY")
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    skills=["invoice-organizer"],  # Matches the SKILL.md folder name

    messages=[{"role": "user", "content": "Organize my receipts for tax season"}],
)
print(response.content)

Why SKILL.md Matters

• Lazy Loading: Only the front-matter metadata loads initially, enabling Claude to host thousands of skills without token budget overflow.
• Portability: Because the skill definition lives in a single markdown file, the same skill works across Claude.ai, Claude Code, the Anthropic API, and compatible third-party agents.
• Extensibility: Optional directories (scripts/, templates/, resources/) allow complex workflows while keeping the core instructions centralized in SKILL.md.

Reference Files

Key files in the ComposioHQ/awesome-claude-skills repository that define the SKILL.md specification:

• README.md (lines 89-100): Explains the overall skill structure, lazy-loading architecture, and metadata requirements.
• template-skill/SKILL.md: Minimal template showing required front-matter structure.
• invoice-organizer/SKILL.md: Full-featured example with description, usage conditions, and detailed instructions.
• README.md (lines 89-108): Official authoring template with recommended sections for new skills.

Summary

• The SKILL.md file is the mandatory core document that defines every Claude Skill's identity and behavior.
• It contains YAML front-matter (~100 tokens) for metadata and a Markdown body for detailed instructions.
• Claude uses lazy loading: only the front-matter loads initially; the full instructions stream when needed.
• Skills follow a standard folder structure with SKILL.md as the only required file, plus optional scripts/, templates/, and resources/ directories.
• The format ensures portability across Claude.ai, Claude Code, and the Anthropic API.

Frequently Asked Questions

What information goes in the SKILL.md YAML front-matter?

The front-matter requires two fields: name (the skill identifier) and description (a concise explanation of the skill's purpose). This metadata block should stay under approximately 100 tokens to ensure efficient loading during skill discovery.

Can a Claude Skill work without a SKILL.md file?

No. The SKILL.md file is mandatory. As documented in README.md (lines 89-100), this file serves as the single source of truth for the skill's metadata and instructions. Without it, Claude cannot identify or execute the skill.

How does Claude decide when to load the full SKILL.md content?

Claude evaluates only the YAML front-matter (name and description) against the user's request. If the description indicates relevance, Claude then streams the Markdown body containing the actual instructions, examples, and guardrails.

Where should I place SKILL.md when creating a new skill?

Place SKILL.md in the root of your skill folder (e.g., my-skill/SKILL.md). Optionally include scripts/, templates/, or resources/ subdirectories alongside it. Install the entire folder to ~/.config/claude-code/skills/ for Claude Code, or reference the skill name in API calls.

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