# The SKILL.md File in a Claude Skill: Structure, Purpose, and Best Practices > Understand the SKILL.md file in Claude Skills. Learn its structure, purpose, and best practices to effectively manage your AI assistant's capabilities and instructions. - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: how-to-guide - Published: 2026-08-29 --- **The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file serves as the core descriptor and instruction manifest for every Claude Skill, combining YAML metadata for discovery with lazy-loaded procedural instructions that Claude executes only when the skill is relevant.** The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file is the mandatory entry point that defines how Claude discovers, catalogs, and executes custom capabilities within the **ComposioHQ/awesome-claude-skills** ecosystem. This single markdown document acts as both the metadata registry and the operational playbook, enabling the model to list available skills without loading their full content while keeping the context window lean. ## Metadata and Discovery via YAML Front-Matter Every [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) begins with a **YAML front-matter block** that declares the skill’s identity and categorization. According to the repository README at lines 101‑103, this metadata is what Claude reads at session start, allowing the model to **list available skills** without processing the entire file content. The front-matter typically includes: - `name`: The display name of the skill - `description`: A concise summary appearing in the skill catalogue - `tags`: Optional categorization labels for filtering ```markdown --- name: "Video Downloader" description: "Download and process videos from supported platforms." tags: ["media", "utility"] --- ``` ## Lazy-Loaded Instruction Architecture The bulk of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) contains the actual procedural instructions that Claude executes **only when the model decides the skill is relevant**. As documented in the README at lines 391‑395, this architecture ensures the instructions—usually containing fewer than 5,000 tokens—remain unloaded until invocation, preserving the model’s context window for active tasks. This lazy-loading mechanism means you can include detailed workflow steps, decision trees, and prompts without burdening every conversation with unused capabilities. Claude references the file path dynamically when the user’s intent matches the skill’s described purpose. ## Single Source of Truth for Workflows [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) functions as the **authoritative source** for all essential workflow steps and prompts. The template in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md) at lines 27‑42 establishes a strict separation between the instruction manifest and static resources, mandating that large files (scripts, datasets, reference documents) reside in companion directories. The standard directory structure requires: - `scripts/` – Executable utilities referenced by the skill - `references/` – Static data files or documentation - [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) – The lean instruction set linking to these resources This separation ensures the skill remains **quickly searchable** and minimizes token consumption during the discovery phase. ## Standardized Structure and Validation The repository enforces a **standardized layout** through templates and automated tooling. The validation logic in [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py) at lines 15‑18 checks for the presence of the required YAML front-matter and basic markdown structure, ensuring interoperability across the ecosystem. The canonical structure includes: 1. **Front-matter** (`---` delimited YAML) 2. **Overview** section explaining the skill’s purpose in ≤2 paragraphs 3. **Instructions** section with step-by-step actions 4. **References** section linking to external resources ## Practical Implementation: Creating a SKILL.md File ### Minimal Template Structure Create your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) following this pattern from the `skill-creator` template: ```markdown --- name: "My Sample Skill" description: "A short description that appears in the skill catalogue." tags: ["example", "demo"] --- # Overview A concise explanation of the skill's purpose and expected outcomes. # Instructions 1. Step-by-step actions Claude should take when invoking this skill. 2. Required API calls or prompt sequences. 3. Decision trees for handling edge cases. # References - `scripts/helper.py` – Utility for data processing - `references/data.json` – Configuration dataset ``` ### Validating Your Skill Before distribution, validate the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) structure using the provided script: ```bash python skill-creator/scripts/quick_validate.py path/to/your/skill ``` This script returns `True` if the file exists with proper front-matter, or prints a specific error indicating missing required sections. ### Packaging for Distribution Bundle your skill for publication using the packaging utility: ```bash python skill-creator/scripts/package_skill.py path/to/your/skill ``` This command creates a zip archive containing the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file alongside any referenced resources from `scripts/` or `references/`, producing a distribution-ready artifact. ## Summary - **[`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) is the mandatory manifest** that combines YAML metadata with markdown instructions, residing at the root of every skill directory in the ComposioHQ/awesome-claude-skills repository. - **Lazy loading preserves context** by keeping detailed instructions (typically <5k tokens) unloaded until Claude determines the skill is relevant to the user’s request. - **External resources belong in companion directories** (`scripts/`, `references/`) to maintain a lean, searchable instruction set rather than embedding large static assets. - **Standardized templates and validators** ([`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py)) ensure all skills follow a parseable, consistent structure compatible with automated tooling. - **Packaging scripts** ([`skill-creator/scripts/package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/package_skill.py)) bundle the manifest and its dependencies for distribution. ## Frequently Asked Questions ### What happens if a skill directory lacks a SKILL.md file? Claude cannot discover or execute the skill. The README at lines 101‑103 indicates that the model specifically scans for [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) at session start to build the available skills catalogue; without this file, the directory is invisible to the skill system. ### How large should the SKILL.md file be? The instruction body should remain under **5,000 tokens** according to the repository documentation at lines 391‑395. If your workflow requires more content, offload static data to the `references/` directory and executable logic to `scripts/`, then link to these from the markdown. ### Can I embed scripts directly inside SKILL.md? While you can include short code snippets inline, large scripts should reside in the `scripts/` directory. The [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md) template at lines 27‑42 explicitly recommends this separation to keep the instruction manifest lean and to allow the packaging script to properly bundle dependencies. ### How does Claude know when to load a skill’s instructions? Claude evaluates the YAML front-matter (name, description, tags) at session start to determine relevance. When the user’s intent matches the skill metadata, Claude then loads the procedural instructions from the body of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) on-demand, as implemented in the lazy-loading architecture described in the README at lines 391‑395.