name	skill-creator
description	Guide for creating effective Agent Skills. Use when creating a new skill (or updating an existing skill) that extends capabilities with specialized knowledge, workflows, or tool integrations. Helps with skill initialization, validation, and best practices.
license	Complete terms in LICENSE

Claude Code Skill Creator

Specialized in creating effective, well-structured Claude Code Agent Skills following best practices and design patterns.

When to Use This Skill

Creating a new Claude Code Agent Skill from scratch
Updating or refactoring existing skills
Understanding skill structure and YAML frontmatter requirements
Implementing progressive disclosure patterns
Validating skill format and requirements
Following skill authoring best practices

Core Principles

Context Window is a Public Good: Keep content concise and essential
Progressive Disclosure: Structure information in layers (metadata → body → references)
Appropriate Freedom: Match specificity to task fragility
Clear Activation Triggers: Description must specify both function and when to use
Single Responsibility: One skill per capability or domain
Concrete Examples: Provide specific input/output examples

Skill Anatomy

Required Structure

skill-name/
├── SKILL.md              # Required: Main skill definition
├── scripts/              # Optional: Executable utilities (Python, Bash)
├── references/           # Optional: Detailed documentation
└── assets/               # Optional: Templates, non-context resources

SKILL.md Format

---
name: skill-name
description: What it does and when to use it (max 1024 chars)
allowed-tools: [optional list]  # Optional: Restrict tool access
---

# Skill Title

## When to Use This Skill
- Specific trigger scenarios

## Core Principles
- Guiding design principles

## Implementation Guidelines
- Detailed instructions with examples

## Tools to Use
- Tool usage patterns

## Workflow
- Step-by-step process

## Related Skills
- Cross-references to other skills

YAML Frontmatter Requirements

Required Fields

name (required):

Max 64 characters
Lowercase letters, numbers, hyphens only
Cannot start/end with hyphens
No consecutive hyphens
No XML tags or reserved words ("anthropic", "claude")

Example: python-core-development, rails-service-objects

description (required):

Max 1024 characters
No XML tags (< or >)
Must specify both functionality AND activation triggers
Written in third person

Good example:

description: Implement Python code with dataclasses, type hints, protocols, error handling, and async programming. Use when designing classes, implementing type safety, handling exceptions, or writing async code.

Bad example:

description: Helps with Python development

Optional Fields

allowed-tools: Restrict Claude's tool access within this skill

allowed-tools: [Read, Grep, Glob, Write, Edit, Bash, WebFetch]

Progressive Disclosure Design

Structure skills in three levels to manage context efficiently:

Level 1: Metadata (Always Loaded)

name and description in YAML frontmatter
Claude uses this to decide whether to activate the skill

Level 2: Skill Body (Loaded When Activated)

Overview and core principles (50-150 lines)
Essential guidelines and patterns
Common use cases
Keep main file under 500 lines

Level 3: References (Loaded On Demand)

Detailed documentation in references/ directory
API specifications
Extended examples
One level deep maximum (no nested directories)

Example:

skill-name/
├── SKILL.md                    # Level 2: Core guidance
├── references/
│   ├── api-reference.md        # Level 3: API details
│   ├── advanced-patterns.md    # Level 3: Advanced techniques
│   └── examples.md             # Level 3: Extended examples

Skill Creation Workflow

1. Planning

Define the skill's single responsibility
Identify trigger scenarios
Determine required tools
Plan progressive disclosure structure

2. Initialize Skill

Use the init_skill.py script:

python configs/claude/skills/claude-code-skill-creator/scripts/init_skill.py skill-name --path configs/claude/skills

This creates:

Directory structure
SKILL.md template with TODOs
Placeholder directories

3. Write SKILL.md

Structure your content:

When to Use This Skill: Clear trigger scenarios
Core Principles: 3-6 guiding principles
Implementation Guidelines: Concrete patterns with code examples
Tools to Use: Specific tool usage
Workflow: Step-by-step process
Related Skills: Cross-references

Best practices:

Use code examples for every pattern
Include WHY comments in code
Keep examples focused and minimal
Reference related skills
Stay under 500 lines

4. Add Reference Files

Create references/ files for:

Detailed API documentation
Advanced patterns
Extended examples
Domain-specific guides

Include table of contents for long reference files.

5. Add Utility Scripts

Create scripts/ for:

Code generation
Validation
Data processing
Common operations

Requirements:

Explicit error handling
Helpful error messages
Document all constants
List required packages
Executable permissions (chmod +x)

6. Validate Skill

python configs/claude/skills/claude-code-skill-creator/scripts/validate_skill.py configs/claude/skills/skill-name

Checks:

SKILL.md exists
Valid YAML frontmatter
Required fields present
Name format correct
Description within limits

7. Test and Iterate

Test with Claude using trigger phrases from description
Verify Claude discovers and activates the skill
Refine based on actual usage patterns
Iterate on description for better activation

Naming Conventions

Skill Names

Use gerund form (verb + -ing) for action-based skills:

✓ processing-pdfs, analyzing-data, generating-reports
✗ pdf-processor, data-analyzer, report-generator

Use domain-noun for knowledge/reference skills:

✓ python-core-development, rails-security, react-components

Avoid:

Vague terms: helper, utils, tools
Generic names: backend, frontend
Overly broad: programming, development

File Names

References:

api-reference.md - API documentation
best-practices.md - Best practices guide
examples.md - Extended examples
advanced-patterns.md - Advanced techniques

Scripts:

init_*.py - Initialization scripts
validate_*.py - Validation scripts
generate_*.py - Generation scripts

Common Anti-Patterns

❌ Avoid

Vague descriptions:

description: Helps with Python development

Information Claude already knows:

Python uses indentation for code blocks...

Overly complex main file (>500 lines):

SKILL.md with 1000+ lines of content

Multiple responsibilities:

name: backend-development  # Too broad
description: Handle all backend tasks

Windows-style paths:

path = "configs\\claude\\skills"  # Wrong

✓ Use Instead

Specific descriptions with triggers:

description: Implement Python code with dataclasses, type hints, protocols, error handling, and async programming. Use when designing classes, implementing type safety, handling exceptions, or writing async code.

Progressive disclosure:

SKILL.md (300 lines) → references/api-reference.md → references/examples.md

Single responsibility:

name: python-core-development
description: Core Python class design and type safety

Forward slashes:

path = "configs/claude/skills"  # Correct

Effective Description Writing

Description format: [What it does]. Use when [trigger scenarios].

Examples:

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs.