Skill Creator

Skill Creator

Overview

Create effective skills that extend Claude's capabilities through specialized knowledge, workflows, and tools. Skills are modular packages that transform Claude from a general-purpose agent into a specialized agent with procedural knowledge for specific domains.

This skill exemplifies its own teachings by using progressive disclosure to keep the entry point lean while providing deep detail in reference files.

When to Use This Skill

Activate when:

• Creating a new skill from scratch
• Updating or refactoring an existing skill
• Adding progressive disclosure to monolithic skills
• Understanding skill structure and best practices
• Planning skill components (scripts, references, assets)
• Packaging skills for distribution

Core Principles

1. Example-Driven Design: Start with concrete usage examples, not abstract concepts 2. Progressive Disclosure: Keep entry point <200 lines (optimal: 140-160), detailed content in references 3. Reusable Components: Extract scripts for repeated code, references for knowledge, assets for templates 4. Imperative Voice: Use verb-first instructions throughout (not second person) 5. Purpose-Built Resources: Each component should solve specific repetitive needs

What Skills Provide

Four Core Capabilities: 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex tasks

Three-Level Loading System: 1. Metadata (name + description) - Always in context (~100 words) 2. SKILL.md body - When skill triggers (<200 lines, optimal: 140-160) 3. Bundled resources - As needed by Claude (unlimited)

Quick Start

Six-Step Creation Process

Step 1: Understand with Concrete Examples Gather 3-5 realistic usage examples. Ask: "What would users say to trigger this skill?" and "What tasks should it accomplish?" → Complete guide

Step 2: Plan Reusable Components Analyze examples to identify: scripts (repeated code), references (domain knowledge), assets (templates). → Planning guide

Step 3: Initialize Skill Run scripts/init_skill.py <skill-name> --path <output-directory> to generate template structure. → Initialization details

Step 4: Edit Skill Implement scripts/references/assets, then update SKILL.md using imperative voice. Apply progressive disclosure if >150 lines. → Editing guide

Step 5: Package and Validate Run scripts/package_skill.py <path/to/skill-folder> to validate and create distributable zip. → Packaging guide

Step 6: Iterate Use on real tasks, notice struggles, update skill accordingly. → Iteration guide

Skill Anatomy

skill-name/
├── SKILL.md (required)           # Entry point with frontmatter + markdown
├── scripts/ (optional)           # Executable code (Python/Bash)
├── references/ (optional)        # Documentation loaded as needed
└── assets/ (optional)            # Templates, images, files for output

Component Guidelines:

• Scripts: When same code is repeatedly rewritten or deterministic execution needed
• References: For detailed specs, workflows, schemas, API docs (150-500 lines each)
• Assets: For templates, boilerplate, images, fonts used in outputs
• Entry Point: Core workflow, navigation, reminders (140-160 lines optimal)

→ Complete structure guide

Progressive Disclosure Pattern

When to apply: Skills >150 lines total

Implementation: 1. Add progressive_disclosure frontmatter with summary, when_to_use, quick_start 2. Reduce entry point to 140-160 lines (core workflow + navigation) 3. Create 3-5 reference files (150-500 lines each) 4. Organize by topic: structure, workflow, best practices, examples 5. Add navigation section linking all references

Benefits:

• Entry loads only essential content
• Deep detail available when needed
• Better organization and maintainability
• 20-30% reduction in entry point size

→ Complete progressive disclosure guide

Meta-example: This skill-creator demonstrates progressive disclosure:

• Entry: 150 lines (28% reduction from 209)
• References: 5 files with complete implementation details
• Recently optimized: mcp-builder (160 lines), testing-anti-patterns (140 lines)

Navigation

Core Concepts

• [🏗️ Skill Structure](./references/skill-structure.md) - Anatomy, components (scripts/references/assets), progressive disclosure architecture. Load when planning skill layout or understanding resource types.

Step-by-Step Process

• [🔄 Creation Workflow](./references/creation-workflow.md) - Complete 6-step process from examples to iteration. Load when creating new skill or following structured workflow.

Design Patterns

• [📊 Progressive Disclosure](./references/progressive-disclosure.md) - Three-level loading, implementation guide, anti-patterns, examples. Load when refactoring skills >150 lines or optimizing context usage.

Quality Standards

• [✅ Best Practices](./references/best-practices.md) - Writing style, metadata quality, content organization, anti-patterns. Load when writing/reviewing skill content or ensuring quality.

Real-World Examples

• [📚 Examples](./references/examples.md) - Complete skill examples: mcp-builder, testing-anti-patterns, pdf-editor, brand-guidelines, database-builder, frontend-builder. Load when starting new skill or seeking patterns.

Key Reminders

• Start with examples - 3-5 concrete usage scenarios before designing
• Use init script - scripts/init_skill.py creates proper structure automatically
• Imperative voice - "To accomplish X, do Y" (not "should do X")
• Progressive disclosure - Entry <200 lines, details in references (for skills >150 lines)
• Avoid duplication - Information lives in ONE place (entry summary, reference detail)
• Component clarity - Scripts for code, references for knowledge, assets for templates
• Validate before sharing - scripts/package_skill.py validates and packages
• Iterate continuously - Use on real tasks, update based on struggles

Red Flags - STOP

STOP when:

• "Let me write all the details in SKILL.md" → Move to references (progressive disclosure)
• "I'll use second person" → Switch to imperative voice
• "Same information in entry and reference" → Delete duplication
• Using generic description → Be specific about activation conditions
• Leaving example files from init script → Delete unused resources
• Skipping validation → Always run package_skill.py before sharing
• Creating skill without examples → Gather concrete usage scenarios first
• Entry point >200 lines → Apply progressive disclosure pattern

ALL of these mean: STOP. Review principles and references.

Integration with Other Skills

Meta-Skills:

• skill-creator (this skill) - Creates other skills, demonstrates its own patterns

Development Skills:

• mcp-builder - Example of progressive disclosure implementation
• testing-anti-patterns - Example of ultra-lean entry point (140 lines)

Workflow Skills:

• documentation - Writing clear, structured content
• verification-before-completion - Testing skills before packaging

Real-World Impact

From skill optimization experience:

• Progressive disclosure: 20-30% reduction in entry point size
• mcp-builder: 209 → 160 lines (23% reduction, 6 references)
• testing-anti-patterns: → 140 lines (ultra-lean with 4 references)
• skill-creator: 209 → 150 lines (28% reduction, 5 references)
• Context efficiency: Load only needed references (saves 50-80% context)
• Maintainability: Update specific references without touching entry point
• Clarity: Better organization improves discoverability and comprehension

---

Remember: Skills are modular packages that transform Claude into a specialized agent. Apply progressive disclosure for skills >150 lines. This skill demonstrates the pattern it teaches.

Skill Creation Best Practices

Writing Style and Voice

Imperative Form (MANDATORY)

All skill content MUST use imperative/infinitive form (verb-first instructions), not second person.

✅ Correct Examples:

• "To accomplish X, do Y"
• "Follow these steps to complete the task"
• "Load the reference file when needed"
• "Execute the script with these parameters"
• "Consider these factors before proceeding"

❌ Incorrect Examples:

• "You should do X"
• "If you need to do X"
• "You can find this in..."
• "Your task is to..."
• "You will need to..."

Rationale:

• Maintains consistency across all skills
• Optimizes for AI comprehension
• Removes ambiguity about audience
• Creates professional, instructional tone
• Easier to scan and parse

Voice and Tone Guidelines

Objective and Instructional:

• Focus on clear procedures and workflows
• State facts and requirements directly
• Avoid conversational filler
• Be specific and actionable

Active Voice:

• "Execute the script" not "The script should be executed"
• "Load the reference" not "The reference can be loaded"
• "Validate the input" not "Input should be validated"

Present Tense:

• "The skill provides..." not "The skill will provide..."
• "Claude loads..." not "Claude will load..."
• "Scripts execute..." not "Scripts will execute..."

Documentation Style

Concise and Scannable:

• Use bullet points for lists
• Keep paragraphs short (2-4 sentences)
• Use headers to organize content
• Highlight key terms in bold
• Use code blocks for examples

Example-Driven:

• Show concrete examples
• Demonstrate patterns in practice
• Provide before/after comparisons
• Include realistic scenarios

Metadata Quality

Name Field

The name: field in YAML frontmatter should be:

Format: kebab-case (lowercase with hyphens)

Examples:

• ✅ skill-creator
• ✅ mcp-builder
• ✅ testing-anti-patterns
• ❌ Skill Creator
• ❌ skill_creator
• ❌ skillCreator

Description Field

The description: field determines when Claude activates the skill. Write descriptions that:

Be Specific About Purpose:

• Clearly state what the skill does
• Mention key capabilities
• Include constraints or limitations

Use Third Person:

• "This skill should be used when..." ✅
• "Use this skill when..." ❌
• "The skill provides..." ✅
• "Provides..." ❌

Include Activation Conditions:

• What user requests trigger the skill?
• What keywords or scenarios activate it?
• When should it NOT be used?

Examples:

✅ Good:

description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).

❌ Too Vague:

description: Helps with MCP servers.

❌ Wrong Voice:

description: Use this when you need to build MCP servers.

✅ Good:

description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Content Organization

Entry Point Structure

For skills using progressive disclosure, organize the entry point with these sections:

1. Overview (2-3 sentences)

• What the skill provides
• Key capabilities
• Primary value proposition

2. When to Use This Skill (5-10 bullet points)

• Clear activation scenarios
• Specific trigger conditions
• Related keywords

3. The Iron Law (Optional, if applicable)

• Non-negotiable principles
• Core constraints
• Fundamental requirements

4. Core Principles (3-5 brief principles)

• Foundational guidelines
• Key philosophies
• Essential approaches

5. Quick Start (5-10 steps)

• High-level workflow
• Phase-based organization
• Links to detailed references

6. Navigation (Annotated list)

• All reference files
• Clear descriptions
• When to load each

7. Key Reminders (5-10 bullets)

• Critical points
• Common pitfalls
• Essential practices

8. Red Flags - STOP (5-10 warning signs)

• Anti-patterns to avoid
• Warning indicators
• Stop conditions

9. Integration with Other Skills (Optional)

• Related skills
• Prerequisites
• Complementary skills

10. Real-World Impact (Optional)

• Metrics and outcomes
• Evidence of effectiveness
• Success stories

Reference File Structure

Each reference file should have:

Clear Purpose Statement:

# Reference Topic Name

## Purpose

Brief description of what this reference covers and when to use it.

Logical Organization:

• Clear section hierarchy
• Progressive complexity (simple → advanced)
• Self-contained content
• Cross-references where helpful

Appropriate Depth:

• 150-500 lines per file
• Combine if <150 lines
• Split if >500 lines

Resource Organization

Scripts Best Practices

When to Create Scripts:

• Same code repeatedly rewritten
• Deterministic execution required
• Complex operations benefit from testing
• Performance optimization matters

Script Quality:

• Include usage documentation
• Handle errors gracefully
• Support common parameters
• Add helpful error messages
• Make executable (chmod +x)

Documentation in SKILL.md:

Execute `scripts/rotate_pdf.py <input.pdf> <output.pdf> <degrees>` to rotate PDFs.

Parameters:
- input.pdf: Source PDF file
- output.pdf: Destination file path
- degrees: Rotation angle (90, 180, 270)

References Best Practices

Content That Belongs in References:

• Detailed specifications
• API documentation
• Database schemas
• Step-by-step workflows
• Best practice details
• Examples and templates
• Domain knowledge

Organization:

• One topic per file
• Descriptive filenames
• 150-500 lines each
• Clear navigation from entry point

Avoid Duplication:

• Information lives in ONE place
• Entry point has summary
• Reference has detail
• Never copy-paste between them

Large Files (>10k words): Include grep patterns in SKILL.md:

Search `references/api_docs.md` for specific endpoints:
- "POST /users" - User creation
- "GET /users/:id" - User retrieval
- "PUT /users/:id" - User updates

Assets Best Practices

Content That Belongs in Assets:

• Templates for output
• Images and icons
• Fonts and typography
• Boilerplate code
• Sample documents
• Binary resources

Organization:

• Group by type or purpose
• Descriptive directory names
• Include README if structure is complex

Documentation in SKILL.md:

Copy `assets/frontend-template/` as starting point for new web applications.

The template includes:
- index.html - Main HTML structure
- styles.css - Base styling
- app.js - JavaScript framework setup

Quality Standards

Completeness Checklist

Before considering a skill complete:

• [ ] YAML frontmatter includes required fields (name, description)
• [ ] Description clearly states purpose and activation conditions
• [ ] All planned scripts implemented and documented
• [ ] All reference files created with clear purpose
• [ ] All assets included and referenced
• [ ] Entry point uses imperative voice throughout
• [ ] Navigation section links to all references
• [ ] No content duplication between entry and references
• [ ] Examples provided for complex workflows
• [ ] Red flags section warns about common mistakes
• [ ] Integration with other skills documented

Progressive Disclosure Checklist

For skills using progressive disclosure:

• [ ] Progressive disclosure frontmatter added
• [ ] Entry point reduced to <200 lines (optimal: 140-160)
• [ ] 3-5 reference files created
• [ ] Each reference 150-500 lines
• [ ] Clear navigation with descriptions
• [ ] No duplicated content
• [ ] Descriptive reference filenames
• [ ] References organized by logical topics

Validation and Testing

Automated Validation: Use packaging script to validate:

scripts/package_skill.py <path/to/skill-folder>

Checks:

• YAML frontmatter format
• Required fields present
• File structure correct
• References exist

Manual Testing: 1. Use the skill on realistic tasks 2. Note any confusion or missing information 3. Iterate based on feedback 4. Repeat until smooth execution

Common Anti-Patterns

❌ Anti-Pattern 1: Overly Detailed Entry Point

Problem: Entry point becomes monolithic reference manual

Example:

# My Skill

## Step 1: Do This
[300 lines of detailed instructions]

## Step 2: Do That
[400 lines of detailed instructions]

Fix: Move details to references

# My Skill

## Quick Start
1. First phase - See [workflow.md](./references/workflow.md) for details
2. Second phase - See [implementation.md](./references/implementation.md)

❌ Anti-Pattern 2: Unclear Activation Conditions

Problem: Claude doesn't know when to use the skill

Example:

description: Helps with stuff

Fix: Specific activation conditions

description: Creates database migration scripts. Use when user requests schema changes, table creation, or data migration for PostgreSQL or MySQL databases.

❌ Anti-Pattern 3: Second-Person Voice

Problem: Violates imperative voice requirement

Example:

You should first load the reference file, then you can start implementing.

Fix: Imperative voice

Load the reference file before implementing.

❌ Anti-Pattern 4: Duplicated Content

Problem: Same information in multiple places

Example:

SKILL.md: "The API requires authentication via OAuth 2.0..."
references/api.md: "The API requires authentication via OAuth 2.0..."

Fix: Summary in entry, detail in reference

SKILL.md: "API uses OAuth 2.0 - see references/api.md for details"
references/api.md: [Complete OAuth 2.0 implementation guide]

❌ Anti-Pattern 5: Missing Navigation

Problem: References exist but aren't mentioned in entry point

Fix: Explicit navigation section

## Navigation

- **[API Reference](./references/api.md)** - Complete API documentation
- **[Examples](./references/examples.md)** - Sample implementations

❌ Anti-Pattern 6: Unused Resources

Problem: Example files from init script left in skill

Fix: Delete unused directories and files

rm -rf scripts/ references/ assets/  # If not needed

Naming Conventions

Skill Names

• kebab-case
• Descriptive and specific
• Avoid generic terms
• Examples: pdf-editor, brand-guidelines, mcp-builder

Reference Filenames

• kebab-case
• Indicate content clearly
• Group related content
• Examples: workflow.md, best-practices.md, api-reference.md

Script Names

• snake_case for Python
• kebab-case for Bash
• Clear purpose
• Examples: rotate_pdf.py, init-skill.sh

Asset Names

• Descriptive
• Include type/purpose
• Examples: logo.png, template.html, boilerplate/

Maintenance Best Practices

Version Control

• Track skills in git
• Commit after each iteration
• Tag major versions
• Include changelog

Documentation Updates

• Update as skill evolves
• Keep examples current
• Remove outdated information
• Test documented workflows

User Feedback

• Collect usage feedback
• Track common issues
• Iterate based on patterns
• Improve clarity continuously

Meta-Skill Considerations

For skills that teach skill creation (like this one):

Demonstrate Your Own Teachings:

• Apply patterns you recommend
• Use structure you advocate
• Follow guidelines you establish
• Be the example

Reference Recent Work:

• Cite recently optimized skills
• Show before/after examples
• Demonstrate real improvements
• Prove effectiveness

Stay Current:

• Update as patterns evolve
• Incorporate new best practices
• Refine based on experience
• Lead by example

This skill-creator skill exemplifies progressive disclosure by:

• Entry point <200 lines
• 5 well-organized references
• Clear navigation
• No content duplication
• Imperative voice throughout
• Recent examples (mcp-builder, testing-anti-patterns)

Skill Creation Workflow

Complete Six-Step Process

Follow this workflow in order, skipping steps only when there is a clear reason they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

When to skip: Only when the skill's usage patterns are already clearly understood.

Purpose: Create effective skills by understanding concrete examples of how the skill will be used.

Approach

Understanding can come from: 1. Direct user examples - User provides real scenarios 2. Generated examples - Create scenarios validated with user feedback

Discovery Questions

Ask targeted questions to understand the skill's scope and usage:

For an image-editor skill example:

• "What functionality should the image-editor skill support? Editing, rotating, anything else?"
• "Can you give some examples of how this skill would be used?"
• "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
• "What would a user say that should trigger this skill?"

General discovery questions:

• What tasks will this skill help accomplish?
• Can you provide 3-5 realistic examples of skill usage?
• What keywords or phrases should activate this skill?
• What are the expected inputs and outputs?
• What domain knowledge is required?
• What constraints or limitations exist?

Best Practices

• Avoid overwhelming users - Don't ask too many questions in a single message
• Start with critical questions - Ask the most important questions first
• Follow up strategically - Add detail questions based on initial answers
• Validate understanding - Summarize back to confirm comprehension
• Collect edge cases - Ask about unusual or complex scenarios

Completion Criteria

Conclude this step when you have:

• Clear sense of functionality the skill should support
• 3-5 concrete usage examples
• Understanding of activation conditions
• Knowledge of expected inputs/outputs
• Awareness of edge cases and constraints

Step 2: Planning the Reusable Skill Contents

Purpose: Transform concrete examples into practical skill components.

Analysis Process

For each concrete example, analyze by:

1. Consider execution from scratch - How would Claude accomplish this without the skill? 2. Identify reusable components - What scripts, references, and assets would make repeated execution easier? 3. Determine component types - Classify as script, reference, or asset

Example Analyses

Example 1: PDF Editor Skill

Query: "Help me rotate this PDF"

Analysis: 1. Rotating a PDF requires re-writing the same code each time 2. A scripts/rotate_pdf.py script would eliminate repeated code writing 3. Component: Script

Example 2: Frontend Webapp Builder Skill

Queries: "Build me a todo app", "Build me a dashboard to track my steps"

Analysis: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An assets/hello-world/ template containing boilerplate project files would provide a starting point 3. Component: Asset (template)

Example 3: BigQuery Skill

Query: "How many users have logged in today?"

Analysis: 1. Querying BigQuery requires re-discovering table schemas and relationships each time 2. A references/schema.md file documenting table schemas would provide persistent knowledge 3. Component: Reference

Example 4: Brand Guidelines Skill

Query: "Create a presentation following our brand guidelines"

Analysis: 1. Brand guidelines include colors, fonts, logo usage rules 2. Components needed:

• references/brand-guidelines.md - Style rules and usage
• assets/logo.png - Logo file for use in outputs
• assets/fonts/ - Brand fonts

3. Components: Reference + Assets

Component Classification

Create a Script when:

• Same code is repeatedly rewritten
• Deterministic execution is critical
• Complex algorithm needs testing
• Performance optimization matters
• External tools need consistent invocation

Create a Reference when:

• Domain knowledge varies by project
• Specifications are detailed/complex
• Workflows have many steps
• API documentation is needed
• Schemas or data structures must be referenced
• Policies or guidelines exist

Create an Asset when:

• Templates accelerate creation
• Binary files are needed (images, fonts)
• Boilerplate code structures exist
• Starting points reduce repetition
• Consistent styling/branding required

Deliverable

Create a structured list of reusable resources:

Scripts:
- scripts/rotate_pdf.py - Rotate PDF files
- scripts/optimize_image.py - Compress and optimize images

References:
- references/schema.md - Database table schemas
- references/api_docs.md - API endpoint specifications
- references/workflow.md - Detailed process steps

Assets:
- assets/template.html - Boilerplate HTML structure
- assets/logo.png - Company logo
- assets/fonts/ - Brand typography

Step 3: Initializing the Skill

When to skip: Skill already exists and needs iteration or packaging only.

Purpose: Generate proper skill directory structure with templates.

Using init_skill.py

Always use the initialization script for new skills:

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

Example:

scripts/init_skill.py pdf-editor --path ./custom-skills/

What the Script Creates

The initialization script:

• Creates skill directory at specified path
• Generates SKILL.md template with proper frontmatter
• Includes TODO placeholders for customization
• Creates example resource directories: scripts/, references/, assets/
• Adds example files demonstrating structure

Generated Structure

skill-name/
├── SKILL.md                           # Template with TODOs
├── scripts/
│   └── example_script.py             # Example script (customize or delete)
├── references/
│   └── example_reference.md          # Example reference (customize or delete)
└── assets/
    └── example_asset.txt             # Example asset (customize or delete)

Next Steps

After initialization: 1. Review generated SKILL.md template 2. Customize or delete example files 3. Begin implementing planned components (Step 4)

Step 4: Edit the Skill

Purpose: Implement the skill for another Claude instance to use.

Mindset: Focus on information beneficial and non-obvious to Claude. Include procedural knowledge, domain-specific details, and reusable assets.

Phase A: Implement Reusable Resources First

Start with the resources identified in Step 2 (scripts, references, assets).

Implementation Order

1. Scripts - Implement executable code first 2. References - Create documentation files 3. Assets - Add templates and resources

User Input Considerations

Some resources may require user input:

• Brand guidelines skill - User provides brand assets, documentation
• Database skill - User provides schemas, connection details
• API integration skill - User provides API documentation, credentials format

Ask for needed materials before implementation.

Clean Up Examples

Delete example files and directories not needed:

• The init script creates example files to demonstrate structure
• Most skills won't need all of scripts/, references/, and assets/
• Remove unused directories to keep skill clean

Phase B: Update SKILL.md

Writing Style Requirements

MANDATORY: Use imperative/infinitive form (verb-first instructions), not second person.

✅ Correct:

• "To accomplish X, do Y"
• "Follow these steps to complete the task"
• "Load the reference file when needed"

❌ Incorrect:

• "You should do X"
• "If you need to do X"
• "You can find this in..."

Rationale: Maintains consistency and clarity for AI consumption.

Progressive Disclosure Structure

For skills expected to exceed 150 lines, implement progressive disclosure:

Entry Point Content (SKILL.md):

• Overview (2-3 sentences)
• When to Use This Skill
• The Iron Law (if applicable)
• Core Principles (brief)
• Quick Start (workflow summary)
• Navigation (links to references)
• Key Reminders
• Red Flags - STOP
• Integration with Other Skills
• Real-World Impact (if applicable)

Target: 140-160 lines for entry point

Reference Content:

• Detailed specifications
• Step-by-step workflows
• Technical implementation guides
• Examples and templates
• Best practices
• Advanced patterns

Target: 150-500 lines per reference file, 3-5 files

Core Questions to Answer

Complete SKILL.md by answering:

1. What is the purpose of the skill, in a few sentences?

• Clear, concise overview
• Key capabilities
• Primary use cases

2. When should the skill be used?

• Specific activation conditions
• Keywords or scenarios that trigger skill
• When NOT to use the skill

3. In practice, how should Claude use the skill?

• Reference all scripts, references, and assets
• Explain when to load each resource
• Provide workflow guidance
• Include navigation to detailed content

Reference Integration

Ensure SKILL.md references all reusable resources:

Scripts:

Execute `scripts/rotate_pdf.py <input.pdf> <output.pdf> <degrees>` to rotate PDFs.

References:

Load `references/schema.md` to understand database structure before writing queries.

Assets:

Copy `assets/frontend-template/` as starting point for new web applications.

Quality Checklist

• [ ] Imperative form throughout
• [ ] All resources referenced with usage instructions
• [ ] Clear activation conditions
• [ ] Navigation to detailed references
• [ ] No duplicated content between entry and references
• [ ] Progressive disclosure frontmatter (if applicable)
• [ ] Entry point <200 lines (optimal: 140-160)

Step 5: Packaging a Skill

Purpose: Validate and create distributable zip file for sharing.

Packaging Command

scripts/package_skill.py <path/to/skill-folder>

Optional output directory:

scripts/package_skill.py <path/to/skill-folder> ./dist

Automatic Validation

The packaging script automatically validates before packaging:

Validation Checks:

• YAML frontmatter format and required fields
• Skill naming conventions and directory structure
• Description completeness and quality
• File organization and resource references
• Progressive disclosure metadata (if present)

Packaging Process

If validation passes, the script: 1. Creates zip file named after the skill (e.g., my-skill.zip) 2. Includes all files from skill directory 3. Maintains proper directory structure 4. Prepares for distribution

Handling Validation Errors

If validation fails: 1. Script reports specific errors 2. Exits without creating package 3. Fix reported errors 4. Run packaging command again

Common validation issues:

• Missing required frontmatter fields
• Invalid YAML syntax
• Poor description quality
• Incorrect directory structure
• Referenced files don't exist

Distribution

After successful packaging:

• Share the .zip file with users
• Users can install via Claude MPM
• Skill becomes available in their Claude instance

Step 6: Iterate

Purpose: Refine skill based on real-world usage and feedback.

When Iteration Happens

Most often immediately after using the skill:

• Fresh context of how the skill performed
• Specific examples of struggles or inefficiencies
• Clear understanding of what needs improvement

Iteration Workflow

1. Use the skill on real tasks

• Apply to actual work scenarios
• Note difficulties and inefficiencies
• Observe where Claude struggles

2. Notice struggles or inefficiencies

• Unclear instructions
• Missing information
• Awkward workflows
• Insufficient examples
• Missing resources

3. Identify how to update skill

• What SKILL.md sections need clarification?
• What references should be added or expanded?
• What scripts would eliminate repeated work?
• What assets would accelerate tasks?

4. Implement changes

• Update SKILL.md
• Add/modify references
• Create new scripts or assets
• Improve navigation

5. Test again

• Use on similar tasks
• Verify improvements
• Continue iterating

Common Iteration Patterns

Add Missing Context:

• Skill assumes knowledge user doesn't have
• Add reference file with background information

Clarify Workflow:

• Steps are ambiguous or incomplete
• Expand Quick Start or create detailed workflow reference

Automate Repetition:

• Same code written multiple times
• Create script for repeated operations

Provide Templates:

• Starting from scratch repeatedly
• Add asset templates

Improve Navigation:

• Can't find relevant information
• Better organize references
• Add clearer signposting

Iteration Best Practices

• Iterate quickly - Don't wait for perfect; improve incrementally
• Test with real tasks - Synthetic examples miss real-world complexity
• Get user feedback - They reveal blindspots
• Track patterns - Multiple similar struggles indicate structural issues
• Balance detail - More isn't always better; clarity matters

When to Stop Iterating

A skill is mature when:

• Consistently accomplishes intended tasks
• No repeated struggles or inefficiencies
• Clear activation and usage patterns
• Well-organized and navigable
• Positive user feedback

Remember: Skills are living documents. Return to iterate as needs evolve.

Skill Creation Examples

Complete Skill Examples

This reference provides real-world examples of well-crafted skills demonstrating various patterns and approaches.

Example 1: mcp-builder (Progressive Disclosure)

Overview

Purpose: Build high-quality MCP servers for LLM integration

Challenge: Complex topic with multiple implementation languages, extensive best practices, and detailed workflows

Solution: Progressive disclosure with 6 reference files

Structure

mcp-builder/
├── SKILL.md (160 lines)
└── references/
    ├── design_principles.md - Agent-centric design philosophy
    ├── workflow.md - 4-phase development process
    ├── mcp_best_practices.md - Universal MCP guidelines
    ├── python_mcp_server.md - Python implementation patterns
    ├── node_mcp_server.md - TypeScript implementation patterns
    └── evaluation.md - Testing and iteration

Entry Point (SKILL.md)

Frontmatter:

---
name: mcp-builder
description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).
progressive_disclosure:
  entry_point:
    summary: "Build agent-friendly MCP servers through research-driven design, thoughtful implementation, and evaluation-based iteration"
    when_to_use: "When integrating external APIs/services via MCP protocol. Prioritize agent workflows over API wrappers, optimize for context efficiency, design actionable errors."
    quick_start: "1. Research protocol & API docs 2. Plan agent-centric tools 3. Implement with validation 4. Create evaluations 5. Iterate based on agent feedback"
  references:
    - design_principles.md
    - workflow.md
    - mcp_best_practices.md
    - python_mcp_server.md
    - node_mcp_server.md
    - evaluation.md
---

Key Sections:

• The Iron Law - "Design for agents, not humans"
• Core Principles - 5 essential guidelines
• Quick Start - 4-phase workflow with reference links
• Navigation - Annotated list of all 6 references
• Red Flags - Warning signs to stop and reconsider

What Makes It Effective:

• Clear activation conditions in description
• Strong Iron Law sets philosophy
• Quick start maps to detailed workflow reference
• Navigation explains when to load each reference
• 160 lines = 23% reduction from original 209

Reference Organization

By Topic and Phase: 1. design_principles.md - Load FIRST before implementation 2. workflow.md - Complete 4-phase process with decision trees 3. mcp_best_practices.md - Universal guidelines (language-agnostic) 4. python_mcp_server.md - Load during Phase 2 for Python 5. node_mcp_server.md - Load during Phase 2 for TypeScript 6. evaluation.md - Load during Phase 4

Content Distribution:

• Entry: Core philosophy + quick start (160 lines)
• References: Deep implementation details (~2000 lines total)
• Total: ~2160 lines (vs 209 monolithic)
• Context saved: Load only what's needed for current language/phase

Example 2: testing-anti-patterns (Ultra-Lean Entry)

Overview

Purpose: Prevent common testing mistakes

Challenge: Multiple distinct anti-patterns, detection guidance, and TDD connection

Solution: Ultra-lean 140-line entry with 4 focused references

Structure

testing-anti-patterns/
├── SKILL.md (140 lines)
└── references/
    ├── core-anti-patterns.md - Patterns 1-3
    ├── completeness-anti-patterns.md - Patterns 4-5
    ├── detection-guide.md - Red flags and gates
    └── tdd-connection.md - Prevention through TDD

Entry Point (SKILL.md)

Frontmatter:

---
name: Testing Anti-Patterns
description: Never test mock behavior. Never add test-only methods to production classes. Understand dependencies before mocking.
when_to_use: when writing or changing tests, adding mocks, or tempted to add test-only methods to production code
progressive_disclosure:
  entry_point:
    summary: "Avoid testing mocks, test-only production methods, and incomplete mocking. Test real behavior, not mock behavior."
    when_to_use: "When writing tests, adding mocks, reviewing test failures, or tempted to add test-only methods to production code."
    quick_start: "1. Ask: 'Am I testing real behavior?' 2. Check: 'Is this method only for tests?' 3. Verify: 'Do I understand what I'm mocking?' 4. Confirm: 'Is my mock complete?' 5. Apply: TDD prevents these patterns"
  references:
    - core-anti-patterns.md
    - completeness-anti-patterns.md
    - detection-guide.md
    - tdd-connection.md
---

Key Sections:

• The Iron Laws - 5 non-negotiable rules
• Core Anti-Pattern Categories - Brief summary + link to details
• Quick Detection Checklist - Runnable checklist
• The Bottom Line - Core philosophy
• Navigation - 4 references with clear purposes

What Makes It Effective:

• Extremely focused entry point (140 lines)
• Iron Laws immediately establish boundaries
• Quick checklist provides instant value
• Entry point alone prevents most anti-patterns
• Deep dive available in references for learning

Reference Organization

By Anti-Pattern Category: 1. core-anti-patterns.md - Patterns 1-3 (testing mocks, test-only methods, uninformed mocking) 2. completeness-anti-patterns.md - Patterns 4-5 (incomplete mocks, tests as afterthought)

By Function: 3. detection-guide.md - How to spot these patterns 4. tdd-connection.md - How TDD prevents them

Content Distribution:

• Entry: Iron Laws + quick checklist (140 lines)
• References: Detailed analysis + examples (~800 lines total)
• Optimal for quick reference with depth available

Example 3: PDF Editor (Simple Skill with Scripts)

Overview

Purpose: Rotate, merge, and manipulate PDF files

Challenge: Repetitive code for PDF operations

Solution: Python scripts for common operations

Structure

pdf-editor/
├── SKILL.md (80 lines)
└── scripts/
    ├── rotate_pdf.py
    ├── merge_pdfs.py
    └── split_pdf.py

Entry Point (SKILL.md)

---
name: pdf-editor
description: Rotate, merge, split, and manipulate PDF files. Use when users need to perform PDF operations like rotation, combining multiple PDFs, or extracting pages.
---

# PDF Editor

## Overview

Provides scripts for common PDF operations: rotation, merging, splitting, and page extraction.

## When to Use This Skill

- User requests PDF rotation
- Multiple PDFs need combining
- PDF pages need extraction
- PDF operations need to be reliable and fast

## Available Operations

### Rotate PDF
Execute `scripts/rotate_pdf.py <input.pdf> <output.pdf> <degrees>` to rotate PDFs.

Parameters:
- input.pdf: Source PDF file
- output.pdf: Destination file path
- degrees: Rotation angle (90, 180, 270)

Example:

scripts/rotate_pdf.py document.pdf rotated.pdf 90

### Merge PDFs
Execute `scripts/merge_pdfs.py <output.pdf> <input1.pdf> <input2.pdf> ...` to combine PDFs.

### Split PDF
Execute `scripts/split_pdf.py <input.pdf> <page_number>` to split PDF at specific page.

What Makes It Effective:

• Simple 80-line skill (no progressive disclosure needed)
• Scripts eliminate repetitive code writing
• Clear usage documentation
• Focused on common operations

Why Scripts?

Without skill:

• User: "Rotate this PDF 90 degrees"
• Claude: Writes PDF rotation code from scratch (50+ lines)
• Code may have bugs, needs testing
• Same code rewritten for each request

With skill:

• User: "Rotate this PDF 90 degrees"
• Claude: Executes scripts/rotate_pdf.py document.pdf rotated.pdf 90
• Pre-tested, reliable code
• Instant execution

Example 4: Brand Guidelines (Reference + Assets)

Overview

Purpose: Ensure consistent brand application

Challenge: Brand rules, color codes, fonts, logo files

Solution: Reference documentation + asset files

Structure

brand-guidelines/
├── SKILL.md (90 lines)
├── references/
│   └── brand-standards.md
└── assets/
    ├── logo-primary.png
    ├── logo-white.png
    ├── logo-black.png
    ├── fonts/
    │   ├── BrandFont-Regular.ttf
    │   └── BrandFont-Bold.ttf
    └── color-palette.png

Entry Point (SKILL.md)

---
name: brand-guidelines
description: Apply company brand guidelines to documents, presentations, and marketing materials. Use when creating customer-facing content that must match brand standards.
---

# Brand Guidelines

## Overview

Ensures all customer-facing content follows company brand standards including colors, fonts, logo usage, and tone of voice.

## When to Use This Skill

- Creating presentations, documents, or marketing materials
- User mentions "brand guidelines" or "brand standards"
- Customer-facing content needs consistency
- Logo placement or usage questions

## Brand Assets

### Logos
Available in `assets/`:
- `logo-primary.png` - Full color logo (primary use)
- `logo-white.png` - White logo (dark backgrounds)
- `logo-black.png` - Black logo (print, grayscale)

### Fonts
Brand fonts in `assets/fonts/`:
- BrandFont-Regular.ttf (body text)
- BrandFont-Bold.ttf (headers)

### Color Palette
Reference `assets/color-palette.png` for official brand colors.

## Detailed Standards

Load `references/brand-standards.md` for:
- Complete color codes (HEX, RGB, CMYK)
- Logo usage rules and clearspace
- Typography hierarchy and sizing
- Tone of voice guidelines
- Do's and don'ts

Reference Content (brand-standards.md)

# Brand Standards Reference

## Color Palette

### Primary Colors
- Brand Blue: #0066CC (RGB: 0, 102, 204)
- Brand White: #FFFFFF
- Brand Black: #1A1A1A

### Secondary Colors
- Accent Orange: #FF6600
- Neutral Gray: #7F7F7F

### Usage
- Brand Blue: Primary CTA buttons, headers
- Accent Orange: Highlights, secondary CTAs
- Neutral Gray: Body text, borders

## Logo Usage

### Clearspace
Maintain minimum clearspace equal to height of "M" in logo around all sides.

### Minimum Size
- Digital: 120px width minimum
- Print: 1 inch width minimum

### Do's
- Use provided logo files
- Maintain aspect ratio
- Place on solid backgrounds

### Don'ts
- Never stretch or distort
- Never add effects or shadows
- Never change colors
- Never place on busy backgrounds

[... additional sections ...]

What Makes It Effective:

• Assets provide ready-to-use brand files
• Reference contains detailed specifications
• Entry point explains what's available
• Claude can apply standards without asking user
• Ensures brand consistency

Example 5: Database Query Builder (References)

Overview

Purpose: Write safe, efficient database queries

Challenge: Complex schema, multiple tables, relationships

Solution: Schema documentation in references

Structure

database-query-builder/
├── SKILL.md (120 lines)
└── references/
    ├── schema.md - Table structures and relationships
    ├── query-patterns.md - Common query templates
    └── optimization.md - Performance best practices

Entry Point (SKILL.md)

---
name: database-query-builder
description: Write safe, efficient database queries for the company PostgreSQL database. Use when user requests data analysis, reporting, or needs to query customer, order, or product tables.
---

# Database Query Builder

## Overview

Provides schema documentation and query patterns for safe, efficient database access.

## When to Use This Skill

- User requests data from database
- Analytics or reporting queries needed
- Mentions customer, order, product, or inventory data
- Data export or analysis tasks

## Query Process

1. Load `references/schema.md` to understand table structure
2. Identify required tables and relationships
3. Review `references/query-patterns.md` for similar queries
4. Write query using best practices from `references/optimization.md`
5. Use parameterized queries (never string concatenation)

## Key Reminders

- Always use parameterized queries for safety
- Include LIMIT clauses for exploratory queries
- Join tables efficiently (use indexes)
- Test queries on small data sets first

## Navigation

- **[Schema Reference](./references/schema.md)** - Complete table structures, columns, relationships, indexes
- **[Query Patterns](./references/query-patterns.md)** - Common query templates and examples
- **[Optimization Guide](./references/optimization.md)** - Performance best practices and anti-patterns

Reference Content (schema.md)

# Database Schema Reference

## Customers Table

CREATE TABLE customers ( id SERIAL PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, name VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW() );

CREATE INDEX idx_customers_email ON customers(email);

**Columns:**
- `id` - Primary key, auto-increment
- `email` - Unique customer email
- `name` - Customer full name
- `created_at` - Account creation timestamp
- `updated_at` - Last update timestamp

**Relationships:**
- `orders.customer_id` → `customers.id` (one-to-many)

## Orders Table

[... additional tables ...]

## Common Queries

Search for specific queries in this file:
- "customer email lookup" - Find customer by email
- "order history" - Get customer's order history
- "revenue by month" - Monthly revenue aggregation

What Makes It Effective:

• Schema reference keeps detailed table structures
• Claude loads schema before writing queries
• Prevents SQL injection via parameterization requirement
• Query patterns provide starting points
• Grep search patterns for large schema files

Example 6: Frontend Webapp Builder (Assets)

Overview

Purpose: Build web applications quickly

Challenge: Same boilerplate code for each app

Solution: Template assets with boilerplate code

Structure

frontend-webapp-builder/
├── SKILL.md (100 lines)
└── assets/
    ├── vanilla-template/
    │   ├── index.html
    │   ├── styles.css
    │   └── app.js
    └── react-template/
        ├── package.json
        ├── public/
        └── src/
            ├── App.jsx
            ├── index.jsx
            └── styles.css

Entry Point (SKILL.md)

---
name: frontend-webapp-builder
description: Build frontend web applications using vanilla JavaScript or React. Use when user requests a web app, dashboard, or interactive webpage.
---

# Frontend Webapp Builder

## Overview

Provides boilerplate templates for rapid web application development.

## When to Use This Skill

- User requests a web app or dashboard
- Interactive webpage needed
- Frontend prototype required
- Quick demo or proof-of-concept

## Available Templates

### Vanilla JavaScript Template
Copy `assets/vanilla-template/` for simple, dependency-free apps.

Includes:
- `index.html` - Semantic HTML5 structure
- `styles.css` - Modern CSS with CSS Grid and Flexbox
- `app.js` - Clean JavaScript with module pattern

Best for: Simple apps, quick demos, no build step needed

### React Template
Copy `assets/react-template/` for complex, stateful applications.

Includes:
- Full React setup with hooks
- Component structure
- Modern build configuration
- Development server ready

Best for: Complex state management, reusable components, larger apps

## Development Workflow

1. Copy appropriate template
2. Customize HTML/JSX structure
3. Add application-specific logic
4. Style with CSS/styled-components
5. Test in browser

What Makes It Effective:

• Asset templates eliminate boilerplate writing
• Two options for different complexity levels
• Ready-to-run code
• Claude customizes rather than creates from scratch
• Faster development, fewer errors

Pattern Summary

When to Use Each Approach

Scripts:

• Repetitive code operations
• Need deterministic execution
• Complex algorithms
• Example: PDF operations, file conversions

References:

• Detailed specifications
• Domain knowledge
• Multi-step workflows
• Example: API docs, database schemas, processes

Assets:

• Templates and boilerplate
• Binary files (images, fonts)
• Starting point code
• Example: Project templates, brand resources

Progressive Disclosure:

• Skill >150 lines
• Multiple distinct topics
• Complex workflows
• Example: Technical guides, multi-phase processes

Structure Selection Guide

Simple Skill (<150 lines):

• Single SKILL.md
• Maybe scripts or assets
• No progressive disclosure needed

Medium Skill (150-300 lines):

• SKILL.md entry point (150-160 lines)
• 2-3 reference files
• Progressive disclosure recommended

Complex Skill (300+ lines if monolithic):

• SKILL.md entry point (140-160 lines)
• 4-6 reference files
• Progressive disclosure required

Key Takeaways

1. Match structure to content - Use references for documentation, scripts for code, assets for templates 2. Apply progressive disclosure - Keep entry point lean, move details to references 3. Demonstrate your teachings - Meta-skills should exemplify their patterns 4. Reference recent work - Show real examples of successful skills 5. Organize logically - Group by topic, phase, or function 6. Document clearly - Explain when to load each resource 7. Avoid duplication - Information lives in one place 8. Test with real tasks - Ensure skill actually helps Claude

Progressive Disclosure Pattern for Skills

What is Progressive Disclosure?

Progressive disclosure is a design pattern that reveals information progressively, starting with the essential and expanding to detail as needed. For skills, it means organizing content into layers that Claude loads based on task complexity.

Core principle: Don't load what you don't need. Start simple, go deep when required.

Why Progressive Disclosure?

The Context Window Problem

Claude has a limited context window. Every token counts. Traditional monolithic skills load ALL content when activated, consuming precious context even for simple tasks.

Without progressive disclosure:

User: "Create a simple skill for tracking todos"
Claude loads: 209 lines of skill-creator content
Claude needs: Maybe 40 lines for this simple case
Wasted: 169 lines of context (80%)

With progressive disclosure:

User: "Create a simple skill for tracking todos"
Claude loads: 150 lines of entry point
Claude identifies: Needs basic structure only
Claude loads: skill-structure.md (additional 200 lines)
Total: 350 lines
Context saved: Didn't load workflow details, examples, best practices (600+ lines)

Benefits

1. Efficient Context Usage - Load only what's needed for current task 2. Faster Comprehension - Entry point provides quick orientation 3. Scalable Depth - Can have unlimited detail without bloating entry 4. Better Organization - Related content grouped logically 5. Easier Maintenance - Update specific references without touching entry 6. Clearer Navigation - Explicit signposting to deeper content

Three-Level Architecture

Skills using progressive disclosure operate on three levels:

Level 1: Metadata (Always Loaded)

Content: YAML frontmatter

• name: - Skill identifier
• description: - Purpose and activation conditions
• progressive_disclosure: - Navigation metadata

Size: ~100-200 words

Purpose: Determine if skill should activate

Example:

---
name: mcp-builder
description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).
progressive_disclosure:
  entry_point:
    summary: "Build agent-friendly MCP servers through research-driven design"
    when_to_use: "When integrating external APIs/services via MCP protocol"
    quick_start: "1. Research 2. Plan 3. Implement 4. Evaluate 5. Iterate"
  references:
    - design_principles.md
    - workflow.md

Level 2: Entry Point (Loaded on Activation)

Content: SKILL.md body

• Overview
• When to Use
• Core Principles (brief)
• Quick Start
• Navigation to references
• Key reminders and warnings

Size: 140-160 lines (optimal), <200 lines (maximum)

Purpose: Orient Claude to skill's approach and provide quick start

What to Include:

• Essential workflow overview
• Activation conditions
• Core principles (summary)
• Critical warnings
• Navigation to detailed references

What to Exclude:

• Detailed step-by-step procedures (→ workflow reference)
• Complete specifications (→ technical reference)
• Extensive examples (→ examples reference)
• Best practice details (→ best practices reference)
• Advanced patterns (→ advanced reference)

Level 3: References (Loaded as Needed)

Content: Reference files in references/ directory

• Detailed workflows
• Technical specifications
• Examples and templates
• Best practices
• Advanced patterns

Size: 150-500 lines per file, 3-5 files typical

Purpose: Provide deep detail when Claude determines it's needed

Organization Patterns:

• By topic (design, workflow, evaluation)
• By role (developer, designer, architect)
• By phase (planning, implementation, testing)
• By complexity (basics, intermediate, advanced)

Implementing Progressive Disclosure

Step 1: Analyze Current Skill

Review existing skill to identify:

1. Essential content - Needed for every task 2. Conditional content - Needed for specific scenarios 3. Reference content - Looked up as needed 4. Natural boundaries - Topic divisions

Analysis questions:

• What must Claude know immediately?
• What can wait until needed?
• What topics cluster together?
• Where are natural section breaks?

Step 2: Plan Reference Organization

Design 3-5 reference files based on:

• Topic clustering
• Usage patterns
• Content size balance
• Logical flow

Common reference patterns:

Technical Skills:

• structure.md - Architecture and components
• workflow.md - Step-by-step processes
• best-practices.md - Quality guidelines
• examples.md - Templates and samples

Domain Skills:

• fundamentals.md - Core concepts
• procedures.md - Standard workflows
• reference-data.md - Schemas, APIs, specs
• advanced.md - Complex scenarios

Tool Integration Skills:

• getting-started.md - Setup and basics
• api-reference.md - Complete API docs
• patterns.md - Common usage patterns
• troubleshooting.md - Error handling

Step 3: Add Progressive Disclosure Frontmatter

Add to YAML frontmatter:

progressive_disclosure:
  entry_point:
    summary: "One-sentence core workflow description"
    when_to_use: "Specific activation conditions and key priorities"
    quick_start: "5-step numbered workflow (1. First 2. Second ...)"
  references:
    - first-reference.md
    - second-reference.md
    - third-reference.md

Guidelines:

• summary: - One sentence, focus on outcome
• when_to_use: - Clear conditions, priorities, key principles
• quick_start: - Exactly 5 numbered steps
• references: - List in logical reading order

Step 4: Refactor Entry Point

Reduce entry point to 140-160 lines by:

Keep in Entry Point:

• Overview (2-3 sentences)
• When to Use (clear activation)
• The Iron Law (if applicable)
• Core Principles (3-5 brief points)
• Quick Start (high-level workflow)
• Navigation (links to all references with descriptions)
• Key Reminders (critical points)
• Red Flags (stop conditions)
• Integration with Other Skills
• Real-World Impact (if applicable)

Move to References:

• Detailed step-by-step workflows → workflow.md
• Complete specifications → structure.md or technical reference
• Extensive examples → examples.md
• Best practice details → best-practices.md
• Advanced patterns → advanced.md

Writing tips:

• Each section: 5-15 lines maximum
• Use bullet points for scannability
• Link to references with context
• Avoid duplicating reference content

Step 5: Create Reference Files

For each reference file:

Header:

# Reference Topic Name

## Purpose

Brief description of what this reference covers and when to use it.

Content organization:

• Clear section headers
• Logical progression
• Self-contained (can be read independently)
• Cross-references to other references when needed

Size targets:

• Minimum: 150 lines (or combine with another reference)
• Optimal: 200-400 lines
• Maximum: 500 lines (consider splitting if larger)

Step 6: Add Navigation

In entry point, create clear navigation:

## Navigation

### Core Workflow
- **[🔄 Complete Workflow](./references/workflow.md)** - Detailed step-by-step process with decision trees and examples. Load when executing the full workflow.

### Technical Details
- **[🏗️ Skill Structure](./references/structure.md)** - Component architecture, file organization, and requirements. Load when designing skill layout.

### Implementation Guidance
- **[✅ Best Practices](./references/best-practices.md)** - Quality guidelines, patterns, and anti-patterns. Load when implementing or reviewing.

### Examples and Templates
- **[📚 Examples](./references/examples.md)** - Complete skill examples and templates. Load when starting new skill or seeking inspiration.

Navigation best practices:

• Use emoji for visual scanning
• Include brief description of content
• Mention when to load
• Group related references
• Order by typical usage flow

Real-World Examples

Example 1: mcp-builder (209 → 160 lines)

Before: Monolithic 209-line SKILL.md

After: Progressive disclosure with 6 references

• Entry: 160 lines (23% reduction)
• design_principles.md - Agent-centric design philosophy
• workflow.md - 4-phase development process
• mcp_best_practices.md - Universal MCP guidelines
• python_mcp_server.md - Python implementation patterns
• node_mcp_server.md - TypeScript implementation patterns
• evaluation.md - Testing and iteration

Impact:

• Simple tasks load 160 lines (vs 209)
• Complex tasks load ~600 lines total (entry + relevant references)
• Clear separation by concern
• Easier to maintain and update

Example 2: testing-anti-patterns (Long → 140 lines)

Before: Lengthy monolithic content

After: Progressive disclosure with 4 references

• Entry: 140 lines (optimal size)
• core-anti-patterns.md - Patterns 1-3
• completeness-anti-patterns.md - Patterns 4-5
• detection-guide.md - Red flags and gates
• tdd-connection.md - Prevention through TDD

Impact:

• Ultra-lean entry point
• Deep detail available when needed
• Organized by anti-pattern category
• Easy to reference specific patterns

Example 3: skill-creator (This Skill!)

Before: Monolithic 209-line SKILL.md

After: Progressive disclosure with 5 references

• Entry: 150 lines (28% reduction)
• skill-structure.md - Architecture and components
• creation-workflow.md - 6-step process
• progressive-disclosure.md - This pattern guide
• best-practices.md - Quality and writing guidelines
• examples.md - Complete skill examples

Meta-insight: This skill demonstrates its own teachings by applying progressive disclosure!

Progressive Disclosure Anti-Patterns

❌ Anti-Pattern 1: Duplicated Content

Problem: Same information in entry point AND references

Example:

SKILL.md: "Follow these 5 steps: 1. Research 2. Plan ..."
workflow.md: "Step 1: Research. Step 2: Plan ..."

Fix: Entry has summary, reference has detail

SKILL.md: "5-phase workflow: Research → Plan → Implement → Test → Iterate"
workflow.md: "## Phase 1: Research\n\n1. Load protocol docs\n2. Study API ..."

❌ Anti-Pattern 2: Over-Fragmentation

Problem: Too many tiny reference files

Example:

• step1.md (50 lines)
• step2.md (60 lines)
• step3.md (55 lines)

Fix: Combine related content

workflow.md (250 lines with all steps)

❌ Anti-Pattern 3: Missing Navigation

Problem: References exist but entry point doesn't mention them

Fix: Explicit navigation section with descriptions

❌ Anti-Pattern 4: Bloated Entry Point

Problem: Entry point still >200 lines after "refactoring"

Fix: Move more content to references, keep only essentials in entry

❌ Anti-Pattern 5: Unclear Reference Purpose

Problem: Generic filenames, no description of content

Fix: Descriptive names, clear navigation descriptions

When NOT to Use Progressive Disclosure

Progressive disclosure adds organizational complexity. Skip it when:

1. Skill is simple - <150 lines total 2. Content doesn't subdivide - No natural topic boundaries 3. Always need everything - No conditional content 4. Single workflow - Linear process, no branching

Example skills that DON'T need progressive disclosure:

• Simple code formatters
• Basic file converters
• Trivial workflows
• Single-purpose tools

Success Metrics

A well-implemented progressive disclosure skill:

• ✅ Entry point: 140-160 lines (optimal) or <200 lines (maximum)
• ✅ 3-5 reference files
• ✅ Each reference: 150-500 lines
• ✅ Clear navigation with descriptions
• ✅ No content duplication
• ✅ Logical topic organization
• ✅ 20-30% reduction from original entry point
• ✅ Maintained or increased total depth
• ✅ Improved usability and discoverability

Implementation Checklist

Before claiming progressive disclosure is complete:

• [ ] Progressive disclosure frontmatter added to YAML
• [ ] Entry point reduced to <200 lines (optimal: 140-160)
• [ ] 3-5 reference files created
• [ ] Each reference 150-500 lines
• [ ] Clear navigation section in entry point
• [ ] No duplicated content between entry and references
• [ ] Descriptive reference filenames
• [ ] Each reference has clear purpose
• [ ] References organized by logical topics
• [ ] Cross-references added where needed
• [ ] All sections follow imperative voice
• [ ] Examples reference the pattern being taught (for meta-skills)

The Meta-Lesson

This very document demonstrates progressive disclosure:

Entry point (SKILL.md):

• What skills are
• Why create them
• Quick 6-step overview
• Navigation to details

This reference (progressive-disclosure.md):

• Deep dive into the pattern
• Implementation guide
• Anti-patterns
• Examples
• Best practices

Other references:

• Detailed workflow steps
• Skill structure specifications
• Examples and templates
• Quality guidelines

By organizing content this way, we practice what we preach.

Skill Structure and Anatomy

Complete Skill Architecture

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md Requirements

YAML Frontmatter (required)

The frontmatter metadata determines when Claude will activate and use the skill.

Required Fields:

• name: - Skill identifier (kebab-case)
• description: - Clear explanation of purpose and activation conditions

Metadata Quality Guidelines:

• Be specific about what the skill does and when to use it
• Use third-person voice (e.g., "This skill should be used when..." instead of "Use this skill when...")
• Include activation conditions in the description
• Mention key capabilities and constraints

Example:

---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---

Progressive Disclosure Frontmatter (recommended for skills >150 lines)

For skills using the progressive disclosure pattern, add structured metadata to guide Claude:

progressive_disclosure:
  entry_point:
    summary: "One-line description of core workflow"
    when_to_use: "Specific activation conditions and priorities"
    quick_start: "5-step workflow overview"
  references:
    - reference-file-1.md
    - reference-file-2.md

Example from mcp-builder:

progressive_disclosure:
  entry_point:
    summary: "Build agent-friendly MCP servers through research-driven design, thoughtful implementation, and evaluation-based iteration"
    when_to_use: "When integrating external APIs/services via MCP protocol. Prioritize agent workflows over API wrappers, optimize for context efficiency, design actionable errors."
    quick_start: "1. Research protocol & API docs 2. Plan agent-centric tools 3. Implement with validation 4. Create evaluations 5. Iterate based on agent feedback"
  references:
    - design_principles.md
    - workflow.md
    - mcp_best_practices.md

Markdown Body Content

Writing Style:

• Use imperative/infinitive form (verb-first instructions), not second person
• Write objective, instructional language
• Example: "To accomplish X, do Y" (not "You should do X")
• Maintain consistency and clarity for AI consumption

Recommended Sections for Entry Point: 1. Overview - What the skill provides (2-3 sentences) 2. When to Use This Skill - Clear activation conditions 3. The Iron Law - Non-negotiable principles (if applicable) 4. Core Principles - Foundational guidelines (brief) 5. Quick Start - High-level workflow 6. Navigation - Links to detailed reference files 7. Key Reminders - Critical points to remember 8. Red Flags - Warning signs to stop and reconsider 9. Integration with Other Skills - Related skills 10. Real-World Impact - Evidence of effectiveness (if applicable)

Bundled Resources

Scripts Directory (scripts/)

Purpose: Executable code for tasks requiring deterministic reliability or repeatedly rewritten logic.

When to include:

• Same code is repeatedly rewritten
• Deterministic reliability is essential
• Complex operations benefit from pre-tested implementation

Examples:

• scripts/rotate_pdf.py - PDF rotation tasks
• scripts/init_skill.py - Skill initialization
• scripts/package_skill.py - Skill packaging and validation

Benefits:

• Token efficient (can be executed without reading into context)
• Deterministic execution
• Testable and versioned

Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments.

References Directory (references/)

Purpose: Documentation and reference material loaded into context as needed to inform Claude's process.

When to include:

• Documentation Claude should reference while working
• Detailed specifications too lengthy for entry point
• Domain knowledge that varies by project
• Complex workflows requiring step-by-step guidance

Examples:

• references/finance.md - Financial schemas
• references/mnda.md - Company NDA template
• references/policies.md - Company policies
• references/api_docs.md - API specifications
• references/workflow.md - Detailed process steps
• references/best_practices.md - Domain-specific guidelines

Use Cases:

• Database schemas
• API documentation
• Domain knowledge
• Company policies
• Detailed workflow guides
• Technical specifications
• Design principles

Benefits:

• Keeps SKILL.md lean and focused
• Loaded only when Claude determines it's needed
• Scales to unlimited detail without bloating entry point
• Organizes information by topic

Best Practices:

• If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication between SKILL.md and references
• Information should live in ONE place (prefer references for detailed content)
• Keep only essential procedural instructions in SKILL.md
• Move detailed reference material, schemas, and examples to reference files
• Use descriptive filenames that indicate content

Progressive Disclosure Pattern: Structure references to answer specific questions:

• Core concepts and principles
• Step-by-step workflows
• Technical implementation details
• Examples and templates
• Advanced patterns and edge cases

Assets Directory (assets/)

Purpose: Files not intended for context loading, but used in the output Claude produces.

When to include:

• Files needed in final deliverables
• Templates that get copied or modified
• Binary resources (images, fonts, etc.)
• Boilerplate code structures

Examples:

• assets/logo.png - Brand assets
• assets/slides.pptx - PowerPoint templates
• assets/frontend-template/ - HTML/React boilerplate
• assets/font.ttf - Typography resources
• assets/contract-template.docx - Document templates

Use Cases:

• Templates
• Images and icons
• Boilerplate code
• Fonts and typography
• Sample documents
• Frontend frameworks

Benefits:

• Separates output resources from documentation
• Enables Claude to use files without loading into context
• Provides ready-to-use starting points
• Maintains consistency across outputs

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)

• Determines skill activation
• Appears in skill catalog
• Should clearly indicate purpose and usage

2. SKILL.md body - When skill triggers (<5k words, optimal: 1-2k words)

• Core workflow and principles
• Quick start guide
• Navigation to deeper resources
• Essential reminders and warnings

3. Bundled resources - As needed by Claude (Unlimited*)

• Detailed specifications
• Complete workflows
• Examples and templates
• Technical implementation guides

*Unlimited because scripts can be executed without reading into context window.

Benefits:

• Efficient context management
• Progressive depth based on need
• Scales from simple to complex tasks
• Reduces cognitive load on entry
• Enables specialization without bloat

Application Guidelines:

• Entry point <200 lines (optimal: 140-160 lines)
• Each reference file 150-500 lines
• Clear navigation from entry to references
• Self-documenting file names
• Avoid content duplication