ma-agents 2.19.2 → 2.20.0

package/.cursor/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/.cursor/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()

package/.cursor/skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import re
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+from pathlib import Path
+
+
+def 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
+    if yaml is None:
+        # Fallback: basic key-value parsing if PyYAML not installed
+        frontmatter = {}
+        for line in frontmatter_text.strip().split('\n'):
+            if ':' in line:
+                key, _, value = line.partition(':')
+                frontmatter[key.strip()] = value.strip()
+    else:
+        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', 'compatibility'}
+
+    # Check for unexpected properties
+    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"
+
+    # Validate name
+    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:
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be kebab-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"
+        if len(name) > 64:
+            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+    # 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:
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+    # Validate compatibility if present
+    compatibility = frontmatter.get('compatibility', '')
+    if compatibility:
+        if not isinstance(compatibility, str):
+            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
+        if len(compatibility) > 500:
+            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 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)

package/.cursor/skills/test-accompanied-development/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Test-Accompanied Development
+description: Enforces writing unit tests for every new public method created by the agent.
+---
+# Test-Accompanied Development (TAD)
+
+Enforce a "Test-Alongside" policy where every public method is accompanied by a corresponding unit test.
+
+## Purpose
+
+To ensure high code quality and maintainability by mandating that all public interfaces are verified by automated tests at the moment of creation.
+
+## Policy
+
+**Every new public method/function you write MUST be accompanied by at least one unit test.**
+
+## When to Use
+
+- Use this skill **every time** you are about to write a new public method or function.
+- This skill should be active during the coding phase of any feature or bug fix.
+
+## Instructions
+
+1.  **Identify Public Exports**: When preparing to write a new class, module, or function, identify which methods will be public/exported.
+2.  **Plan the Test**: Before or immediately after writing the method signature, plan the corresponding test cases (Happy Path, Edge Cases, Error Cases).
+3.  **Write the Method**: Implement the public method.
+4.  **Write the Tests**: Immediately write the unit tests for the method. 
+    - Refer to the `test-generator` skill for best practices on how to structure these tests (AAA pattern, Mocking, etc.).
+    - Ensure tests are placed in the appropriate test directory of the project.
+5.  **Verify**: Run the tests to ensure they pass before considering the method "done".
+
+## Rules
+
+- **No Public Method without Tests**: Do not consider a public method complete until its corresponding test file exists and passes.
+- **Refer to Test Generator**: Use the `test-generator` skill as the standard for test quality and structure.
+- **Traceability**: Mention the test file location when adding the public method.
+
+## Example Workflow
+
+### TypeScript (Jest)
+1.  **Agent**: "I am adding a `calculateTotal` method to the `InvoiceService`. I will also create `InvoiceService.test.ts` to verify it."
+2.  **Agent**: [Writes `calculateTotal` in `InvoiceService.ts`]
+3.  **Agent**: [Writes tests in `InvoiceService.test.ts` using `test-generator` patterns]
+4.  **Agent**: "Method and tests are complete. Running tests now..."
+
+### Python (Pytest)
+1.  **Agent**: "I am adding a `validate_user` function to `auth.py`. I will also create `tests/test_auth.py` to verify it."
+2.  **Agent**: [Writes `validate_user` in `auth.py`]
+3.  **Agent**: [Writes tests in `tests/test_auth.py` using `test-generator` patterns]
+4.  **Agent**: "Implementation and tests are ready. Running `pytest`."

package/.cursor/skills/test-generator/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: Test Generator
+description: Generates comprehensive unit and integration tests
+---
+# Test Generator
+
+Generate comprehensive unit and integration tests for code.
+
+## Process
+
+1. **Analyze**: Understand code purpose, paths, dependencies, edge cases
+2. **Framework**: Determine or ask for testing framework
+3. **Generate**: Create test cases covering:
+   - Happy path (normal behavior)
+   - Edge cases (boundaries, empty/null inputs)
+   - Error cases (invalid inputs, exceptions)
+   - Integration scenarios (if applicable)
+
+## Test Structure (AAA Pattern)
+
+```
+- Arrange: Setup test data
+- Act: Execute code
+- Assert: Verify results
+```
+
+## Coverage Goals
+
+- 80%+ code coverage
+- All public methods
+- All conditional branches
+- Positive and negative cases
+
+## Best Practices
+
+- One assertion per test
+- Independent tests
+- Descriptive test names
+- Mock external dependencies
+- Clear assertion messages
+
+## Example Output
+
+```javascript
+describe('ComponentName', () => {
+  test('should [behavior] when [condition]', () => {
+    // Arrange
+    const input = setupTestData();
+
+    // Act
+    const result = functionUnderTest(input);
+
+    // Assert
+    expect(result).toEqual(expectedOutput);
+  });
+
+  test('should handle edge case', () => {
+    // ...
+  });
+
+  test('should throw on invalid input', () => {
+    expect(() => fn(invalid)).toThrow();
+  });
+});
+```

package/.cursor/skills/vercel-react-best-practices/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: Vercel React Best Practices
+description: Performance optimization framework for React and Next.js projects with 57 actionable rules across 8 categories
+---
+# Vercel React Best Practices
+
+A thorough performance optimization framework for React and Next.js projects. Contains 57 actionable rules organized into 8 categories, ranked by potential impact.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components
+- Implementing data fetching
+- Reviewing code for performance concerns
+- Refactoring existing applications
+- Reducing bundle sizes and load times
+
+## Rule Categories (Priority-Ordered)
+
+### 1. Eliminating Waterfalls (CRITICAL)
+Prefix: `async-`
+
+- Avoid sequential data fetching — use parallel requests (`Promise.all`, `Promise.allSettled`)
+- Prefetch data at the layout/page level rather than in deeply nested components
+- Use `loading.tsx` and `Suspense` boundaries to stream content progressively
+- Avoid `await` chains where requests don't depend on each other
+- Colocate data fetching with the component that uses the data, but fetch in parallel at the route level
+- Use React Server Components to move data fetching to the server and eliminate client-server waterfalls
+
+### 2. Bundle Size Optimization (CRITICAL)
+Prefix: `bundle-`
+
+- Prefer `next/dynamic` or `React.lazy` for heavy components not needed on initial load
+- Audit dependencies with `@next/bundle-analyzer` — remove or replace bloated packages
+- Use tree-shakeable libraries and import only what you need (`import { x } from 'lib'` not `import lib from 'lib'`)
+- Mark client components with `'use client'` only at the lowest necessary level
+- Avoid importing server-only code into client components
+- Use `next/image` instead of raw `<img>` tags for automatic optimization
+- Use `next/font` to self-host fonts and eliminate external font requests
+
+### 3. Server-Side Performance (HIGH)
+Prefix: `server-`
+
+- Default to React Server Components — only add `'use client'` when interactivity is needed
+- Use the `cache()` function to deduplicate identical requests within a single render
+- Leverage `unstable_cache` or `fetch` cache options for cross-request caching
+- Set proper `revalidate` values — avoid `revalidate: 0` unless data truly changes on every request
+- Use `generateStaticParams` for static generation of dynamic routes
+- Move database queries and API calls to Server Components or Route Handlers
+- Use streaming (`loading.tsx`, `Suspense`) to avoid blocking the entire page on slow data
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+Prefix: `client-`
+
+- Use SWR or React Query for client-side data fetching with caching, revalidation, and deduplication
+- Implement optimistic updates for mutations to improve perceived performance
+- Set appropriate `staleTime` and `cacheTime` to avoid unnecessary refetches
+- Use `prefetchQuery` or `preload` to start fetching before navigation
+- Avoid `useEffect` + `fetch` patterns — prefer dedicated data fetching libraries
+- Paginate or infinitely scroll large datasets instead of loading everything at once
+
+### 5. Re-render Optimization (MEDIUM)
+Prefix: `rerender-`
+
+- Lift state up only as far as necessary — keep state close to where it's used
+- Split contexts to avoid triggering unnecessary re-renders on unrelated state changes
+- Use `useMemo` and `useCallback` only for expensive computations or stable references passed to memoized children
+- Avoid creating new objects/arrays in render — extract them as constants or memoize them
+- Use `React.memo` for pure components that re-render often with the same props
+- Prefer `useRef` over `useState` for values that don't need to trigger re-renders
+- Avoid prop drilling — use composition (`children` prop) instead of deep prop chains
+
+### 6. Rendering Performance (MEDIUM)
+Prefix: `rendering-`
+
+- Virtualize long lists with `react-window` or `@tanstack/virtual`
+- Debounce rapid user inputs (search, resize, scroll handlers)
+- Use CSS for animations and transitions instead of JS-driven re-renders
+- Use `content-visibility: auto` for off-screen content
+- Avoid layout thrashing — batch DOM reads and writes
+- Use `will-change` sparingly and only on elements that will actually animate
+- Prefer `transform` and `opacity` for GPU-accelerated animations
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+Prefix: `js-`
+
+- Avoid blocking the main thread — use `requestIdleCallback` or Web Workers for heavy computation
+- Use `Map` and `Set` for frequent lookups instead of arrays
+- Minimize closures in hot paths
+- Prefer `for...of` or `Array.prototype` methods over manual loops for readability, but use manual loops in performance-critical sections
+- Avoid deep cloning — use structural sharing (Immer) or shallow copies where possible
+- Use `AbortController` to cancel stale requests and avoid race conditions
+
+### 8. Advanced Patterns (LOW)
+Prefix: `advanced-`
+
+- Use the `Offscreen` API (when stable) for pre-rendering hidden UI
+- Implement route-level code splitting with parallel route segments
+- Use Edge Runtime for latency-sensitive API routes
+- Implement partial prerendering (PPR) for hybrid static/dynamic pages
+- Use `Server Actions` for form mutations to avoid manual API routes
+- Profile with React DevTools Profiler and Chrome Performance tab before optimizing
+
+## General Principles
+
+- **Measure before optimizing** — use Lighthouse, Web Vitals, and React DevTools
+- **Higher-priority categories yield larger gains** — focus on waterfalls and bundle size first
+- **Don't prematurely optimize** — only apply lower-priority rules after addressing critical ones
+- **Test performance changes** — verify improvements with real metrics, not just intuition