# How to Create New Claude Skills with the skill-creator Framework

> Learn to create new Claude Skills using the Composio skill-creator framework. Scaffold, validate, and package your skills for distribution with this powerful tool.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The skill-creator framework scaffolds self-contained Claude Skills using YAML front-matter metadata, markdown instructions, and bundled resource directories that can be validated and packaged for distribution.**

The skill-creator framework from ComposioHQ/awesome-claude-skills provides a standardized toolbox for building modular AI capabilities. This framework generates a complete skill structure with mandatory [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) files and optional resource bundles, ensuring consistent deployment across Claude AI, Claude Code, and the Anthropic API.

## Anatomy of a Claude Skill

A Claude Skill is a self-contained folder with three logical layers that separate lightweight metadata from heavy resources. According to the source code in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md), this architecture ensures efficient token usage by loading only essential information initially.

### Metadata Layer (SKILL.md Front-matter)

The **metadata** layer resides in the YAML front-matter of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) and consists of approximately 100 tokens containing the skill `name` and `description`. This information is always loaded into context to help Claude determine skill relevance. The framework enforces **hyphen-case** naming with a maximum of 40 characters as implemented in [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py).

### Body Layer (SKILL.md Instructions)

The **body** contains full markdown instructions (up to 5,000 tokens) that provide imperative guidance for executing the skill. Unlike metadata, this content loads only when Claude determines the skill is relevant to the current conversation, optimizing context window usage.

### Bundled Resources Layer (Sub-directories)

Heavy assets reside in three optional sub-folders that Claude pulls on demand:
- `scripts/` – Deterministic helper scripts (Python, bash, etc.)
- `references/` – External documentation or API references
- `assets/` – Static templates or configuration files

This separation allows skills to host megabytes of reference material without inflating every chat session's token count.

## CLI Scaffolding Tools

The framework provides two primary CLI helpers in `skill-creator/scripts/` that enforce the required directory layout and naming conventions.

### init_skill.py

The [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py) utility generates a correctly-named folder structure with starter templates:

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

```

This command creates:
- `pdf-rotator/` – Root folder with hyphen-case naming
- [`pdf-rotator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/pdf-rotator/SKILL.md) – Template with YAML front-matter and TODO sections
- [`pdf-rotator/scripts/example.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/pdf-rotator/scripts/example.py) – Placeholder script
- [`pdf-rotator/references/api_reference.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/pdf-rotator/references/api_reference.md) – Placeholder documentation
- [`pdf-rotator/assets/example_asset.txt`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/pdf-rotator/assets/example_asset.txt) – Placeholder asset

### package_skill.py

The [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) utility validates and archives skills for distribution:

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

```

This script invokes [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) to check for required files and proper front-matter syntax before generating `dist/pdf-rotator.zip` with the exact folder structure required by Claude agents.

## Step-by-Step Creation Workflow

Follow this process to create new Claude Skills from concept to deployment.

### 1. Plan Skill Requirements

Gather concrete examples of user queries your skill must handle (e.g., "rotate this PDF 90 degrees"). Determine which reusable scripts, reference documents, or assets Claude will need to satisfy these requests.

### 2. Initialize the Skill Structure

Execute the initialization script with your desired skill name:

```bash
python skill-creator/scripts/init_skill.py my-new-skill --path ./skills/public

```

Replace example files with production resources while maintaining the directory names (`scripts/`, `references/`, `assets/`).

### 3. Configure SKILL.md

Edit [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) to replace `[TODO]` sections with:
- **Purpose**: Clear description of what the skill accomplishes
- **Triggers**: Specific phrases or intents that activate the skill
- **Instructions**: Imperative workflow steps following the style guidelines in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md)

### 4. Add Implementation Scripts

Replace placeholder files with working implementations. For example, create [`scripts/rotate_pdf.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/rotate_pdf.py):

```python
#!/usr/bin/env python3
"""
Rotate a PDF file by a given angle.
Usage: rotate_pdf.py <input.pdf> <output.pdf> <angle>
"""

import sys
import fitz  # PyMuPDF

def rotate(in_path, out_path, angle):
    doc = fitz.open(in_path)
    for page in doc:
        page.set_rotation(angle)
    doc.save(out_path)

if __name__ == "__main__":
    rotate(sys.argv[1], sys.argv[2], int(sys.argv[3]))

```

Reference this script in your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) body:

```markdown

## Workflow – Rotate PDF

1. **Load the PDF** – Claude uploads the user's PDF file.
2. **Run the helper** – Execute `scripts/rotate_pdf.py <uploaded> <output> 90`.
3. **Return the result** – Provide the rotated PDF back to the user.

```

## Validation and Packaging

Before distribution, validate your skill using the built-in validator.

### Running Validation

Execute [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) to verify structural compliance:

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

```

The validator checks for:
- Presence of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) with valid YAML front-matter
- Hyphen-case naming convention compliance
- Maximum name length of 40 characters

### Creating Distribution Archives

Package validated skills for deployment:

```bash
python skill-creator/scripts/package_skill.py ./skills/public/my-new-skill ./dist

```

This generates `dist/my-new-skill.zip` containing the complete folder structure with [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) and all bundled resources.

## Deployment Options

Deploy your packaged skill to the target Claude environment based on your integration method.

### Claude AI (Web Interface)

Upload the skill via the skill marketplace UI by importing the generated ZIP file.

### Claude Code (CLI)

Place the skill folder (not the ZIP) in the local skills directory:

```bash
cp -r ./skills/public/my-new-skill ~/.config/claude-code/skills/

```

Claude Code automatically discovers skills in this location during startup.

### Anthropic API

Reference the skill ID in API calls:

```python
import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_KEY")
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    skills=["my-new-skill"],
    messages=[{"role": "user", "content": "Execute my custom workflow"}],
)

```

## Summary

- **skill-creator** generates standardized skill folders with [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) metadata, instructional body content, and segregated resource directories
- **[`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py)** scaffolds new skills with proper hyphen-case naming and example files
- **[`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py)** validates skills via [`quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/quick_validate.py) and creates distributable ZIP archives
- Skills deploy to Claude AI via marketplace upload, Claude Code via `~/.config/claude-code/skills/`, or the API via the `skills` parameter
- The three-layer architecture (metadata, body, resources) optimizes token usage by loading heavy assets only when needed

## Frequently Asked Questions

### What is the maximum length for a skill name?

Skill names must use hyphen-case formatting and cannot exceed 40 characters, as enforced by the validation logic in [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py). Names longer than this limit will fail validation during the packaging process.

### How do I validate my skill before packaging?

Run `python skill-creator/scripts/quick_validate.py <skill-path>` to check for required [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) presence, proper YAML front-matter syntax, and naming convention compliance. This validator is automatically invoked by [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) before ZIP creation.

### Where should I place skills for Claude Code?

Copy the skill folder (not the ZIP archive) to `~/.config/claude-code/skills/` on your local machine. Claude Code scans this directory during initialization and loads any valid skills found there.

### What belongs in the SKILL.md front-matter versus the body?

The **front-matter** (YAML between `---` delimiters) contains only the skill `name` and `description` (≈100 tokens) for relevance detection. The **body** contains the full markdown instructions (up to 5,000 tokens) that guide Claude's behavior when the skill is active.