How to Create Custom Claude Skills with SKILL.md YAML Frontmatter Structure

Claude Skills are self-contained instruction packages defined by a SKILL.md file with YAML frontmatter that specifies the skill's name and description, allowing the agent to decide relevance in approximately 100 tokens before lazily loading the full instruction body.

Claude Skills provide a modular way to extend Anthropic's Claude agent with custom behaviors. According to the ComposioHQ/awesome-claude-skills repository, each skill resides in its own directory and relies on a structured SKILL.md file with YAML frontmatter to declare metadata. This architecture enables efficient context management while supporting hundreds of portable skills across Claude.ai, Claude Code, and the Claude API.

The SKILL.md File Structure

Every custom Claude Skill requires a SKILL.md file in its root directory. This file serves as both the configuration manifest and the instruction manual for the agent.

Required YAML Frontmatter

The file must begin with valid YAML frontmatter enclosed between triple dashes. As defined in template-skill/SKILL.md, the minimal required structure includes two fields:

---
name: your-skill-identifier
description: A concise sentence explaining when to use this skill.
---

• name: A unique slug identifier (e.g., tailored-resume-generator) used for discovery and invocation.
• description: A clear, imperative sentence telling Claude exactly when the skill should be activated (e.g., "Generate a résumé tailored to a specific job description").

This frontmatter is parsed first—consuming only about 100 tokens—enabling Claude to scan hundreds of skills without bloating the context window.

The Markdown Body Sections

After the frontmatter, the markdown body contains instructional content loaded lazily (up to 5,000 tokens) only when Claude determines the skill is relevant. Based on the skill-creator/SKILL.md guide, organize the body into these standard sections:

When to Use This Skill

List specific conditions or user intents that should trigger this skill. Use bullet points for scannability:

## When to Use This Skill

- The user provides a job posting and their CV.
- You need to highlight the most relevant experience for a specific role.

Instructions

Provide step-by-step directions written in imperative form. These instructions guide Claude's reasoning process, not the end user:

## Instructions

1. Parse the job description and extract key requirements.
2. Scan the user's CV for matching experiences.
3. Rewrite the résumé focusing on those matches.
4. Return a markdown-formatted résumé.

Examples

Include concrete input/output pairs demonstrating expected behavior:

## Examples

**User:** "Help me apply for a senior data engineer role at Acme Corp."
**Claude:** [Uses skill to generate tailored content]

Organizing Auxiliary Assets

Complex skills often require additional files beyond the SKILL.md documentation. The repository supports a standard folder structure for organizing these assets, as shown in the tailored-resume-generator/SKILL.md example:

my-skill/
├── SKILL.md          # Required: metadata and instructions

├── scripts/          # Optional: executable helper scripts

├── templates/        # Optional: document templates

└── resources/        # Optional: reference files and schemas

Claude loads these auxiliary files on demand, keeping the primary context window small while still supporting data-heavy operations. For example, you might store a JSON schema in resources/schema.json and reference it from your instructions, or place a Python helper script in scripts/clean_data.py for data processing tasks.

Skill Discovery and Loading

Claude discovers custom skills through multiple channels defined in the repository's README.md:

• Claude.ai UI: Skills uploaded through the web interface
• Claude Code: Local directory at ~/.config/claude-code/skills/<skill-name>/
• Skills API: Programmatic access for external integrations

When a user query arrives, Claude evaluates the YAML frontmatter of all available skills to determine relevance. Only if the skill is selected does Claude load the full markdown body and any referenced auxiliary files. This lazy loading mechanism ensures optimal token usage even with extensive skill libraries.

Separating Skills from MCP Tools

A critical architectural distinction exists between Skills and MCP (Model Context Protocol) servers. As documented in the repository, Skills describe behavior—they tell Claude what to do and how to reason—while MCP servers provide access to external APIs and tools.

Keep authentication logic and external API calls within MCP servers (such as those provided by Composio), not inside your SKILL.md files. This separation ensures your skills remain portable and secure across different deployment environments.

Testing Your Custom Skill

Before publishing, verify your skill functions correctly in Claude Code by placing the skill directory in ~/.config/claude-code/skills/ and invoking it through natural language prompts. For API testing, refer to the Skills API documentation in README.md (lines 71–84) to validate programmatic access patterns.

Summary

• YAML Frontmatter is mandatory: Every SKILL.md must start with name and description fields that fit within ~100 tokens.
• Lazy loading optimizes performance: The body (≤5,000 tokens) and auxiliary files load only after Claude selects the skill based on frontmatter matching.
• Standard sections drive behavior: Structure content with "When to Use," "Instructions," and "Examples" sections written in imperative form.
• Auxiliary assets stay separate: Store scripts, templates, and large reference files in sibling directories to SKILL.md, loading them on demand.
• Portability across platforms: The same skill works on Claude.ai, Claude Code, and the Claude API without modification.

Frequently Asked Questions

What fields are required in the SKILL.md YAML frontmatter?

The frontmatter must include exactly two fields: name (a unique slug identifier) and description (a concise sentence explaining when to invoke the skill). Both are required for Claude to index and discover the skill. Invalid YAML or missing fields will prevent the skill from loading.

How does Claude decide when to activate a custom skill?

Claude evaluates the description field from the YAML frontmatter of all available skills—approximately 100 tokens per skill—to determine relevance to the current user query. Only if the description matches the task context does Claude load the full instruction body and execute the skill's logic.

Can I include executable scripts in my Claude Skill?

Yes. Place helper scripts in a scripts/ directory adjacent to your SKILL.md file. Reference these scripts in your instructions using Claude Code's !run command syntax. Claude loads these files lazily when the skill is activated, keeping the initial context window small while enabling complex operations like data cleaning or file processing.

Where should I store custom skills for local testing with Claude Code?

For Claude Code local development, place your skill directory in ~/.config/claude-code/skills/<your-skill-name>/ with the SKILL.md file at the root of that directory. Claude Code automatically discovers skills in this location, allowing you to test invocation and behavior before publishing to the Skills API or sharing with the community.

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