@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/skillkit/scripts/init_skill.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    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 argparse
+import sys
+from enum import Enum
+from pathlib import Path
+
+
+SKILL_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]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This 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.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**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.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __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 real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+class WorkflowMode(Enum):
+    FAST = "fast"      # 12-step, structural only
+    FULL = "full"      # 15-step, structural + behavioral
+
+
+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 prompt_for_mode():
+    """Ask user for workflow mode during skill creation."""
+    print("\n" + "=" * 60)
+    print("WORKFLOW MODE SELECTION")
+    print("=" * 60)
+    print("\nFAST Mode (12 steps)")
+    print("  - Structural validation only")
+    print("  - Quick iteration")
+    print("  - Best for: simple utilities, prototypes")
+    print("\nFULL Mode (15 steps)")
+    print("  - Structural + behavioral validation")
+    print("  - TDD pressure testing")
+    print("  - Best for: discipline skills, production quality")
+    print("\n" + "-" * 60)
+
+    while True:
+        choice = input("\nSelect mode (1=fast, 2=full) [1]: ").strip() or "1"
+        if choice == "1":
+            return WorkflowMode.FAST
+        if choice == "2":
+            return WorkflowMode.FULL
+        print("Invalid choice. Enter 1 or 2.")
+
+
+def get_skill_template(skill_name, mode=WorkflowMode.FAST):
+    """Get SKILL.md template based on workflow mode."""
+    skill_title = title_case_skill_name(skill_name)
+    template = SKILL_TEMPLATE
+
+    if mode == WorkflowMode.FULL:
+        template += """
+
+## Behavioral Validation
+
+### RED Phase - Baseline Failures
+<!-- Document rationalizations found WITHOUT skill -->
+
+### GREEN Phase - Verification
+<!-- Confirm compliance WITH skill -->
+
+### Rationalization Table
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks |
+| "I'll test after" | Tests-after proves nothing |
+
+## Pressure Test Results
+- [ ] Time pressure: __
+- [ ] Sunk cost pressure: __
+- [ ] Authority pressure: __
+- [ ] Exhaustion pressure: __
+- [ ] Combined pressure: __
+
+**Final Behavioral Score:** __/10
+"""
+
+    return template.format(
+        skill_name=skill_name,
+        skill_title=skill_title
+    )
+
+
+def create_skill_structure(skill_name, path, mode):
+    """Create skill directory and mode-specific SKILL.md."""
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"❌ Error: Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    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
+
+    # Create mode marker file
+    mode_file = skill_dir / '.skillkit-mode'
+    mode_file.write_text(mode.value)
+    print(f"✅ Created .skillkit-mode ({mode.value})")
+
+    # Create SKILL.md from template
+    skill_content = get_skill_template(skill_name, mode)
+    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
+
+    return skill_dir
+
+
+def init_skill(skill_name, path, mode=WorkflowMode.FAST):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    skill_dir = create_skill_structure(skill_name, path, mode)
+    if not skill_dir:
+        return None
+
+    # Create resource directories with example files
+    skill_title = title_case_skill_name(skill_name)
+    try:
+        # Create scripts/ directory with example script
+        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")
+
+        # Create references/ directory with example reference doc
+        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")
+
+        # Create assets/ directory with example asset placeholder
+        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 next steps
+    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    print("2. Customize or delete the example files in scripts/, references/, and assets/")
+    print("3. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Create a new skill from template',
+        epilog='''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
+
+Skill name requirements:
+  - Hyphen-case identifier (e.g., 'data-analyzer')
+  - Lowercase letters, digits, and hyphens only
+  - Max 40 characters
+  - Must match directory name exactly''',
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument('skill_name', help='Name of the skill to create')
+    parser.add_argument(
+        '--path',
+        default='.',
+        help='Path where the skill directory should be created (default: current directory)'
+    )
+    parser.add_argument(
+        '--mode',
+        choices=['fast', 'full'],
+        default=None,
+        help='Workflow mode: fast (12-step) or full (15-step with TDD). Default: fast'
+    )
+
+    args = parser.parse_args()
+    selected_mode = (
+        WorkflowMode(args.mode)
+        if args.mode
+        else (prompt_for_mode() if sys.stdin.isatty() else WorkflowMode.FAST)
+    )
+
+    print(f"🚀 Initializing skill: {args.skill_name}")
+    print(f"   Location: {args.path}")
+    print(f"   Mode: {selected_mode.value}")
+    print()
+
+    result = init_skill(args.skill_name, args.path, selected_mode)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skills/skillkit/scripts/init_subagent.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+Subagent Initializer - Creates a new subagent file from template
+
+Usage:
+    init_subagent.py <subagent-name> --path <path>
+
+Examples:
+    init_subagent.py code-reviewer --path ~/.claude/agents
+    init_subagent.py security-auditor --path ~/.claude/agents
+
+Note: Subagents are individual .md files in ~/.claude/agents/
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+SUBAGENT_TEMPLATE = """---
+name: {subagent_name}
+description: "[TODO: Clear description of what this subagent does and when to use it. Include specific scenarios that trigger delegation. See code-simplifier.md for example format with <example> tags.]"
+subagent_type: [TODO: Choose one]
+# Options: general-purpose, code-reviewer, typescript-pro, flutter-expert,
+#          red-team, qa-expert, seo-manager, creative-copywriter,
+#          decision-maker, research, custom
+
+tools:
+  - Read      # Always recommended
+  - Write     # Enable if subagent needs to create files
+  - Edit      # Enable if subagent needs to modify files
+  - Bash      # Enable if subagent needs command execution
+  - Glob      # Enable for file pattern matching
+  - Grep      # Enable for content search
+  - Skill     # Enable to invoke other skills
+  # - Task    # Enable if spawning nested subagents
+
+# Optional: Skills this subagent can invoke
+# skills:
+#   - skill-name  # Description of when to use this skill
+
+# Optional: Model preference (defaults to parent's model)
+# model: sonnet  # Options: sonnet, opus, haiku
+---
+
+You are a specialist in [TODO: domain expertise]. Your purpose is to [TODO: main purpose].
+
+## Your Capabilities
+
+**Core Expertise:**
+- [TODO: Capability 1]
+- [TODO: Capability 2]
+- [TODO: Capability 3]
+
+**When to Invoke You:**
+- [TODO: Trigger condition 1]
+- [TODO: Trigger condition 2]
+- [TODO: Trigger condition 3]
+
+## Your Approach
+
+1. **Analysis Phase:**
+   - [TODO: Step 1]
+   - [TODO: Step 2]
+
+2. **Implementation Phase:**
+   - [TODO: Step 3]
+   - [TODO: Step 4]
+
+3. **Review Phase:**
+   - [TODO: Step 5]
+   - [TODO: Step 6]
+
+## Guidelines
+
+- [TODO: Guideline 1]
+- [TODO: Guideline 2]
+- [TODO: Guideline 3]
+
+## Output Format
+
+Always structure your response as:
+
+```
+## Summary
+[Brief overview of what was done]
+
+## Details
+[Detailed explanation/implementation]
+
+## Recommendations
+[Actionable next steps or improvements]
+```
+
+---
+
+**IMPORTANT:** This is a template with [TODO] placeholders. Before using this subagent, you MUST:
+1. Research actual best practices for this domain (don't use generic personas)
+2. Replace all [TODO] sections with specific, research-based content
+3. Add concrete examples with <example> tags in description
+4. Test the subagent with sample tasks
+"""
+
+
+def validate_subagent_name(name: str) -> tuple[bool, str]:
+    """Validate subagent name format.
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if len(name) > 40:
+        return False, "Name must be 40 characters or less"
+
+    if not re.match(r'^[a-z0-9-]+$', name):
+        return False, "Name must contain only lowercase letters, digits, and hyphens"
+
+    if name.startswith('-') or name.endswith('-'):
+        return False, "Name cannot start or end with a hyphen"
+
+    if '--' in name:
+        return False, "Name cannot contain consecutive hyphens"
+
+    return True, ""
+
+
+def init_subagent(subagent_name: str, path: str) -> Path | None:
+    """Initialize a new subagent file with template content.
+
+    Args:
+        subagent_name: Name of the subagent (hyphen-case)
+        path: Directory path where the subagent file should be created
+
+    Returns:
+        Path to created subagent file, or None if error occurred
+    """
+    # Validate inputs
+    is_valid, error_msg = validate_subagent_name(subagent_name)
+    if not is_valid:
+        print(f"❌ Error: Invalid subagent name '{subagent_name}': {error_msg}")
+        return None
+
+    target_dir = Path(path).expanduser().resolve()
+    subagent_file = target_dir / f"{subagent_name}.md"
+
+    # Check if file already exists
+    if subagent_file.exists():
+        print(f"❌ Error: Subagent file already exists: {subagent_file}")
+        return None
+
+    # Ensure target is a directory
+    if target_dir.exists() and not target_dir.is_dir():
+        print(f"❌ Error: Target path exists but is not a directory: {target_dir}")
+        return None
+
+    # Create parent directory
+    try:
+        target_dir.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        print(f"❌ Error: Permission denied creating directory: {target_dir}")
+        return None
+    except OSError as e:
+        print(f"❌ Error creating directory: {e}")
+        return None
+
+    # Create subagent file
+    try:
+        subagent_file.write_text(SUBAGENT_TEMPLATE.format(subagent_name=subagent_name))
+        print(f"✅ Created subagent file: {subagent_file}")
+    except PermissionError:
+        print(f"❌ Error: Permission denied writing file: {subagent_file}")
+        return None
+    except OSError as e:
+        print(f"❌ Error creating subagent file: {e}")
+        return None
+
+    return subagent_file
+
+
+def print_next_steps(subagent_name: str, subagent_file: Path) -> None:
+    """Print follow-up instructions after successful creation."""
+    print(f"\n✅ Subagent '{subagent_name}' initialized successfully")
+    print("\n⚠️  IMPORTANT: This is a template with [TODO] placeholders.")
+    print("   Before using this subagent, you MUST:")
+    print("   1. Research actual best practices for this domain (don't use generic personas)")
+    print("   2. Replace all [TODO] sections with specific, research-based content")
+    print("   3. Add concrete examples with <example> tags in description")
+    print("   4. Test the subagent with sample tasks")
+    print(f"\n   Edit the file: {subagent_file}")
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description='Create a new subagent file from template',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  init_subagent.py code-reviewer --path ~/.claude/agents
+  init_subagent.py security-auditor --path ~/.claude/agents
+  init_subagent.py data-analyzer --path ~/.claude/agents
+
+Subagent name requirements:
+  - Hyphen-case identifier (e.g., 'code-reviewer')
+  - Lowercase letters, digits, and hyphens only
+  - Max 40 characters
+  - Will create: <name>.md file
+
+Note: Subagents are stored as individual .md files in ~/.claude/agents/
+        """
+    )
+    parser.add_argument('subagent_name', help='Name of the subagent to create')
+    parser.add_argument('--path', required=True,
+                       help='Directory path where the subagent file should be created')
+
+    args = parser.parse_args()
+
+    print(f"🚀 Initializing subagent: {args.subagent_name}")
+    print(f"   Location: {args.path}\n")
+
+    result = init_subagent(args.subagent_name, args.path)
+
+    if result:
+        print_next_steps(args.subagent_name, result)
+        return 0
+    else:
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())