How to Create a Custom Claude Skill Using YAML

Create a custom Claude skill by authoring a SKILL.md file that begins with YAML front matter defining the skill's name and description, followed by markdown instructions that Claude loads on-demand to execute specialized tasks.

Claude Skills are self-contained instruction packages in the ComposioHQ/awesome-claude-skills repository that tell an Anthropic Claude agent how to perform specific task classes. Each skill relies on YAML front matter for instant metadata indexing, allowing the runtime to evaluate relevance before loading the full instruction body.

How Claude Discovers and Loads Skills

The Claude runtime processes skills through a three-phase architecture designed for efficiency:

Skill Discovery – When a session starts, Claude scans every SKILL.md file and extracts only the YAML front matter (approximately 100 tokens per skill). This lightweight index allows the model to evaluate relevance without loading full instruction sets.

Lazy Loading – If the model determines a skill is needed, it fetches the remainder of the file, including the markdown body and any auxiliary assets.

Execution – The runtime follows the step-by-step instructions in the markdown body, optionally invoking helper scripts via the MCP gateway from a scripts/ subdirectory.

YAML Front Matter Structure

Every SKILL.md must begin with a YAML block delimited by triple dashes. According to the template-skill/SKILL.md reference implementation, the front matter requires only two keys:

---
name: my-custom-skill
description: A short, human-readable description of what the skill does and when to use it.
---

Required Fields

• name – The unique identifier for the skill (kebab-case recommended)
• description – A concise explanation of the skill's purpose and trigger conditions

Optional Fields

• tags – Categories for organization (e.g., web, analysis, writing)
• authors – Maintainer or creator identifiers
• version – Semantic version string

Claude reads the YAML block instantly to build the skill index, while the markdown body remains unloaded until requested.

Step-by-Step: Creating Your First Skill

Follow these steps to implement a complete skill in the ComposioHQ/awesome-claude-skills repository or your local configuration.

Create the Skill Directory

Create a new folder for your skill. For local testing with Claude Code, place it under:

~/.config/claude-code/skills/my-custom-skill/

For repository contributions, create a directory under the repository root:

my-custom-skill/

Write the YAML Front Matter

Inside your directory, create SKILL.md and add the YAML header:

---
name: article-summarizer
description: Summarizes web articles into concise bullet lists for quick consumption.
---

Add Instructions and Examples

Below the YAML block, write markdown sections that guide Claude through execution:

# Article Summarizer

Converts long-form web content into actionable briefs.

## When to Use This Skill

- You have a URL to a news article or research paper
- You need a high-level overview for a meeting or report
- The source text exceeds single-prompt context limits

## Instructions

1. **Fetch the article** – Use the built-in `webfetch` tool to retrieve content.
2. **Extract main points** – Identify headings and bolded statements.
3. **Rewrite** – Convert points into a flat bullet list (maximum 5 items).
4. **Validate** – If fewer than three bullets result, expand the weakest point.

## Examples

**Input:** `/article-summarizer https://example.com/long-article`

**Output:**
- Bullet 1 – Core claim or finding
- Bullet 2 – Supporting evidence or statistic
- Bullet 3 – Key implication for the reader

Optional: Add Helper Scripts

Create a scripts/ subdirectory for executable assets that the skill invokes through the MCP gateway. Store templates in templates/ and static resources in resources/.

Complete YAML Skill Template

The repository provides a minimal starter at template-skill/SKILL.md. Below is a production-ready example combining YAML metadata with full instruction sets:

---
name: my-custom-skill
description: Summarizes a web article, extracts the main arguments, and rewrites them as a concise bullet-list.
---

# My Custom Skill

This skill helps Claude process long-form web content and turn it into a clean, actionable summary.

## When to Use This Skill

- You have a URL to a news article, blog post, or research paper.
- You need a quick, high-level overview for a meeting or report.
- The original text is too large to fit in a single Claude prompt.

## Instructions

1. **Fetch the article** – Use the built-in `webfetch` tool to retrieve the page content.
2. **Extract the main points** – Identify headings, sub-headings, and any bolded statements.
3. **Rewrite** – Convert the extracted points into a concise, flat bullet list (max 5 items).
4. **Validate** – If fewer than three bullets are produced, ask the model to "expand" one of the points.

## Examples

**Input**  
`/my-custom-skill https://example.com/long-article`

**Output**  

- Bullet 1 – Core claim or finding.
- Bullet 2 – Supporting evidence or statistic.
- Bullet 3 – Key implication for the reader.

Save this as SKILL.md in your skill folder. Claude will index it by the YAML name and description, then load the full instructions only when the user query matches the "When to Use This Skill" criteria.

File Organization Best Practices

Structure your skill directory to support the lazy-loading architecture:

• SKILL.md – Required. Contains YAML front matter and instruction body.
• scripts/ – Optional. Executable helpers invoked via MCP.
• templates/ – Optional. Reusable prompt fragments or output formats.
• resources/ – Optional. Static data files or configuration assets.

Keep the YAML front matter under 100 tokens to ensure rapid discovery, and place detailed logic in the markdown body or external scripts.

Summary

• YAML Front Matter: Every skill requires a SKILL.md file starting with YAML containing name and description keys.
• Lazy Loading: Claude reads only the YAML during discovery (~100 tokens), fetching the full markdown body only when the skill is invoked.
• Directory Structure: Store skills in ~/.config/claude-code/skills/ for local use or contribute to ComposioHQ/awesome-claude-skills repository subdirectories.
• Optional Assets: Add scripts/, templates/, or resources/ subdirectories for helper code and static files.
• Metadata Support: Optional keys like tags, authors, and version are accepted but not required by the runtime.

Frequently Asked Questions

What file naming convention must I follow for Claude to recognize my skill?

Claude specifically looks for files named exactly SKILL.md (case-sensitive). The file must reside in its own directory, either within the repository structure or under ~/.config/claude-code/skills/ for local Claude Code installations. Other filenames or extensions will not be indexed during the discovery phase.

Can I include arbitrary keys in the YAML front matter?

Yes. While Claude requires the name and description keys to function, the YAML parser accepts additional keys such as tags, authors, version, or custom metadata. These extra fields do not affect the runtime behavior but can help with repository organization and documentation.

How does Claude decide which skill to load?

During the initial discovery phase, Claude extracts only the YAML front matter from all available SKILL.md files. It evaluates the description field against the user's query to determine relevance. If the description indicates the skill can handle the request, Claude performs lazy loading to fetch the full markdown body and execute the instructions contained within.

Where should I store helper scripts that my skill needs to execute?

Place executable helper scripts in a scripts/ subdirectory within your skill folder. The skill can invoke these through the MCP gateway during the execution phase. Similarly, use templates/ for reusable text fragments and resources/ for static data files that support the skill's operation.

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