skill-creator

1#!/usr/bin/env python32"""Skill Initializer - Creates a new skill from template.3 4Usage:5 init_skill.py <skill-name> --path <path>6 7Examples:8 init_skill.py my-new-skill --path skills/public9 init_skill.py my-api-helper --path skills/private10 init_skill.py custom-skill --path /custom/location11 12For deepagents CLI:13 init_skill.py my-skill --path ~/.deepagents/agent/skills14"""15 16import sys17from pathlib import Path18 19SKILL_TEMPLATE = """---20name: {skill_name}21description: [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.]22---23 24# {skill_title}25 26## Overview27 28[TODO: 1-2 sentences explaining what this skill enables]29 30## Structuring This Skill31 32[TODO: Choose the structure that best fits this skill's purpose. Common patterns:33 34**1. Workflow-Based** (best for sequential processes)35- Works well when there are clear step-by-step procedures36- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"37- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...38 39**2. Task-Based** (best for tool collections)40- Works well when the skill offers different operations/capabilities41- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"42- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...43 44**3. Reference/Guidelines** (best for standards or specifications)45- Works well for brand guidelines, coding standards, or requirements46- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"47- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...48 49**4. Capabilities-Based** (best for integrated systems)50- Works well when the skill provides multiple interrelated features51- Example: Product Management with "Core Capabilities" → numbered capability list52- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...53 54Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).55 56Delete this entire "Structuring This Skill" section when done - it's just guidance.]57 58## [TODO: Replace with the first main section based on chosen structure]59 60[TODO: Add content here. See examples in existing skills:61- Code samples for technical skills62- Decision trees for complex workflows63- Concrete examples with realistic user requests64- References to scripts/templates/references as needed]65 66## Resources67 68This skill includes example resource directories that demonstrate how to organize different types of bundled resources:69 70### scripts/71Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.72 73**Examples from other skills:**74- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation75- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing76 77**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.78 79**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.80 81### references/82Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.83 84**Examples from other skills:**85- Product management: `communication.md`, `context_building.md` - detailed workflow guides86- BigQuery: API reference documentation and query examples87- Finance: Schema documentation, company policies88 89**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.90 91### assets/92Files not intended to be loaded into context, but rather used within the output Claude produces.93 94**Examples from other skills:**95- Brand styling: PowerPoint template files (.pptx), logo files96- Frontend builder: HTML/React boilerplate project directories97- Typography: Font files (.ttf, .woff2)98 99**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.100 101---102 103**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.104"""  # noqa: E501105 106EXAMPLE_SCRIPT = '''#!/usr/bin/env python3107"""108Example helper script for {skill_name}109 110This is a placeholder script that can be executed directly.111Replace with actual implementation or delete if not needed.112 113Example real scripts from other skills:114- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields115- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images116"""117 118def main():119    print("This is an example script for {skill_name}")120    # TODO: Add actual script logic here121    # This could be data processing, file conversion, API calls, etc.122 123if __name__ == "__main__":124    main()125'''126 127EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}128 129This is a placeholder for detailed reference documentation.130Replace with actual reference content or delete if not needed.131 132Example real reference docs from other skills:133- product-management/references/communication.md - Comprehensive guide for status updates134- product-management/references/context_building.md - Deep-dive on gathering context135- bigquery/references/ - API references and query examples136 137## When Reference Docs Are Useful138 139Reference docs are ideal for:140- Comprehensive API documentation141- Detailed workflow guides142- Complex multi-step processes143- Information too lengthy for main SKILL.md144- Content that's only needed for specific use cases145 146## Structure Suggestions147 148### API Reference Example149- Overview150- Authentication151- Endpoints with examples152- Error codes153- Rate limits154 155### Workflow Guide Example156- Prerequisites157- Step-by-step instructions158- Common patterns159- Troubleshooting160- Best practices161"""  # noqa: E501162 163EXAMPLE_ASSET = """# Example Asset File164 165This placeholder represents where asset files would be stored.166Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.167 168Asset files are NOT intended to be loaded into context, but rather used within169the output Claude produces.170 171Example asset files from other skills:172- Brand guidelines: logo.png, slides_template.pptx173- Frontend builder: hello-world/ directory with HTML/React boilerplate174- Typography: custom-font.ttf, font-family.woff2175- Data: sample_data.csv, test_dataset.json176 177## Common Asset Types178 179- Templates: .pptx, .docx, boilerplate directories180- Images: .png, .jpg, .svg, .gif181- Fonts: .ttf, .otf, .woff, .woff2182- Boilerplate code: Project directories, starter files183- Icons: .ico, .svg184- Data files: .csv, .json, .xml, .yaml185 186Note: This is a text placeholder. Actual assets can be any file type.187"""  # noqa: E501188 189 190def title_case_skill_name(skill_name):191    """Convert hyphenated skill name to Title Case for display.192 193    Returns:194        Skill name with each word capitalized.195    """196    return " ".join(word.capitalize() for word in skill_name.split("-"))197 198 199def init_skill(skill_name, path):200    """Initialize a new skill directory with template SKILL.md.201 202    Args:203        skill_name: Name of the skill204        path: Path where the skill directory should be created205 206    Returns:207        Path to created skill directory, or None if error208    """209    # Determine skill directory path210    skill_dir = Path(path).resolve() / skill_name211 212    # Check if directory already exists213    if skill_dir.exists():214        print(f"Error: Skill directory already exists: {skill_dir}")215        return None216 217    # Create skill directory218    try:219        skill_dir.mkdir(parents=True, exist_ok=False)220        print(f"Created skill directory: {skill_dir}")221    except Exception as e:222        print(f"Error creating directory: {e}")223        return None224 225    # Create SKILL.md from template226    skill_title = title_case_skill_name(skill_name)227    skill_content = SKILL_TEMPLATE.format(228        skill_name=skill_name, skill_title=skill_title229    )230 231    skill_md_path = skill_dir / "SKILL.md"232    try:233        skill_md_path.write_text(skill_content)234        print("Created SKILL.md")235    except Exception as e:236        print(f"Error creating SKILL.md: {e}")237        return None238 239    # Create resource directories with example files240    try:241        # Create scripts/ directory with example script242        scripts_dir = skill_dir / "scripts"243        scripts_dir.mkdir(exist_ok=True)244        example_script = scripts_dir / "example.py"245        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))246        example_script.chmod(0o755)247        print("Created scripts/example.py")248 249        # Create references/ directory with example reference doc250        references_dir = skill_dir / "references"251        references_dir.mkdir(exist_ok=True)252        example_reference = references_dir / "api_reference.md"253        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))254        print("Created references/api_reference.md")255 256        # Create assets/ directory with example asset placeholder257        assets_dir = skill_dir / "assets"258        assets_dir.mkdir(exist_ok=True)259        example_asset = assets_dir / "example_asset.txt"260        example_asset.write_text(EXAMPLE_ASSET)261        print("Created assets/example_asset.txt")262    except Exception as e:263        print(f"Error creating resource directories: {e}")264        return None265 266    # Print next steps267    print(f"\nSkill '{skill_name}' initialized successfully at {skill_dir}")268    print("\nNext steps:")269    print("1. Edit SKILL.md to complete the TODO items and update the description")270    print(271        "2. Customize or delete the example files in scripts/, references/, and assets/"272    )273    print("3. Run the validator when ready to check the skill structure")274 275    return skill_dir276 277 278def main():279    """Main entry point for the skill initialization script."""280    if len(sys.argv) < 4 or sys.argv[2] != "--path":281        print("Usage: init_skill.py <skill-name> --path <path>")282        print("\nSkill name requirements:")283        print(" - Hyphen-case identifier (e.g., 'data-analyzer')")284        print(" - Lowercase letters, digits, and hyphens only")285        print(" - Max 64 characters")286        print(" - Must match directory name exactly")287        print("\nExamples:")288        print(" init_skill.py my-new-skill --path skills/public")289        print(" init_skill.py my-api-helper --path skills/private")290        print(" init_skill.py custom-skill --path /custom/location")291        print("\nFor deepagents CLI:")292        print(" init_skill.py my-skill --path ~/.deepagents/agent/skills")293        sys.exit(1)294 295    skill_name = sys.argv[1]296    path = sys.argv[3]297 298    print(f"🚀 Initializing skill: {skill_name}")299    print(f"   Location: {path}")300    print()301 302    result = init_skill(skill_name, path)303 304    if result:305        sys.exit(0)306    else:307        sys.exit(1)308 309 310if __name__ == "__main__":311    main()312