# How to Create a New Claude AI Skill: The Complete Developer Guide > Learn how to create a new Claude AI skill with our complete developer guide. Follow simple steps to scaffold, author, script, and validate your new skill. Get started today! - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: how-to-guide - Published: 2026-07-24 --- **Creating a new Claude AI skill involves scaffolding a modular folder structure with [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py), authoring a concise [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with YAML front-matter, adding deterministic scripts to the `scripts/` directory, and validating the package with [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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: ```bash python skill-creator/scripts/init_skill.py --path ``` This command, defined in [`skill-creator/scripts/init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/init_skill.py), creates a new directory containing a template [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) along with example subdirectories: `scripts/`, `references/`, and `assets/`. ### 4. Author the SKILL.md File Edit the generated [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) to include the required YAML front-matter and body content: ```yaml --- 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/example.py) or [`example_asset.txt`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/example_asset.txt)) before packaging. ### 6. Validate and Package Execute the packaging script to validate structure and create the distributable archive: ```bash python skill-creator/scripts/package_skill.py [output-dir] ``` This script invokes `quick_validate.validate_skill` from [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py) to verify your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) contains required front-matter fields and that the folder layout adheres to specification. Upon successful validation, the script generates `.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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) instructions based on actual interactions, add missing resources to `scripts/` or `references/`, and re-run [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py)** generates the skeleton directory structure and starter [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) to enforce schema requirements before archiving. ## Minimal Working Example To create a new Claude AI skill named "pdf-rotator" from scratch: ```bash # 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py)** automates the creation of the standardized folder structure and starter files required by the Anthropic specification. - **[`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.