ma-agents 3.2.0 → 3.3.0

package/.roo/skills/self-signed-cert/scripts/generate-cert.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# generate-cert.sh - Part of ma-agents self-signed-cert skill
+
+TYPE=$1
+NAME=${2:-"server"}
+DNS=${3:-"localhost"}
+
+if [ "$TYPE" == "root" ]; then
+    echo "Generating Root CA..."
+    openssl genrsa -out "${NAME}_rootCA.key" 4096
+    openssl req -x509 -new -nodes -key "${NAME}_rootCA.key" -sha256 -days 3650 -out "${NAME}_rootCA.crt" \
+        -subj "/CN=${NAME}-Root-CA/O=MA-Agents/C=US"
+    chmod 600 "${NAME}_rootCA.key"
+    echo "Root CA created: ${NAME}_rootCA.crt"
+
+elif [ "$TYPE" == "cert" ]; then
+    CA_KEY=$4
+    CA_CRT=$5
+
+    if [ -z "$CA_KEY" ] || [ -z "$CA_CRT" ]; then
+        echo "Generating standalone self-signed certificate..."
+        openssl req -x509 -newnodes -days 365 -newkey rsa:2048 \
+            -keyout "${NAME}.key" -out "${NAME}.crt" \
+            -subj "/CN=${DNS}/O=MA-Agents" \
+            -addext "subjectAltName = DNS:${DNS}"
+    else
+        echo "Generating certificate signed by CA..."
+        openssl genrsa -out "${NAME}.key" 2048
+        openssl req -new -key "${NAME}.key" -out "${NAME}.csr" -subj "/CN=${DNS}/O=MA-Agents"
+        
+        # Extension file for SAN
+        echo "subjectAltName = DNS:${DNS}" > "${NAME}.ext"
+        
+        openssl x509 -req -in "${NAME}.csr" -CA "$CA_CRT" -CAkey "$CA_KEY" -CAcreateserial \
+            -out "${NAME}.crt" -days 365 -sha256 -extfile "${NAME}.ext"
+        rm "${NAME}.csr" "${NAME}.ext"
+    fi
+    chmod 600 "${NAME}.key"
+    echo "Certificate created: ${NAME}.crt"
+else
+    echo "Usage: $0 [root|cert] [name] [dns] [ca_key] [ca_crt]"
+    exit 1
+fi

package/.roo/skills/skill-creator/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: Skill Creator
+description: Guide for creating effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations
+---
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The 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 Freedom
+
+Match 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.
+
+### Anatomy of a Skill
+
+Every 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)
+│   │   └── compatibility: (optional, rarely needed)
+│   └── 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)
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers.
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code 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
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+
+##### References (`references/`)
+
+Documentation intended to be loaded as needed into context.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information lives in either SKILL.md or references files, not both
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but used within the output Claude produces.
+
+- **When to include**: When the skill needs files for final output
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents
+
+#### What NOT to Include
+
+Do NOT create: README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, or other auxiliary documentation. The skill should only contain information needed for an AI agent to execute tasks.
+
+### Progressive Disclosure Design Principle
+
+Three-level loading system:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited)
+
+Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+## Quick start
+Extract text with pdfplumber: [code example]
+## Advanced features
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+```
+
+**Pattern 2: Domain-specific organization**
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── references/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    └── product.md (API usage, features)
+```
+
+**Pattern 3: Conditional details**
+
+```markdown
+# DOCX Processing
+## Creating documents
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+## Editing documents
+For simple edits, modify the XML directly.
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+```
+
+## Skill Creation Process
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run scripts/init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run scripts/package_skill.py)
+6. Iterate based on real usage
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Gather concrete examples of how the skill will be used. Ask users clarifying questions about functionality and triggers. Conclude when there's clear understanding of supported functionality.
+
+### Step 2: Planning the Reusable Skill Contents
+
+Analyze each concrete example:
+1. Consider how to execute the example from scratch
+2. Identify what scripts, references, and assets would be helpful for repeated execution
+
+### Step 3: Initializing the Skill
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+Creates skill directory with SKILL.md template, example resource directories, and placeholder files.
+
+### Step 4: Edit the Skill
+
+**Writing guideline:** Always use imperative/infinitive form.
+
+**Update Frontmatter:**
+- `name`: The skill name
+- `description`: Include both what the skill does AND specific triggers/contexts for when to use it
+
+**Update Body:**
+- Write instructions for using the skill and bundled resources
+- For multi-step processes: See references/workflows.md
+- For specific output formats: See references/output-patterns.md
+
+**Start with Reusable Skill Contents:**
+- Implement scripts, references, and assets first
+- Test scripts by running them
+- Delete example files not needed for the skill
+
+### Step 5: Packaging a Skill
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> [output-directory]
+```
+
+Validates and packages the skill into a distributable .skill file (zip format).
+
+### Step 6: Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

package/.roo/skills/skill-creator/references/output-patterns.md

@@ -0,0 +1,82 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS 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
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here 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 Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+````markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use 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.

package/.roo/skills/skill-creator/references/workflows.md

@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For 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:
+
+```markdown
+Filling 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 Workflows
+
+For tasks with branching logic, guide Claude through decision points:
+
+```markdown
+1. Determine the modification type:
+   **Creating new content?** → Follow "Creation workflow" below
+   **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```

package/.roo/skills/skill-creator/scripts/init_skill.py

@@ -0,0 +1,208 @@
+#!/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 sys
+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
+- 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
+- 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
+- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...
+
+Patterns can be mixed and matched as needed.
+
+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]
+
+## Resources
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly.
+
+### references/
+Documentation and reference material intended to be loaded into context as needed.
+
+### assets/
+Files not intended to be loaded into context, but used within 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. 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 here
+
+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.
+
+## When Reference Docs Are Useful
+
+- 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
+"""
+
+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.
+"""
+
+
+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.
+
+    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 = 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))
+        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"\nSkill '{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():
+    if len(sys.argv) < 4 or sys.argv[2] != '--path':
+        print("Usage: init_skill.py <skill-name> --path <path>")
+        print("\nSkill name requirements:")
+        print("  - Kebab-case identifier (e.g., 'my-data-analyzer')")
+        print("  - Lowercase letters, digits, and hyphens only")
+        print("  - Max 64 characters")
+        print("\nExamples:")
+        print("  init_skill.py my-new-skill --path skills/public")
+        print("  init_skill.py my-api-helper --path skills/private")
+        sys.exit(1)
+
+    skill_name = sys.argv[1]
+    path = sys.argv[3]
+
+    print(f"Initializing skill: {skill_name}")
+    print(f"   Location: {path}\n")
+
+    result = init_skill(skill_name, path)
+    sys.exit(0 if result else 1)
+
+
+if __name__ == "__main__":
+    main()

package/.roo/skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python package_skill.py skills/public/my-skill
+    python package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    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"\nSuccessfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python package_skill.py skills/public/my-skill")
+        print("  python package_skill.py skills/public/my-skill ./dist")
+        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()