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

> Discover the essential SKILL.md file for Claude Skills. Learn how it defines metadata, activation, and workflow steps within the ComposioHQ/awesome-claude-skills framework.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: deep-dive
- Published: 2026-07-28

---

**The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) (lines 89-100). While [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md) file demonstrates the bare minimum structure:

```markdown
---
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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:

```markdown
---
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:

```bash
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:

```python
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md).

## Reference Files

Key files in the **ComposioHQ/awesome-claude-skills** repository that define the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) specification:

- **[`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md)** (lines 89-100): Explains the overall skill structure, lazy-loading architecture, and metadata requirements.
- **[`template-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md)**: Minimal template showing required front-matter structure.
- **[`invoice-organizer/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/invoice-organizer/SKILL.md)**: Full-featured example with description, usage conditions, and detailed instructions.
- **[`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md)** (lines 89-108): Official authoring template with recommended sections for new skills.

## Summary

- The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file is mandatory. As documented in [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) in the root of your skill folder (e.g., [`my-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.