# Production-Ready Claude Skill Structure: Complete Directory Layout Guide > Master production-ready Claude Skill structure. Learn the complete directory layout including SKILL.md, scripts, templates, and resources for lazy loading and portability. - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: how-to-guide - Published: 2026-08-30 --- **A production-ready Claude Skill is a self-contained folder containing a required [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with YAML front-matter and Markdown instructions, plus optional subdirectories for scripts, templates, and resources that enable lazy loading and cross-platform portability.** The ComposioHQ/awesome-claude-skills repository establishes the canonical blueprint for building discoverable, production-grade capabilities for Claude. Mastering this structure ensures your skills load efficiently and behave consistently whether deployed on Claude.ai, Claude Code, or the Claude API. ## Required Core Components Every production-ready Claude Skill must include at least one file at its root directory. ### The SKILL.md File The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file serves as the mandatory entry point and contract between the skill and Claude. Located at the root of the skill folder, this file must contain **YAML front-matter** defining metadata followed by the full instruction set in Markdown. According to the repository's [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) **Skill Structure** section, the front-matter requires two fields: - `name`: The unique identifier for the skill - `description`: A concise summary (approximately 100 tokens) loaded at session initialization The Markdown body (typically under 5,000 tokens) contains the complete workflow instructions, guardrails, and error handling logic. This content is fetched lazily only when Claude determines the skill is relevant to the current context. ## Optional Asset Directories Beyond the required [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md), a skill may include three optional subdirectories to organize auxiliary assets: - **`scripts/`** – Helper executables (Bash, Python, Node.js) that the skill invokes via the MCP server or local runtime. Store automation logic here rather than embedding it in the Markdown instructions. - **`templates/`** – Document or code templates that the skill copies, fills, or renders during workflow execution. Useful for standardizing outputs like email formats or configuration files. - **`resources/`** – Static assets including reference PDFs, JSON datasets, images, or validation schemas required for context-heavy operations. ## Architectural Design Principles The production-ready Claude Skill structure in `ComposioHQ/awesome-claude-skills` implements three core architectural patterns that optimize performance and maintainability. ### Lazy Loading Strategy The system implements aggressive lazy loading to minimize context window usage. At session start, only the skill's name and description (~100 tokens) are loaded into memory. The full [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) body remains on disk until Claude's routing logic determines the skill is needed for the current task, at which point the complete instruction set (<5k tokens) is fetched. ### Separation of Concerns The architecture distinguishes three distinct layers: - **MCP Layer** – Handles authentication and transport protocols to external services (APIs, databases, filesystems). - **Tools** – Low-level atomic functions such as `send_email` or `create_issue` that perform single actions. - **Skills** – High-level orchestration layers that coordinate tools, encode business workflows, and implement guardrails or edge-case handling. ### Cross-Platform Portability Because a skill is fundamentally a folder containing declarative Markdown and static files, the identical skill works unchanged across Claude.ai, Claude Code, and the Claude API. The repository's [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) **Using Skills** section confirms this portability requires no platform-specific configuration. ## Complete Production Example The repository includes a [`template-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md) demonstrating the minimal viable structure. Below is an expanded production example named `summarize-article` showing the required [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) content and folder layout. ```markdown --- name: summarize-article description: Summarizes a web article into a concise bullet‑point summary, preserving key facts. --- # Summarize Article **When to use** - You have a URL of a news article, blog post, or documentation page. - You need a short, factual summary for a briefing or newsletter. **Prerequisites** - The `webfetch` tool must be enabled in the MCP server. **Instructions** 1. Use the `webfetch` tool to retrieve the page content from the provided URL. 2. Extract the main headline, author, and publication date. 3. Identify the top 5 most important points in the article. 4. Return a markdown bullet list prefixed with the headline and a citation link. **Example** > **Input:** `https://example.com/ai‑trends‑2024` > **Output:** ```markdown **AI Trends 2024 – Example.com** - AI‑generated video editing tools will cut post‑production time by 30 %. - … (four more bullet points) [Read full article](https://example.com/ai‑trends‑2024) ``` **Error handling** - If the URL fails to load, respond with "❌ Unable to fetch the article – please verify the URL." - If the page contains no clear headline, fall back to the `` tag. ``` The corresponding folder structure follows this layout: ```text summarize-article/ ├── SKILL.md # Required metadata and instructions └── scripts/ # Optional helper utilities (e.g., HTML stripping) ``` ## Summary - **A production-ready Claude Skill requires a single [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file** with YAML front-matter (`name`, `description`) and Markdown instructions, located at the repository root as defined in the **Skill Structure** section of [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md). - **Optional directories `scripts/`, `templates/`, and `resources/`** organize auxiliary assets without bloating the core instruction set. - **Lazy loading** ensures only ~100 tokens of metadata load initially, with the full <5k token body fetched on-demand. - **The three-layer architecture** separates MCP transport, low-level Tools, and high-level Skill orchestration for maintainable workflows. - **Cross-platform compatibility** allows the same skill folder to function identically across Claude.ai, Claude Code, and the Claude API. ## Frequently Asked Questions ### What is the minimum required file for a Claude Skill? The absolute minimum is a single [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file located at the root of the skill folder. This file must contain valid YAML front-matter with `name` and `description` fields, followed by Markdown instructions. The [`template-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/template-skill/SKILL.md) in the ComposioHQ/awesome-claude-skills repository provides the canonical template for this required structure. ### How does lazy loading work in Claude Skills? At session initialization, Claude loads only the `name` and `description` from each skill's YAML front-matter—approximately 100 tokens total. The full Markdown body (typically under 5,000 tokens) remains unloaded until the system determines the skill is relevant to the current user query, at which point it fetches the complete instruction set. This design prevents context window saturation when multiple skills are available. ### Can I include executable code in a Claude Skill? Yes, but it belongs in the optional `scripts/` subdirectory rather than embedded in the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file. The skill can invoke these scripts via the MCP server or local runtime. Supported languages include Bash, Python, and Node.js. Keep the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) focused on orchestration logic while storing implementation details in `scripts/` to maintain clean separation of concerns. ### Where should I store static assets like PDFs or JSON files? Place static assets in the `resources/` subdirectory. This directory houses reference materials, validation schemas, images, or datasets that the skill needs for context or validation. Like `scripts/` and `templates/`, the `resources/` folder is optional and only loaded when the skill actively requests specific files, preserving the lazy loading optimization.