Production-Ready Claude Skill Structure: Complete Directory Layout Guide

A production-ready Claude Skill is a self-contained folder containing a required 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 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 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, 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 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 Using Skills section confirms this portability requires no platform-specific configuration.

Complete Production Example

The repository includes a template-skill/SKILL.md demonstrating the minimal viable structure. Below is an expanded production example named summarize-article showing the required SKILL.md content and folder layout.

---
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 <title> 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 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.
• 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 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 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 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 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.

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