name	maestro
description	Creates and updates Claude Code skills following best practices. Guides through requirements gathering, design, content generation, and validation. Handles both new skill creation and refactoring existing skills. Use when user mentions 'create skill', 'build skill', 'new skill', 'update skill', 'improve skill', 'refactor skill', or asks to build capabilities for Claude Code.

Maestro: Skill Builder for Claude Code

Maestro helps you create high-quality Claude Code skills through a guided, stage-based workflow. It handles both new skill creation and improvements to existing skills.

What Maestro Does

Creates new skills from scratch with proper structure and best practices
Updates existing skills by analyzing and refactoring them
Ensures YAML syntax validity and structural correctness
Enforces best practices (concise content, trigger-rich descriptions, progressive disclosure)
Generates supporting files only when justified (templates, examples, scripts)
Provides validation and quality assurance
Outputs skills to user-specified locations

When to Use Maestro

Use maestro when:

User wants to create a new skill for Claude Code
User wants to improve/refactor/update an existing skill
User mentions skill-related terms: "build a skill", "create skill", "skill for X"
User wants to package functionality into a reusable capability

Workflow Overview

Maestro uses a 5-stage workflow that adapts based on whether you're creating or updating:

Stage 0: Mode Detection

Determine if this is Creation Mode or Update Mode:

Creation: User wants a new skill from scratch
Update: User provides existing skill path or asks to improve/refactor

Stage 1: Requirements & Discovery

Creation Mode: Ask interactive questions to gather requirements:

Core capability: What task/capability should this skill handle?
Trigger phrases: What user phrases should activate it? (for description)
Tool requirements: What tools are needed?
- Read-only operations?
- File editing?
- Web access?
- Bash execution?
Complexity level:
- Simple utility (single file, <300 lines)?
- Moderate workflow (main file + 1-2 support files)?
- Complex multi-step (multiple files + scripts)?
Supporting resources: Does it need:
- Templates for output formats?
- Examples showing desired behavior?
- Reference documentation?
- Utility scripts (only if deterministic operations needed)?
Output location: Where to create skill?
- Default: ./skill-name/ in current directory
- Custom: User-specified path

Document all requirements clearly before proceeding.

Update Mode:

Ask for existing skill path (SKILL.md location)
Read all skill files (SKILL.md + supporting files)
Analyze current structure:
- YAML frontmatter compliance
- Content length and organization
- File structure and references
- Best practice adherence
Identify issues:
- YAML syntax problems
- Vague or missing trigger terms in description
- Anti-patterns (Windows paths, magic numbers, etc.)
- Length violations (>500 lines)
- Missing opportunities (could use scripts, needs examples, etc.)
- Unclear workflows
Present improvement proposal with specific changes
Get user confirmation on what to fix

Stage 2: Design & Architecture

Name Design:

Creation: Propose skill names following conventions
Update: Validate existing name or propose rename if needed

Naming rules:

Lowercase letters, numbers, hyphens only
Max 64 characters
Use gerund form (verb + -ing): processing-pdfs, analyzing-data
Avoid vague names: helper, utils, tool

Description Design: Craft trigger-rich descriptions (max 1024 chars) that specify:

What the skill does (capabilities)
When to use it (trigger scenarios)
Key terms users might mention

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

Information Architecture: Determine file structure based on complexity:

Simple (single SKILL.md, <300 lines):
- No supporting files
- All content in SKILL.md
- No scripts
Moderate (SKILL.md + 1-2 support files):
- SKILL.md as overview (~300 lines)
- TEMPLATES.md for output formats
- EXAMPLES.md for input/output pairs
- No scripts or very simple script
Complex (multiple files + scripts):
- SKILL.md as navigation hub (~400 lines)
- Multiple support files (TEMPLATES.md, EXAMPLES.md, REFERENCE.md, WORKFLOWS.md)
- Utility scripts (only if needed for deterministic operations)
- Keep scripts simple (<150 lines each)

Script Planning: Only include scripts when:

Deterministic operations needed (validation, parsing, formatting)
Script saves significant tokens vs. generating code inline
Operation is fragile and needs exact sequence

Script requirements:

Keep simple (<150 lines)
Document all parameters with comments
Explicit error handling (solve, don't punt)
No external dependencies if possible
Add basic tests if >50 lines or complex logic

Tool Restrictions: Determine if allowed-tools frontmatter is needed:

Use for read-only skills that shouldn't modify files
Use for security-sensitive workflows
Omit if skill needs full tool access

Stage 3: Content Generation

Generate all skill files following best practices.

SKILL.md Structure:

---
name: skill-name
description: What it does and when to use it with trigger terms
allowed-tools: [optional, only if restrictions needed]
---

# Skill Title

Brief overview paragraph.

## What This Skill Does

- Capability 1
- Capability 2
- Capability 3

## When to Use

Use this skill when...

## How It Works

[For simple skills: direct instructions]
[For complex skills: stage-based workflow or decision tree]

## References

[If applicable, one-level-deep references to supporting files]
- See TEMPLATES.md for output format examples
- See EXAMPLES.md for input/output pairs
- Run validate.py for validation

SKILL.md Best Practices:

Keep under 500 lines (ideally 300-400)
Use progressive disclosure (overview → details in support files)
Write concisely (assume Claude is smart, only add what's not known)
Include clear workflows for multi-step tasks
Provide checklists for complex sequences
Use consistent terminology throughout
No time-sensitive information (dates, versions)
Unix-style paths only (forward slashes)
Reference support files one level deep only

Supporting Files (generate only when justified):

TEMPLATES.md: Output format examples
- Include when skill produces structured output
- Show exact format expected
- Provide variations for different contexts
EXAMPLES.md: Input/output pairs
- Include when behavior needs demonstration
- Show 3-5 realistic examples
- Cover edge cases and variations
- Annotate to explain choices
REFERENCE.md: Detailed documentation
- Include when SKILL.md would exceed 500 lines
- Technical details too lengthy for main file
- API documentation, schema definitions
WORKFLOWS.md: Decision trees and conditional logic
- Include when skill has multiple paths
- Provide clear decision points
- Show "if X then Y" logic
Utility Scripts: Deterministic operations
- Only when truly needed
- Keep simple and well-documented
- Explicit error handling
- Comment parameter choices

For Updates:

Regenerate problematic sections while preserving good content
Fix structural issues (YAML, paths, naming)
Enhance descriptions with trigger terms
Split oversized SKILL.md into main + support files
Add missing support files if beneficial
Simplify or document existing scripts

Stage 4: Validation & Quality Assurance

Run automated validation using validate_skill.py:

Structural Checks:

YAML syntax valid
Frontmatter complete (name, description present)
Name constraints (≤64 chars, lowercase, hyphens only)
Description constraints (≤1024 chars, non-empty)
File paths valid and use Unix-style separators
All referenced files exist

Best Practice Checks:

SKILL.md ≤500 lines
Description includes trigger terms
File references one level deep only
Consistent terminology used
No time-sensitive information
No Windows-style paths

Anti-Pattern Detection:

Windows paths (backslashes)
Vague descriptions ("helper", "utility")
Magic numbers in scripts (undocumented constants)
Missing error handling in scripts
Deeply nested file references
Excessive options without defaults

Auto-Fix Minor Issues:

Convert Windows paths to Unix paths
Fix whitespace in YAML
Normalize line endings

Report Major Issues:

Present validation report with quality score
List all issues found by category
Offer to regenerate/fix problematic sections
Highlight critical vs. optional improvements

Stage 5: Testing & Iteration Support

Help user test and refine the skill.

Generate Test Prompts: Create 3-5 example user messages that should trigger the skill:

Vary phrasing to test trigger term matching
Cover different use cases
Include edge cases

Installation Instructions:

# Personal skill
cp -r ./skill-name ~/.claude/skills/

# Project skill
cp -r ./skill-name ./.claude/skills/

Testing Guidance:

Install the skill in desired location
Start new Claude Code conversation
Test with generated prompts
Verify skill activates appropriately
Check output quality and behavior

Iteration Support:

Common refinements based on testing
How to adjust trigger terms if not activating
When to simplify vs. add detail
Cross-model considerations (Haiku vs. Sonnet vs. Opus)

Next Steps:

If skill works well: done!
If needs refinement: offer to update (return to Stage 1B)
If not activating: improve description trigger terms
If behavior issues: refine instructions or add examples

Reference Materials

For detailed information, reference these supporting files:

TEMPLATES.md: Ready-to-use skill templates for different complexity levels
CHECKLIST.md: Quality checklist and best practices summary
EXAMPLES.md: Annotated real skill examples with design explanations
PATTERNS.md: Common skill patterns and progressive disclosure strategies

For validation:

Run python ~/.claude/skills/maestro/validate_skill.py <path-to-SKILL.md>

Quick Start Examples

Example 1: Create Simple Skill

User: "Create a skill that helps me write commit messages"
Maestro: [Asks questions about requirements]
Maestro: [Designs simple single-file skill]
Maestro: [Generates SKILL.md in ./commit-helper/]
Maestro: [Validates and provides installation instructions]

Example 2: Update Existing Skill

User: "Improve my PDF skill at ~/.claude/skills/pdf-processor/SKILL.md"
Maestro: [Analyzes existing skill]
Maestro: [Identifies issues: description too vague, SKILL.md too long]
Maestro: [Proposes improvements: enhance description, split into SKILL.md + REFERENCE.md]
Maestro: [Regenerates improved skill]
Maestro: [Validates and provides testing guidance]

Important Principles

Simplicity First: Start with minimal structure. Only add complexity when justified.

Scripts as Last Resort: Only include scripts for deterministic operations that save tokens or ensure consistency. Keep them simple.

Progressive Disclosure: Don't load everything upfront. SKILL.md is navigation hub, details in support files.

Teach While Building: Explain why design choices matter, not just what to do.

User Ownership: Output to user-specified location. User handles installation, git, and distribution.

Quality Over Speed: Take time to get structure right. Validate before delivering.

Output Strategy

Default: Create ./skill-name/ in current working directory

Custom: Ask user for preferred path if they specify

Post-Generation Message:

✓ Skill created at ./skill-name/

To install:
  Personal: cp -r ./skill-name ~/.claude/skills/
  Project:  cp -r ./skill-name ./.claude/skills/

Test with prompts like:
  - [generated example 1]
  - [generated example 2]
  - [generated example 3]

Common Pitfalls to Avoid

Vague descriptions: Always include specific trigger terms
Oversized SKILL.md: Keep under 500 lines, use support files
Unnecessary complexity: Don't add scripts/files unless justified
Windows paths: Always use forward slashes
Missing validation: Always run validate_skill.py before delivering
Assumed knowledge: Document script parameters and design choices
Time-sensitive content: No dates, version cutoffs, or temporal references

Success Criteria

A well-built skill should:

✓ Have valid YAML frontmatter
✓ Have trigger-rich description (≤1024 chars)
✓ Have concise SKILL.md (≤500 lines)
✓ Follow progressive disclosure pattern
✓ Include only justified supporting files
✓ Pass all validation checks
✓ Activate appropriately when tested
✓ Follow consistent terminology
✓ Include clear workflows for complex tasks

Install Skill

SKILL.md