# Claude Skill Structure: Anatomy of a Self-Contained AI Package > Discover the Claude Skill structure. Learn how SKILL.md files, scripts, and assets create self-contained AI packages to define Claude activations and capabilities. - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: deep-dive - Published: 2026-07-28 --- **A Claude Skill is a self-contained package comprising a mandatory SKILL.md file with YAML front-matter and optional directories for scripts, references, and assets that define when Claude activates and what capabilities it provides.** The [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) repository defines the canonical Claude Skill structure that all custom integrations must follow. This specification ensures that skills load efficiently, validate correctly, and package into distributable artifacts for the Claude ecosystem. ## Required Components: The SKILL.md File Every skill must include a [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file at the root of its directory. This single file acts as the entry point and contains two distinct sections: metadata that Claude always loads, and instructions that load on-demand. ### Front-Matter Metadata (Always Loaded) The file must begin with a YAML front-matter block delimited by triple dashes. At minimum, you must define: - **`name`** – A hyphen-case identifier (e.g., `pdf-processor`) that Claude matches against user intent - **`description`** – A concise, third-person sentence explaining exactly *when* the skill should be invoked According to [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py), the validation tooling enforces strict hyphen-case naming conventions and rejects descriptions containing angle brackets to prevent parsing errors. ### Instructional Body (Loaded On-Demand) Below the front-matter, the markdown body contains the actual instructions Claude reads upon activation. As documented in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md) (lines 27-40), effective skills typically organize this content into: - **Overview** – The purpose and high-level capabilities of the skill - **Step-by-step workflow** – Procedural instructions Claude can execute - **Resource references** – Links to files in the optional `scripts/`, `references/`, or `assets/` directories ## Optional Resource Directories While [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) is the only required file, the Claude Skill structure supports three optional folders that extend functionality without bloating the initial context window. Claude loads these resources only when explicitly referenced. ### scripts/ – Executable Code Contains deterministic code that Claude executes without loading the entire script into its context. Place Python, Bash, or other executable files here when the skill requires external processing. Example: [`scripts/rotate_pdf.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/rotate_pdf.py) for a PDF-editor skill that manipulates documents. ### references/ – Documentation and Schemas Holds large documentation, API specifications, or JSON schemas that Claude pulls in for context-heavy tasks. This keeps the initial skill load lightweight while providing deep reference material when needed. Example: [`references/api_reference.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/references/api_reference.md) for an API-wrapper skill requiring detailed endpoint documentation. ### assets/ – Static Files Stores templates, images, fonts, or configuration files that Claude copies or embeds into final outputs. These are typically non-executable resources used for presentation or branding. Example: `assets/logo.png` for a brand-guidelines skill that generates compliant marketing materials. ## Creating, Validating, and Packaging Skills The repository provides three Python scripts in `skill-creator/scripts/` to manage the complete skill lifecycle from scaffolding to distribution. ### Generating a New Skill Use [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py) to scaffold a new skill directory with the required layout and starter [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md): ```bash python skill-creator/scripts/init_skill.py my-new-skill --path skills/public ``` This creates the full structure: ``` skills/public/my-new-skill/ ├── SKILL.md ├── scripts/ │ └── example.py ├── references/ │ └── api_reference.md └── assets/ └── example_asset.txt ``` ### Validating Before Distribution Run [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) to verify that your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) front-matter meets the naming and formatting requirements: ```bash python skill-creator/scripts/quick_validate.py skills/public/my-new-skill # → "Skill is valid!" ``` ### Packaging for Release Once validated, use [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) to create a distributable zip file: ```bash python skill-creator/scripts/package_skill.py skills/public/my-new-skill ./dist # → creates dist/my-new-skill.zip ``` ## Real-World Examples ### Minimal Skill Structure A basic greeting skill requires only the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with no additional directories: ~~~~yaml --- name: greeting-skill description: This skill should be used when Claude needs to generate a friendly greeting for a user. --- # Greeting Skill When the user asks for a greeting, respond with: ``` Hello, {user_name}! 👋 How can I help you today? ``` ~~~~ This minimal structure contains only metadata and instructional markdown. ### Full-Featured Skill Structure Complex skills like **Connect Apps** ([`connect-apps/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/connect-apps/SKILL.md)) utilize all optional directories, shipping with `scripts/`, `references/`, and `assets/` to provide comprehensive API integration capabilities while maintaining efficient context loading. ## Summary - A **Claude Skill** is a self-contained directory centered around a mandatory [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with YAML front-matter - The **front-matter** requires `name` (hyphen-case) and `description` (third-person trigger condition) fields - **Optional directories** (`scripts/`, `references/`, `assets/`) extend capabilities without impacting initial context size - **Validation** via [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) enforces naming conventions and forbids angle brackets in descriptions - **Packaging** via [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) produces distributable zip files only after validation passes ## Frequently Asked Questions ### What files are required for a Claude Skill to function? Only [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) is strictly required at the skill root. This file must contain valid YAML front-matter with at least the `name` and `description` fields, followed by instructional markdown. The `scripts/`, `references/`, and `assets/` directories are optional and loaded only when referenced in the skill body. ### How does Claude know when to activate a specific skill? Claude evaluates the `description` field in the YAML front-matter as a trigger condition. The description should be written in third person and explicitly state the scenario in which the skill should be used (e.g., "This skill should be used when the user needs to analyze CSV data"). The [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) script checks that descriptions contain no angle brackets to ensure clean parsing. ### Can I include executable Python code in a Claude Skill? Yes. Place executable scripts in the `scripts/` directory. According to the anatomy specification in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md), these files should contain deterministic code that executes without requiring Claude to load the entire script into its context window. This architecture optimizes performance while enabling complex operations like PDF manipulation or API calls. ### How do I validate my skill before sharing it? Run `python skill-creator/scripts/quick_validate.py ` to verify that your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) meets the required Claude Skill structure. The validator checks for proper YAML front-matter, hyphen-case naming conventions, and compliant description formatting. Once validation passes, use [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) to generate a distributable zip file.