Skill Creator

---name: skill-creatordescription: 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---# Skill CreatorThis skill provides guidance for creating effective skills.## About SkillsSkills are modular, self-contained packages that extend Claude's capabilities by providingspecialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specificdomains or tasks—they transform Claude from a general-purpose agent into a specialized agentequipped with procedural knowledge that no model can fully possess.### What Skills Provide1. Specialized workflows - Multi-step procedures for specific domains2. Tool integrations - Instructions for working with specific file formats or APIs3. Domain expertise - Company-specific knowledge, schemas, business logic4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks## Core Principles### Concise is KeyThe context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"Prefer concise examples over verbose explanations.### Set Appropriate Degrees of FreedomMatch the level of specificity to the task's fragility and variability:**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).### Anatomy of a SkillEvery 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 (required)Every SKILL.md consists of:- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Claude reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).#### Bundled Resources (optional)##### Scripts (`scripts/`)Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks- **Benefits**: Token efficient, deterministic, may be executed without loading into context- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments##### References (`references/`)Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.- **When to include**: For documentation that Claude should reference while working- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md- **Avoid duplication**: Information should live in either SKILL.md or references files, not both.##### Assets (`assets/`)Files not intended to be loaded into context, but rather used within the output Claude produces.- **When to include**: When the skill needs files that will be used in the final output- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents### Progressive Disclosure Design PrincipleSkills use a three-level loading system to manage context efficiently:1. **Metadata (name + description)** - Always in context (~100 words)2. **SKILL.md body** - When skill triggers (<5k words)3. **Bundled resources** - As needed by ClaudeKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat.## Skill Creation ProcessSkill creation involves these steps:1. Understand the skill with concrete examples2. Plan reusable skill contents (scripts, references, assets)3. Initialize the skill (run init_skill.py)4. Edit the skill (implement resources and write SKILL.md)5. Package the skill (run package_skill.py)6. Iterate based on real usage### Step 3: Initializing the SkillWhen creating a new skill from scratch, always run the `init_skill.py` script:```bashscripts/init_skill.py <skill-name> --path <output-directory>```### Step 4: Edit the SkillConsult these helpful guides based on your skill's needs:- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns### Step 5: Packaging a Skill```bashscripts/package_skill.py <path/to/skill-folder>```The packaging script validates and creates a .skill file for distribution.FILE:references/workflows.md# Workflow Patterns## Sequential WorkflowsFor complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:```markdownFilling a PDF form involves these steps:1. Analyze the form (run analyze_form.py)2. Create field mapping (edit fields.json)3. Validate mapping (run validate_fields.py)4. Fill the form (run fill_form.py)5. Verify output (run verify_output.py)```## Conditional WorkflowsFor tasks with branching logic, guide Claude through decision points:```markdown1. Determine the modification type:   **Creating new content?** → Follow "Creation workflow" below   **Editing existing content?** → Follow "Editing workflow" below2. Creation workflow: [steps]3. Editing workflow: [steps]```FILE:references/output-patterns.md# Output PatternsUse these patterns when skills need to produce consistent, high-quality output.## Template PatternProvide templates for output format. Match the level of strictness to your needs.**For strict requirements (like API responses or data formats):**```markdown## Report structureALWAYS use this exact template structure:# [Analysis Title]## Executive summary[One-paragraph overview of key findings]## Key findings- Finding 1 with supporting data- Finding 2 with supporting data- Finding 3 with supporting data## Recommendations1. Specific actionable recommendation2. Specific actionable recommendation```**For flexible guidance (when adaptation is useful):**```markdown## Report structureHere is a sensible default format, but use your best judgment:# [Analysis Title]## Executive summary[Overview]## Key findings[Adapt sections based on what you discover]## Recommendations[Tailor to the specific context]Adjust sections as needed for the specific analysis type.```## Examples PatternFor skills where output quality depends on seeing examples, provide input/output pairs:```markdown## Commit message formatGenerate commit messages following these examples:**Example 1:**Input: Added user authentication with JWT tokensOutput:```feat(auth): implement JWT-based authenticationAdd login endpoint and token validation middleware```**Example 2:**Input: Fixed bug where dates displayed incorrectly in reportsOutput:```fix(reports): correct date formatting in timezone conversionUse UTC timestamps consistently across report generation```Follow this style: type(scope): brief description, then detailed explanation.```Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.FILE:scripts/quick_validate.py#!/usr/bin/env python3"""Quick validation script for skills - minimal version"""import sysimport osimport reimport yamlfrom pathlib import Pathdef validate_skill(skill_path):    """Basic validation of a skill"""    skill_path = Path(skill_path)    # Check SKILL.md exists    skill_md = skill_path / 'SKILL.md'    if not skill_md.exists():        return False, "SKILL.md not found"    # Read and validate frontmatter    content = skill_md.read_text()    if not content.startswith('---'):        return False, "No YAML frontmatter found"    # Extract frontmatter    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)    if not match:        return False, "Invalid frontmatter format"    frontmatter_text = match.group(1)    # Parse YAML frontmatter    try:        frontmatter = yaml.safe_load(frontmatter_text)        if not isinstance(frontmatter, dict):            return False, "Frontmatter must be a YAML dictionary"    except yaml.YAMLError as e:        return False, f"Invalid YAML in frontmatter: {e}"    # Define allowed properties    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}    # Check for unexpected properties (excluding nested keys under metadata)    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES    if unexpected_keys:        return False, (            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"        )    # Check required fields    if 'name' not in frontmatter:        return False, "Missing 'name' in frontmatter"    if 'description' not in frontmatter:        return False, "Missing 'description' in frontmatter"    # Extract name for validation    name = frontmatter.get('name', '')    if not isinstance(name, str):        return False, f"Name must be a string, got {type(name).__name__}"    name = name.strip()    if name:        # Check naming convention (hyphen-case: lowercase with hyphens)        if not re.match(r'^[a-z0-9-]+$', name):            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"        if name.startswith('-') or name.endswith('-') or '--' in name:            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"        # Check name length (max 64 characters per spec)        if len(name) > 64:            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."    # Extract and validate description    description = frontmatter.get('description', '')    if not isinstance(description, str):        return False, f"Description must be a string, got {type(description).__name__}"    description = description.strip()    if description:        # Check for angle brackets        if '<' in description or '>' in description:            return False, "Description cannot contain angle brackets (< or >)"        # Check description length (max 1024 characters per spec)        if len(description) > 1024:            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."    return True, "Skill is valid!"if __name__ == "__main__":    if len(sys.argv) != 2:        print("Usage: python quick_validate.py <skill_directory>")        sys.exit(1)        valid, message = validate_skill(sys.argv[1])    print(message)    sys.exit(0 if valid else 1)FILE:scripts/init_skill.py#!/usr/bin/env python3"""Skill Initializer - Creates a new skill from templateUsage:    init_skill.py <skill-name> --path <path>Examples:    init_skill.py my-new-skill --path skills/public    init_skill.py my-api-helper --path skills/private    init_skill.py custom-skill --path /custom/location"""import sysfrom pathlib import PathSKILL_TEMPLATE = """---name: {skill_name}description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]---# {skill_title}## Overview[TODO: 1-2 sentences explaining what this skill enables]## ResourcesThis skill includes example resource directories that demonstrate how to organize different types of bundled resources:### scripts/Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.### references/Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.### assets/Files not intended to be loaded into context, but rather used within the output Claude produces.---**Any unneeded directories can be deleted.** Not every skill requires all three types of resources."""EXAMPLE_SCRIPT = '''#!/usr/bin/env python3"""Example helper script for {skill_name}This is a placeholder script that can be executed directly.Replace with actual implementation or delete if not needed."""def main():    print("This is an example script for {skill_name}")    # TODO: Add actual script logic hereif __name__ == "__main__":    main()'''EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}This is a placeholder for detailed reference documentation.Replace with actual reference content or delete if not needed."""EXAMPLE_ASSET = """# Example Asset FileThis placeholder represents where asset files would be stored.Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed."""def title_case_skill_name(skill_name):    """Convert hyphenated skill name to Title Case for display."""    return ' '.join(word.capitalize() for word in skill_name.split('-'))def init_skill(skill_name, path):    """Initialize a new skill directory with template SKILL.md."""    skill_dir = Path(path).resolve() / skill_name    if skill_dir.exists():        print(f"❌ Error: Skill directory already exists: {skill_dir}")        return None    try:        skill_dir.mkdir(parents=True, exist_ok=False)        print(f"✅ Created skill directory: {skill_dir}")    except Exception as e:        print(f"❌ Error creating directory: {e}")        return None    skill_title = title_case_skill_name(skill_name)    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)    skill_md_path = skill_dir / 'SKILL.md'    try:        skill_md_path.write_text(skill_content)        print("✅ Created SKILL.md")    except Exception as e:        print(f"❌ Error creating SKILL.md: {e}")        return None    try:        scripts_dir = skill_dir / 'scripts'        scripts_dir.mkdir(exist_ok=True)        example_script = scripts_dir / 'example.py'        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))        example_script.chmod(0o755)        print("✅ Created scripts/example.py")        references_dir = skill_dir / 'references'        references_dir.mkdir(exist_ok=True)        example_reference = references_dir / 'api_reference.md'        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))        print("✅ Created references/api_reference.md")        assets_dir = skill_dir / 'assets'        assets_dir.mkdir(exist_ok=True)        example_asset = assets_dir / 'example_asset.txt'        example_asset.write_text(EXAMPLE_ASSET)        print("✅ Created assets/example_asset.txt")    except Exception as e:        print(f"❌ Error creating resource directories: {e}")        return None    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")    return skill_dirdef main():    if len(sys.argv) < 4 or sys.argv[2] != '--path':        print("Usage: init_skill.py <skill-name> --path <path>")        sys.exit(1)    skill_name = sys.argv[1]    path = sys.argv[3]    print(f"🚀 Initializing skill: {skill_name}")    print(f"   Location: {path}")    print()    result = init_skill(skill_name, path)    sys.exit(0 if result else 1)if __name__ == "__main__":    main()FILE:scripts/package_skill.py#!/usr/bin/env python3"""Skill Packager - Creates a distributable .skill file of a skill folderUsage:    python utils/package_skill.py <path/to/skill-folder> [output-directory]Example:    python utils/package_skill.py skills/public/my-skill    python utils/package_skill.py skills/public/my-skill ./dist"""import sysimport zipfilefrom pathlib import Pathfrom quick_validate import validate_skilldef package_skill(skill_path, output_dir=None):    """Package a skill folder into a .skill file."""    skill_path = Path(skill_path).resolve()    if not skill_path.exists():        print(f"❌ Error: Skill folder not found: {skill_path}")        return None    if not skill_path.is_dir():        print(f"❌ Error: Path is not a directory: {skill_path}")        return None    skill_md = skill_path / "SKILL.md"    if not skill_md.exists():        print(f"❌ Error: SKILL.md not found in {skill_path}")        return None    print("🔍 Validating skill...")    valid, message = validate_skill(skill_path)    if not valid:        print(f"❌ Validation failed: {message}")        print("   Please fix the validation errors before packaging.")        return None    print(f"✅ {message}\n")    skill_name = skill_path.name    if output_dir:        output_path = Path(output_dir).resolve()        output_path.mkdir(parents=True, exist_ok=True)    else:        output_path = Path.cwd()    skill_filename = output_path / f"{skill_name}.skill"    try:        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:            for file_path in skill_path.rglob('*'):                if file_path.is_file():                    arcname = file_path.relative_to(skill_path.parent)                    zipf.write(file_path, arcname)                    print(f"  Added: {arcname}")        print(f"\n✅ Successfully packaged skill to: {skill_filename}")        return skill_filename    except Exception as e:        print(f"❌ Error creating .skill file: {e}")        return Nonedef main():    if len(sys.argv) < 2:        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")        sys.exit(1)    skill_path = sys.argv[1]    output_dir = sys.argv[2] if len(sys.argv) > 2 else None    print(f"📦 Packaging skill: {skill_path}")    if output_dir:        print(f"   Output directory: {output_dir}")    print()    result = package_skill(skill_path, output_dir)    sys.exit(0 if result else 1)if __name__ == "__main__":    main()