ma-agents 1.2.0 → 1.4.0

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,211 @@
+# 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 `skill.json` metadata file, a `SKILL.md` instruction file, and optional bundled resources:
+
+```
+skill-name/
+├── skill.json (required)
+│   ├── name: (required)
+│   ├── description: (required)
+│   ├── version: (required)
+│   ├── author: (optional)
+│   └── tags: (optional)
+├── SKILL.md (required) - Pure Markdown instructions, NO frontmatter
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    ├── examples/         - Sample outputs showing expected format
+    ├── hooks/            - Git hooks or other hook scripts
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### skill.json (required - single source of truth)
+
+Contains all metadata. The installer reads this to list skills and automatically injects YAML frontmatter (`name`, `description`) into the installed SKILL.md at install time. You never write frontmatter manually in `.md` files.
+
+```json
+{
+  "name": "My Skill",
+  "description": "What this skill does and when to use it",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "tags": ["category", "keywords"]
+}
+```
+
+The `description` field is critical — it determines when the skill triggers. Include both what the skill does AND specific triggers/contexts.
+
+#### SKILL.md (required)
+
+Pure Markdown instructions — no YAML frontmatter. Only loaded AFTER the skill triggers based on the description in `skill.json`.
+
+#### 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.json, SKILL.md template, example resource directories, and placeholder files.
+
+### Step 4: Edit the Skill
+
+**Writing guideline:** Always use imperative/infinitive form.
+
+**Update skill.json:**
+- `name`: The skill display name
+- `description`: Include both what the skill does AND specific triggers/contexts for when to use it
+- `version`: Semantic version (e.g., "1.0.0")
+
+**Update SKILL.md (pure Markdown, no frontmatter):**
+- 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/skills/skill-creator/claude-code.md

@@ -1,8 +1,3 @@
----
-name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
----
-
 # Skill Creator
 
 ## Description
@@ -34,15 +29,18 @@ Follow these steps in order:
 
 ```
 skill-name/
-├── SKILL.md (required — YAML frontmatter + markdown body)
+├── skill.json (required — single source of truth for metadata)
+├── SKILL.md (required — pure Markdown, no frontmatter)
 ├── scripts/          (executable code, Python/Bash)
 ├── references/       (documentation loaded into context as needed)
+├── examples/         (sample outputs showing expected format)
+├── hooks/            (git hooks or other hook scripts)
 └── assets/           (files used in output: templates, images, fonts)
 ```
 
-### SKILL.md Frontmatter
+### skill.json (metadata)
 
-Only `name` and `description` are required. Description is the primary trigger mechanism — include both what the skill does AND when to use it.
+Contains `name`, `description`, `version`, `author`, `tags`. The `description` is the primary trigger mechanism — include both what the skill does AND when to use it. The installer automatically injects YAML frontmatter from skill.json into the installed SKILL.md.
 
 ### Bundled Resources
 

package/skills/skill-creator/generic.md

@@ -1,8 +1,3 @@
----
-name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
----
-
 # Skill Creator
 
 This skill provides guidance for creating effective skills.

package/skills/test-generator/SKILL.md

@@ -0,0 +1,61 @@
+# 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/skills/vercel-react-best-practices/SKILL.md

@@ -0,0 +1,105 @@
+# 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

package/skills/verify-hardened-docker-skill/SKILL.md

@@ -1,8 +1,3 @@
----
-name: verify-hardened-docker
-description: Comprehensive security verification for Docker configurations. Checks Dockerfile, docker-compose.yml, and running containers against CIS Docker Benchmark, OWASP, and NIST SP 800-190 standards. Scans for vulnerabilities, leaked secrets, insecure configurations, and missing hardening controls.
----
-
 # Verify Hardened Docker
 
 ## Overview