# How to Create a Custom Claude Skill Using YAML > Learn to create a custom Claude skill using YAML. Define your skill's name and description in YAML, then add markdown instructions for specialized tasks. Build powerful Claude extensions easily. - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: how-to-guide - Published: 2026-07-27 --- **Create a custom Claude skill by authoring a [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) must begin with a YAML block delimited by triple dashes. According to the [`template-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md) reference implementation, the front matter requires only two keys: ```yaml --- 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: ```bash ~/.config/claude-code/skills/my-custom-skill/ ``` For repository contributions, create a directory under the repository root: ```bash my-custom-skill/ ``` ### Write the YAML Front Matter Inside your directory, create [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) and add the YAML header: ```yaml --- 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: ```markdown # 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md). Below is a production-ready example combining YAML metadata with full instruction sets: ```markdown --- 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.