How to Create a New Claude AI Skill: The Complete Developer Guide

Creating a new Claude AI skill involves scaffolding a modular folder structure with init_skill.py, authoring a concise SKILL.md file with YAML front-matter, adding deterministic scripts to the scripts/ directory, and validating the package with package_skill.py to produce a distributable .zip archive.

The ComposioHQ/awesome-claude-skills repository provides a standardized framework for extending Claude's capabilities through modular, domain-specific skills. Following the official Anthropic Skills specification, this approach uses a three-level progressive disclosure architecture to keep context windows small while supporting unlimited auxiliary resources. Understanding how to create a new Claude AI skill allows developers to package reusable workflows, deterministic code, and reference materials for distribution across Claude AI, Claude Code, and the Skills API.

Understanding the Progressive Disclosure Architecture

Claude AI Skills utilize a hierarchical loading strategy defined in skill-creator/SKILL.md to optimize token usage. When you create a new Claude AI skill, you are building a modular folder that extends Claude’s capabilities through three distinct disclosure levels:

1. Metadata Layer – The name and description fields from the YAML front-matter (approximately 100 tokens) are always loaded at session start, enabling Claude to determine skill relevance.
2. Instruction Layer – The full SKILL.md body (typically under 5,000 tokens) loads only when the skill is triggered, providing detailed usage instructions.
3. Resource Layer – Files in scripts/, references/, and assets/ remain unloaded until explicitly requested, allowing you to bundle large reference documents or deterministic executable code without inflating the context window.

This architecture ensures that auxiliary resources can be executed or referenced on demand while keeping the active context lightweight.

Step-by-Step Guide to Create a New Claude AI Skill

1. Define the Use Case

Identify the concrete user queries your skill will solve before writing any code. This drives the purpose statement, when-to-use guidelines, and the specific examples you will provide in the metadata. According to the skill-creator/SKILL.md guide, starting with concrete examples ensures your skill triggers at the appropriate times.

2. Plan Reusable Contents

For each use case, determine which resources will be reused across interactions. Decide whether you need deterministic Python scripts in scripts/, large documentation files in references/, or binary templates in assets/. The repository structure distinguishes between executable code (which runs without LLM context) and reference material (which the LLM may read).

3. Initialize the Skill Structure

Run the initialization script to generate the required folder hierarchy and starter files:

python skill-creator/scripts/init_skill.py <skill-name> --path <output-dir>

This command, defined in skill-creator/scripts/init_skill.py, creates a new directory containing a template SKILL.md along with example subdirectories: scripts/, references/, and assets/.

4. Author the SKILL.md File

Edit the generated SKILL.md to include the required YAML front-matter and body content:

---
name: Skill Name
description: A concise description of what this skill does and when to use it.
---

# Skill Name

## Overview

Brief explanation of the skill's purpose.

## When to Use

Specific trigger conditions for Claude to invoke this skill.

## Examples

Concrete usage scenarios showing input and expected output.

The file must follow the imperative writing style specified in the creator guide. Remove any placeholder "TODO" comments and ensure the description clearly signals to Claude when this skill is relevant.

5. Add Bundled Resources

Populate the resource directories created by the initializer:

• scripts/ – Store deterministic automation code here. These scripts execute outside the LLM context window, making them ideal for data processing or API calls.
• references/ – Place large documentation, API specifications, or knowledge bases that Claude should read only when necessary.
• assets/ – Include templates, icons, or binary files required for the workflow.

Delete any unused example files (such as example.py or example_asset.txt) before packaging.

6. Validate and Package

Execute the packaging script to validate structure and create the distributable archive:

python skill-creator/scripts/package_skill.py <skill-folder> [output-dir]

This script invokes quick_validate.validate_skill from skill-creator/scripts/quick_validate.py to verify your SKILL.md contains required front-matter fields and that the folder layout adheres to specification. Upon successful validation, the script generates <skill-name>.zip containing your skill.

7. Test and Iterate

Install the generated .zip into Claude AI, Claude Code, or via the Skills API to test real-world performance. Refine the SKILL.md instructions based on actual interactions, add missing resources to scripts/ or references/, and re-run package_skill.py to regenerate the archive.

The Core Scripts: init_skill.py and package_skill.py

The repository provides two primary Python utilities in skill-creator/scripts/ to automate skill creation:

init_skill.py generates the skeleton directory structure and starter SKILL.md with proper YAML front-matter formatting. It ensures consistent naming conventions and creates placeholder files in each resource directory to guide authors.

package_skill.py performs pre-distribution validation by checking for required metadata fields, verifying directory layout compliance, and bundling the skill into a standardized .zip format. It internally calls validation logic from quick_validate.py to enforce schema requirements before archiving.

Minimal Working Example

To create a new Claude AI skill named "pdf-rotator" from scratch:

# Scaffold the skill directory

python skill-creator/scripts/init_skill.py pdf-rotator --path ./skills/public

# Edit the SKILL.md file to add description and usage examples

# Located at: ./skills/public/pdf-rotator/SKILL.md

# Replace the example script with actual implementation

mv ./skills/public/pdf-rotator/scripts/example.py \
   ./skills/public/pdf-rotator/scripts/rotate_pdf.py

# Validate and package for distribution

python skill-creator/scripts/package_skill.py \
    ./skills/public/pdf-rotator \
    ./dist

The resulting pdf-rotator.zip file in ./dist/ is ready for upload to the Claude AI skill marketplace, placement in ~/.config/claude-code/skills/, or integration via the API.

Summary

• Progressive Disclosure allows skills to remain lightweight by loading only metadata initially, instructions when triggered, and auxiliary resources on demand.
• init_skill.py automates the creation of the standardized folder structure and starter files required by the Anthropic specification.
• package_skill.py validates schema compliance and bundles the skill into a portable .zip archive for distribution.
• Bundled Resources follow strict directory conventions (scripts/, references/, assets/) to ensure deterministic execution and efficient context management.
• YAML Front-Matter in SKILL.md serves as the critical filtering mechanism that helps Claude decide when to invoke your skill.

Frequently Asked Questions

What is the required file structure for a Claude AI skill?

Every skill must contain a SKILL.md file at the root, optionally accompanied by three specific directories: scripts/ for executable code, references/ for large documentation files, and assets/ for binary templates or media. The init_skill.py script generates this structure automatically, ensuring compliance with the Anthropic specification.

How does the progressive disclosure model optimize context window usage?

The model loads only the YAML front-matter (name and description) at session start, keeping the active token count near 100. The full instructions load only upon skill invocation, typically staying under 5,000 tokens. Large reference files and scripts remain unloaded until explicitly requested, preventing context window overflow while supporting unlimited auxiliary resources.

What validation does package_skill.py perform?

The script validates that SKILL.md contains required front-matter fields (name and description), checks that resource directories follow naming conventions, and verifies the overall folder layout using quick_validate.validate_skill. It fails fast with descriptive errors if the skill structure deviates from the specification.

Where should I place deterministic scripts versus reference materials?

Place deterministic automation scripts in the scripts/ directory, as these execute outside the LLM context through the skill's execution environment. Place large documentation, knowledge bases, or API specifications in references/ for Claude to read when needed. Keep assets/ reserved for binary files like templates or icons that support the workflow but do not require parsing.

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