Claude Skill Structure: Anatomy of a Self-Contained AI Package

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 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 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, 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 (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 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 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 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 to scaffold a new skill directory with the required layout and starter SKILL.md:

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 to verify that your SKILL.md front-matter meets the naming and formatting requirements:

python skill-creator/scripts/quick_validate.py skills/public/my-new-skill

# → "Skill is valid!"

Packaging for Release

Once validated, use package_skill.py to create a distributable zip file:

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 file with no additional directories:

---
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) 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 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 enforces naming conventions and forbids angle brackets in descriptions
• Packaging via 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 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 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, 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 <path-to-skill> to verify that your 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 to generate a distributable zip file.

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