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

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 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, 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 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.

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 utility generates a correctly-named folder structure with starter templates:

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 – Template with YAML front-matter and TODO sections
• pdf-rotator/scripts/example.py – Placeholder script
• pdf-rotator/references/api_reference.md – Placeholder documentation
• pdf-rotator/assets/example_asset.txt – Placeholder asset

package_skill.py

The package_skill.py utility validates and archives skills for distribution:

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

This script invokes 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:

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 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

4. Add Implementation Scripts

Replace placeholder files with working implementations. For example, create scripts/rotate_pdf.py:

#!/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 body:

## 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 to verify structural compliance:

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

The validator checks for:

• Presence of 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:

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 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:

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:

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 metadata, instructional body content, and segregated resource directories
• init_skill.py scaffolds new skills with proper hyphen-case naming and example files
• package_skill.py validates skills via 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. 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 presence, proper YAML front-matter syntax, and naming convention compliance. This validator is automatically invoked by 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.

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