1#!/usr/bin/env python3
  2"""
  3Skill Initializer - Creates a new skill from template
  4
  5Usage:
  6    init_skill.py <skill-name> --path <path>
  7
  8Examples:
  9    init_skill.py my-new-skill --path skills/public
 10    init_skill.py my-api-helper --path skills/private
 11    init_skill.py custom-skill --path /custom/location
 12"""
 13
 14import sys
 15from pathlib import Path
 16
 17
 18SKILL_TEMPLATE = """---
 19name: {skill_name}
 20description: [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.]
 21---
 22
 23# {skill_title}
 24
 25## Overview
 26
 27[TODO: 1-2 sentences explaining what this skill enables]
 28
 29## Structuring This Skill
 30
 31[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
 32
 33**1. Workflow-Based** (best for sequential processes)
 34- Works well when there are clear step-by-step procedures
 35- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
 36- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
 37
 38**2. Task-Based** (best for tool collections)
 39- Works well when the skill offers different operations/capabilities
 40- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
 41- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
 42
 43**3. Reference/Guidelines** (best for standards or specifications)
 44- Works well for brand guidelines, coding standards, or requirements
 45- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
 46- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
 47
 48**4. Capabilities-Based** (best for integrated systems)
 49- Works well when the skill provides multiple interrelated features
 50- Example: Product Management with "Core Capabilities" → numbered capability list
 51- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
 52
 53Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
 54
 55Delete this entire "Structuring This Skill" section when done - it's just guidance.]
 56
 57## [TODO: Replace with the first main section based on chosen structure]
 58
 59[TODO: Add content here. See examples in existing skills:
 60- Code samples for technical skills
 61- Decision trees for complex workflows
 62- Concrete examples with realistic user requests
 63- References to scripts/templates/references as needed]
 64
 65## Resources
 66
 67This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
 68
 69### scripts/
 70Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
 71
 72**Examples from other skills:**
 73- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
 74- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
 75
 76**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
 77
 78**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
 79
 80### references/
 81Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
 82
 83**Examples from other skills:**
 84- Product management: `communication.md`, `context_building.md` - detailed workflow guides
 85- BigQuery: API reference documentation and query examples
 86- Finance: Schema documentation, company policies
 87
 88**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
 89
 90### assets/
 91Files not intended to be loaded into context, but rather used within the output Claude produces.
 92
 93**Examples from other skills:**
 94- Brand styling: PowerPoint template files (.pptx), logo files
 95- Frontend builder: HTML/React boilerplate project directories
 96- Typography: Font files (.ttf, .woff2)
 97
 98**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
 99
100---
101
102**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
103"""
104
105EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
106"""
107Example helper script for {skill_name}
108
109This is a placeholder script that can be executed directly.
110Replace with actual implementation or delete if not needed.
111
112Example real scripts from other skills:
113- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
114- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
115"""
116
117def main():
118    print("This is an example script for {skill_name}")
119    # TODO: Add actual script logic here
120    # This could be data processing, file conversion, API calls, etc.
121
122if __name__ == "__main__":
123    main()
124'''
125
126EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
127
128This is a placeholder for detailed reference documentation.
129Replace with actual reference content or delete if not needed.
130
131Example real reference docs from other skills:
132- product-management/references/communication.md - Comprehensive guide for status updates
133- product-management/references/context_building.md - Deep-dive on gathering context
134- bigquery/references/ - API references and query examples
135
136## When Reference Docs Are Useful
137
138Reference docs are ideal for:
139- Comprehensive API documentation
140- Detailed workflow guides
141- Complex multi-step processes
142- Information too lengthy for main SKILL.md
143- Content that's only needed for specific use cases
144
145## Structure Suggestions
146
147### API Reference Example
148- Overview
149- Authentication
150- Endpoints with examples
151- Error codes
152- Rate limits
153
154### Workflow Guide Example
155- Prerequisites
156- Step-by-step instructions
157- Common patterns
158- Troubleshooting
159- Best practices
160"""
161
162EXAMPLE_ASSET = """# Example Asset File
163
164This placeholder represents where asset files would be stored.
165Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
166
167Asset files are NOT intended to be loaded into context, but rather used within
168the output Claude produces.
169
170Example asset files from other skills:
171- Brand guidelines: logo.png, slides_template.pptx
172- Frontend builder: hello-world/ directory with HTML/React boilerplate
173- Typography: custom-font.ttf, font-family.woff2
174- Data: sample_data.csv, test_dataset.json
175
176## Common Asset Types
177
178- Templates: .pptx, .docx, boilerplate directories
179- Images: .png, .jpg, .svg, .gif
180- Fonts: .ttf, .otf, .woff, .woff2
181- Boilerplate code: Project directories, starter files
182- Icons: .ico, .svg
183- Data files: .csv, .json, .xml, .yaml
184
185Note: This is a text placeholder. Actual assets can be any file type.
186"""
187
188
189def title_case_skill_name(skill_name):
190    """Convert hyphenated skill name to Title Case for display."""
191    return ' '.join(word.capitalize() for word in skill_name.split('-'))
192
193
194def init_skill(skill_name, path):
195    """
196    Initialize a new skill directory with template SKILL.md.
197
198    Args:
199        skill_name: Name of the skill
200        path: Path where the skill directory should be created
201
202    Returns:
203        Path to created skill directory, or None if error
204    """
205    # Determine skill directory path
206    skill_dir = Path(path).resolve() / skill_name
207
208    # Check if directory already exists
209    if skill_dir.exists():
210        print(f"❌ Error: Skill directory already exists: {skill_dir}")
211        return None
212
213    # Create skill directory
214    try:
215        skill_dir.mkdir(parents=True, exist_ok=False)
216        print(f"✅ Created skill directory: {skill_dir}")
217    except Exception as e:
218        print(f"❌ Error creating directory: {e}")
219        return None
220
221    # Create SKILL.md from template
222    skill_title = title_case_skill_name(skill_name)
223    skill_content = SKILL_TEMPLATE.format(
224        skill_name=skill_name,
225        skill_title=skill_title
226    )
227
228    skill_md_path = skill_dir / 'SKILL.md'
229    try:
230        skill_md_path.write_text(skill_content)
231        print("✅ Created SKILL.md")
232    except Exception as e:
233        print(f"❌ Error creating SKILL.md: {e}")
234        return None
235
236    # Create resource directories with example files
237    try:
238        # Create scripts/ directory with example script
239        scripts_dir = skill_dir / 'scripts'
240        scripts_dir.mkdir(exist_ok=True)
241        example_script = scripts_dir / 'example.py'
242        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
243        example_script.chmod(0o755)
244        print("✅ Created scripts/example.py")
245
246        # Create references/ directory with example reference doc
247        references_dir = skill_dir / 'references'
248        references_dir.mkdir(exist_ok=True)
249        example_reference = references_dir / 'api_reference.md'
250        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
251        print("✅ Created references/api_reference.md")
252
253        # Create assets/ directory with example asset placeholder
254        assets_dir = skill_dir / 'assets'
255        assets_dir.mkdir(exist_ok=True)
256        example_asset = assets_dir / 'example_asset.txt'
257        example_asset.write_text(EXAMPLE_ASSET)
258        print("✅ Created assets/example_asset.txt")
259    except Exception as e:
260        print(f"❌ Error creating resource directories: {e}")
261        return None
262
263    # Print next steps
264    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
265    print("\nNext steps:")
266    print("1. Edit SKILL.md to complete the TODO items and update the description")
267    print("2. Customize or delete the example files in scripts/, references/, and assets/")
268    print("3. Run the validator when ready to check the skill structure")
269
270    return skill_dir
271
272
273def main():
274    if len(sys.argv) < 4 or sys.argv[2] != '--path':
275        print("Usage: init_skill.py <skill-name> --path <path>")
276        print("\nSkill name requirements:")
277        print("  - Hyphen-case identifier (e.g., 'data-analyzer')")
278        print("  - Lowercase letters, digits, and hyphens only")
279        print("  - Max 40 characters")
280        print("  - Must match directory name exactly")
281        print("\nExamples:")
282        print("  init_skill.py my-new-skill --path skills/public")
283        print("  init_skill.py my-api-helper --path skills/private")
284        print("  init_skill.py custom-skill --path /custom/location")
285        sys.exit(1)
286
287    skill_name = sys.argv[1]
288    path = sys.argv[3]
289
290    print(f"🚀 Initializing skill: {skill_name}")
291    print(f"   Location: {path}")
292    print()
293
294    result = init_skill(skill_name, path)
295
296    if result:
297        sys.exit(0)
298    else:
299        sys.exit(1)
300
301
302if __name__ == "__main__":
303    main()