skill-creator Complete Guide - Claude Skills Development Framework¶

This article reflects January 2026 information

Skills/Plugin installation methods and marketplace specifications may have changed. For the latest Skills installation guide, see SkillsMP (Agent Skills Marketplace) Complete Guide.

March 2026 Update: skill-creator now includes an eval pipeline (eval/improve/benchmark modes). See skill-creator New Version - How Eval Pipelines Transform Skill Development for details.

Key Points¶

What is skill-creator - A tool that generates Skills through dialog
How to use it - Two approaches (Build from scratch / Convert conversations)
How to improve generated Skills - Understanding structure and customization

The Key Benefit of skill-creator

Just tell it what Skill you want. skill-creator will interview you through dialog and automatically generate SKILL.md and directory structure. You don't need to learn design principles or formats beforehand.

What is skill-creator¶

skill-creator is "a tool that creates Skills through dialog."

What You Do¶

Tell Claude Code "I want to create a skill for ○○"
Answer skill-creator's questions
Test and improve the generated Skill

What skill-creator Does¶

Interview you about requirements (what to create, when to trigger, etc.)
Automatically generate SKILL.md based on design principles
Create appropriate directory structure (scripts/, references/, assets/)
Generate script templates as needed

sequenceDiagram
    participant You as You
    participant SC as skill-creator
    participant Output as Output

    You->>SC: "Create a PDF processing skill"
    SC->>You: "What features do you need?"
    You->>SC: "Rotation, text extraction, merging"
    SC->>You: "When should it trigger?"
    You->>SC: "When asked to edit PDFs"
    SC->>Output: Generate SKILL.md + scripts/
    Output->>You: Review and test the Skill

First Time Users

You don't need to understand "Core Design Principles" or "Skill Structure" beforehand. skill-creator handles these automatically.

Refer to this information when you need to modify the generated Skill.

Installation¶

Installing in Claude Code¶

# Add the marketplace
/plugin marketplace add anthropics/skills

# Install example-skills (includes skill-creator)
/plugin install example-skills@anthropic-agent-skills

# Optional: Add document-skills (DOCX/PDF operations, etc.)
/plugin install document-skills@anthropic-agent-skills

After installation, restart Claude Code and verify skill-creator appears with the /skills command.

About Licenses

example-skills: Apache 2.0 (open source, free to modify and redistribute)
document-skills: Source-available (for reference and learning, redistribution restricted)

How to Use: Two Approaches¶

skill-creator offers two ways to create Skills. Choose based on your situation.

Approach 1: Build from Scratch (Dialog Mode)¶

Use when you want to create a new Skill from the ground up.

Use skill-creator to create a PDF processing skill

skill-creator will ask questions interactively:

"What features should it support?"
"When should this Skill trigger?"
"Do you need scripts?"

You just answer the questions, and SKILL.md and directory structure are generated automatically.

Dialog Example¶

You: I want to create a code review skill using skill-creator

skill-creator: I'll create a code review skill. Let me ask you a few questions.

1. What aspects should it review?
   (e.g., security, performance, readability, test coverage, etc.)

You: I want to focus on security and performance

skill-creator: 
2. When should this skill trigger?
   (e.g., "review my code", "check this PR", etc.)

You: When someone says "review this" or "check my code"

skill-creator: Got it. I'll generate the Skill with this structure...
[Automatically generates SKILL.md and scripts/security_check.py]

Approach 2: Convert from Conversation¶

Use when you want to turn a successful AI conversation pattern into a Skill.

(After a successful conversation)
Use skill-creator to convert this conversation into a skill

skill-creator automatically:

Analyzes conversation patterns
Extracts reusable workflows
Generates SKILL.md template

Use Cases¶

Scenario	Example
Complex analysis flows	Data analysis → visualization → report generation sequence
Troubleshooting	Error resolution dialog patterns
Code reviews	Extracting review criteria and checklists

Benefits of Converting Conversations to Skills

Aspect	Before Skill	After Skill
Reproducibility	Need same explanation each time	Consistent workflow
Quality	Variation depending on dialog	Standardized process
Sharing	Individual tacit knowledge	Shareable with team

After Generation¶

Once a Skill is generated, follow these steps to use and improve it.

Step 1: Review the Generated Skill¶

# Check the generated directory structure
ls -la skills/my-new-skill/

# Review SKILL.md contents
cat skills/my-new-skill/SKILL.md

Step 2: Test and Use¶

Use the Skill for actual tasks and verify behavior.

"Rotate this PDF" (← Skill should trigger)

Step 3: Improve as Needed¶

If it doesn't work as expected or needs improvement:

Edit SKILL.md to adjust trigger conditions and steps
Add/modify scripts in scripts/
Add reference documents to references/

Reference Information for Improvements

Check the "Reference Section" below for Skill structure and design principles.

[Reference] What to Know When Improving¶

How to Read This Section

The following content is for modifying Skills generated by skill-creator. For initial generation, skill-creator considers these principles automatically.

Skill Structure¶

Required File: SKILL.md¶

---
name: skill-name          # Required: hyphen-case identifier (64 chars max)
description: ...          # Required: description with trigger conditions (200 chars recommended, max 1024)
license: See LICENSE.txt  # Optional
allowed-tools: [...]      # Optional: list of allowed tools
metadata: {...}           # Optional: custom metadata
---

# Skill Name

## Overview
[Explain Skill functionality in 1-2 sentences]

## Workflow
[Steps and guidance]

Importance of description

description is the most important element for determining trigger conditions. Always include "when to use" information here. The body is loaded after triggering, so the "Usage Scenarios" section in the body won't reach Claude for triggering.

Directory Structure¶

skill-name/
├── SKILL.md              # Required: metadata and instructions
├── scripts/              # Optional: executable code
├── references/           # Optional: reference documents
└── assets/               # Optional: output files

scripts/references/assets/

Executable Code (Python/Bash, etc.)

Code requiring deterministic reliability
Reusable utilities
Examples: rotate_pdf.py, extract_text.py

Reference Documents

Information Claude should reference during work
API documentation, schema definitions, etc.
Examples: schema.md, api_docs.md

Output Files

Files used in Claude's output
Templates, logos, boilerplate
Examples: template.pptx, boilerplate/

Core Design Principles¶

1. Prioritize Conciseness¶

Claude is already very smart, so only add information Claude doesn't inherently have.

❌ Verbose Explanation✅ Concise Example

To rotate a PDF file, you first need to import a PDF library.
Python has various PDF libraries available...

PDF rotation: `scripts/rotate_pdf.py 90 input.pdf output.pdf`

2. Set Appropriate Freedom Levels¶

Freedom	Use Case	Format
High	Multiple approaches valid	Text-based instructions
Medium	Recommended patterns exist	Pseudocode
Low	Consistency required	Specific scripts

3. Script Deterministic Processing¶

One of the most important design principles. AI is smart, but may return slightly different outputs for the same input each time.

AI Judgment Variability

Character counting → Calculation method may vary slightly
File validation → Possible missing check items
Format conversion → Output format inconsistencies

Processing that requires 100% identical results should be implemented as scripts in scripts/, not as text instructions in SKILL.md.

❌ Text Instructions (Variable)✅ Scripted (Deterministic)

## Character Count Check
Count the article characters and verify it's within 2000-3000 range.

## Character Count Check
Run `python scripts/check_article.py <file>`

Script Decision Criteria:

Processing Type	Should Script?	Reason
Character/line counting	✅ Required	Same result needed every time
Syntax checking	✅ Required	Detect all items without omission
File conversion	✅ Recommended	Output format consistency
Text editing suggestions	❌ Not needed	AI judgment appropriate
Design review	❌ Not needed	Context understanding required

4. Progressive Disclosure¶

graph LR
    A[Level 1: Metadata<br/>~100 tokens・Always loaded] --> B[Level 2: SKILL.md Body<br/><5000 tokens・On trigger]
    B --> C[Level 3: Bundled Resources<br/>Unlimited・As needed]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

Watch Token Consumption

Level 1 metadata is always loaded into context even when the Skill isn't used. Each Skill consumes about 100 tokens, so periodically uninstall unnecessary Skills.

Development Tools (Manual Use)¶

When to Use

When using skill-creator, these scripts are called automatically. Manual execution is needed for:

Creating from scratch without skill-creator
Manually validating/packaging generated Skills

init_skill.py - Initialization¶

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

quick_validate.py - Validation¶

python scripts/quick_validate.py <skill-directory>

Validation Checks:

Item	Check
SKILL.md exists	File exists
YAML frontmatter	Correct format
Required fields	`name` and `description` present
Naming convention	Hyphen-case (lowercase, numbers, hyphens)
Reserved words	`name` doesn't contain reserved words (`anthropic`, `claude`)
Character limits	name: 64 chars max, description: 200 chars recommended / max 1024

Official Documentation Discrepancy

Description character limit differs between Help Center ("200 characters") and Docs ("max 1024 characters"). Aim for 200 characters for safety.

package_skill.py - Packaging¶

python scripts/package_skill.py <skill-directory> [output-directory]

Body Structure Patterns¶

Workflow-BasedTask-BasedReference-Based

For sequential processes:

## Overview → ## Decision Flow → ## Step 1 → ## Step 2...

For independent operations:

## Overview → ## Quick Start → ## Task 1 → ## Task 2...

For standards/specifications:

## Overview → ## Guidelines → ## Specifications → ## Examples...

Progressive Disclosure Patterns¶

Target under 5000 tokens (~500 lines) for SKILL.md, separating details.

Pattern 1: High-Level Guide + References

## Advanced Features
- **Form Input**: See [FORMS.md](FORMS.md)
- **API Reference**: See [REFERENCE.md](REFERENCE.md)

Pattern 2: Domain-Based Structure

bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Should You Use skill-creator?¶

Good Fit Cases¶

Case	Reason
Recurring tasks	Skill creation cost is recovered
Clear procedure workflows	Easy to document in SKILL.md
Tasks involving code execution	Reusable via scripts/ directory
Knowledge to share with team	Distributable as a Skill

Not a Good Fit (Gap)¶

Case	Reason	Alternative
One-time tasks	Not worth the cost	Regular prompts
Frequently changing requirements	High maintenance cost	Memory / Projects
Primarily external API integration	MCP is more appropriate	MCP
Tasks involving sensitive information	Security risks	Consider secure methods

Decision Criteria

"Will I repeat this task 3+ times?" is a good benchmark for Skill creation.

Security Considerations¶

Skills involve code execution, so security requires careful attention.

Use Only Trusted Sources

Anthropic strongly recommends using only Skills you've created yourself or official Anthropic Skills.

Security Checklist¶

No hardcoded API keys, passwords, or secrets
No unintended external network connections
Appropriate file access scope
Audited scripts/ code when using third-party Skills

Safe Secret Management¶

# ❌ Bad: Hardcoded
API_KEY = "sk-1234567890abcdef"

# ✅ Good: From environment variable
import os
API_KEY = os.environ.get("API_KEY")

Available Official Skills¶

Category	Key Skill	Purpose
Meta	skill-creator	Skill creation assistance
Development	mcp-builder	MCP server building
Creative	algorithmic-art	Generative art
Document	docx, pdf, pptx, xlsx	Document operations

Check the official documentation for latest information.

Platform Differences¶

Feature	Claude Code	Claude.ai	API
SKILL.md loading	✅ Local	✅ Upload	✅ system prompt
scripts/ execution	✅ Direct	⚠️ With Code Execution	⚠️ With Code Execution tool
references/ access	✅ Auto-loaded	⚠️ Manual attach	⚠️ Manual include

Using Skills with API

With API, specify skill_id in the container parameter and combine with code execution tool to enable scripts/ execution.

Best Practices Summary¶

Category	Recommendation
Conciseness	Only add information Claude doesn't know
Triggers	Include usage scenarios in `description` (200 chars recommended)
Structure	SKILL.md under 5000 tokens, separate details
Fields	`name` cannot contain reserved words (`anthropic`, `claude`)
Testing	Always verify behavior after generation

Claude Skills Complete Guide - General Skills explanation
Claude Skills API Implementation Guide - API integration
Claude Code Complete Guide - Claude Code basics

Next Steps

Install skill-creator and verify with /skills
Say "Create a skill for ○○" to start the dialog
Test the generated Skill and improve