ma-agents 1.3.0 → 1.5.0

package/skills/logging-best-practices/SKILL.md

@@ -0,0 +1,46 @@
+# Logging Best Practices
+
+Enforce structured, context-rich logging according to market standards (OpenTelemetry) across all application domains.
+
+## Policy
+
+**All logs must be structured (preferably JSON) and include mandatory context. Every exception MUST be logged with its full stack trace.**
+
+## Core Mandatory Fields
+
+Every log entry must contain:
+- `datetime`: ISO 8601 timestamp with timezone.
+- `severity`: Standard level (DEBUG, INFO, WARN, ERROR, CRITICAL).
+- `message`: Clear, concise description of the event.
+- `placement`: File name and line number where the log was triggered.
+- `process_name`: Name of the service or application.
+- `container_id`: (If applicable) Docker/K8s container identifier.
+- `trace_id` / `span_id`: For distributed tracing and request correlation.
+
+## Domain-Specific Requirements
+
+### 1. Backend Systems
+- **Log**: Incoming/outgoing requests (method, status, duration).
+- **Log**: Database query latencies and connection states.
+- **Mandatory**: Full exception details in catch blocks.
+
+### 2. Frontend Applications
+- **Log**: Client-side errors (JS runtime, UI crashes).
+- **Log**: User interaction context (last clicked component, breadcrumbs).
+- **Context**: Browser version, OS, Resolution.
+
+### 3. Realtime & Algorithmic Work
+- **Log**: Iteration throughput and step-by-step latency.
+- **Log**: Mathematical anomalies or convergence failures.
+- **Mandatory**: Timeout exceptions and resource exhaustion warnings.
+
+## Rules
+
+- **No PII/Secrets**: Never log passwords, keys, or private user data.
+- **Asynchronous**: Prefer non-blocking logging to maintain performance.
+- **Traceability**: Always include `trace_id` in logs that are part of a request flow.
+- **Exception Policy**: Use the `ERROR` level for caught exceptions that affect flow, and `CRITICAL` for system-wide failures.
+
+## Reference
+
+See [logging-standards.md](./references/logging-standards.md) for detailed field definitions and level guidance.

package/skills/logging-best-practices/examples/cpp.md

@@ -0,0 +1,36 @@
+# C++ Logging Examples
+
+## Structured Logging with `spdlog`
+
+```cpp
+#include "spdlog/spdlog.h"
+#include "spdlog/sinks/stdout_color_sinks.h"
+#include <exception>
+
+void run_realtime_loop() {
+    auto logger = spdlog::get("realtime_logger");
+    
+    try {
+        // Realtime/Algorithmic domain logging
+        logger->info("Computation step started. Input size: {}. Placement: {}:{}", 
+                     1024, __FILE__, __LINE__);
+        
+        if (check_anomaly()) {
+            logger->warn("Numerical anomaly detected! Severity: WARN");
+        }
+        
+    } catch (const std::exception& e) {
+        // Mandatory Exception Logging
+        logger->critical("Critical failure in realtime loop! Error: {}. File: {}. Line: {}", 
+                        e.what(), __FILE__, __LINE__);
+        throw;
+    }
+}
+
+// Global setup for JSON output
+void setup_logging() {
+    // Note: spdlog requires a custom formatter or sink for pure JSON output 
+    // to match OTel standards perfectly.
+    spdlog::set_pattern("{\"datetime\":\"%Y-%m-%dT%H:%M:%SZ\",\"severity\":\"%l\",\"message\":\"%v\",\"process_name\":\"engine_v1\"}");
+}
+```

package/skills/logging-best-practices/examples/csharp.md

@@ -0,0 +1,49 @@
+# C# Logging Examples
+
+## Structured Logging with Serilog
+
+```csharp
+using Serilog;
+using System;
+
+public class DataService
+{
+    private readonly ILogger _logger = Log.ForContext<DataService>();
+
+    public void ProcessAlgorithm(double[] data)
+    {
+        try
+        {
+            _logger.Information("Algorithm iteration started. Data points: {Count}. Placement: {Placement}", 
+                data.Length, "DataService.cs:45");
+
+            // Realtime/Algorithmic specific logging
+            var startTime = DateTime.UtcNow;
+            RunComplexMath(data);
+            var duration = (DateTime.UtcNow - startTime).TotalMilliseconds;
+
+            _logger.Information("Iteration complete. Latency: {Latency}ms", duration);
+        }
+        catch (Exception ex)
+        {
+            // Mandatory Exception Logging
+            _logger.Error(ex, "Algorithm execution failed at {Placement}. Container: {ContainerId}", 
+                "DataService.cs:55", Environment.GetEnvironmentVariable("HOSTNAME"));
+        }
+    }
+}
+```
+
+## Microsoft.Extensions.Logging (JSON Console)
+
+```csharp
+// In Program.cs
+builder.Logging.AddJsonConsole(options => {
+    options.TimestampFormat = "yyyy-MM-ddTHH:mm:ssZ ";
+    options.JsonWriterOptions = new JsonWriterOptions { Indented = true };
+});
+
+// Usage
+_logger.LogError(exception, "Request failed at {Placement}. TraceId: {TraceId}", 
+    "OrderController.cs:120", HttpContext.TraceIdentifier);
+```

package/skills/logging-best-practices/examples/javascript.md

@@ -0,0 +1,77 @@
+# JavaScript/TypeScript Logging Examples
+
+## Backend (Node.js with `pino` or `winston`)
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => {
+      return { severity: label.toUpperCase() };
+    },
+  },
+  base: {
+    process_name: 'api-gateway',
+    container_id: process.env.HOSTNAME || 'unknown'
+  }
+});
+
+async function handleRequest(req, res) {
+  const traceId = req.headers['x-trace-id'];
+  try {
+    logger.info({ 
+      msg: 'Handling incoming request', 
+      trace_id: traceId,
+      path: req.path,
+      placement: 'router.ts:12'
+    });
+    
+    // ... logic
+  } catch (error) {
+    // Mandatory Exception Logging
+    logger.error({
+      msg: 'Request handler failed',
+      trace_id: traceId,
+      err: error, // Pino automatically formats the stack trace
+      severity: 'ERROR',
+      placement: 'router.ts:25'
+    });
+    res.status(500).send('Internal Server Error');
+  }
+}
+```
+
+## Frontend (Browser)
+
+```javascript
+const logToServer = async (logEntry) => {
+  try {
+    await fetch('/api/logs', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...logEntry,
+        datetime: new Date().toISOString(),
+        browser: navigator.userAgent,
+        process_name: 'frontend-spa'
+      })
+    });
+  } catch (e) {
+    console.error('Failed to ship logs', e);
+  }
+};
+
+// Global error handler
+window.onerror = function(msg, url, lineNo, columnNo, error) {
+  logToServer({
+    severity: 'ERROR',
+    message: msg,
+    placement: `${url}:${lineNo}`,
+    exception: {
+      message: error?.message,
+      stack: error?.stack
+    }
+  });
+};
+```

package/skills/logging-best-practices/examples/python.md

@@ -0,0 +1,57 @@
+# Python Logging Examples
+
+## Structured Logging with `structlog`
+
+```python
+import structlog
+import os
+
+logger = structlog.get_logger()
+
+def process_data(data):
+    try:
+        # Algorithmic step logging
+        logger.info("calculation_step_started",
+                    step="matrix_multiplication",
+                    data_size=len(data),
+                    placement="processor.py:45")
+        
+        result = perform_complex_math(data)
+        return result
+    except Exception as e:
+        # Mandatory Exception Logging
+        logger.error("calculation_failed",
+                     exception_type=type(e).__name__,
+                     exception_msg=str(e),
+                     stack_trace=True, # structlog captures this
+                     severity="ERROR",
+                     placement="processor.py:52",
+                     container_id=os.getenv("HOSTNAME"))
+        raise
+```
+
+## Standard Library with JSON Formatter
+
+```python
+import logging
+import json
+from datetime import datetime
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record):
+        log_entry = {
+            "datetime": datetime.utcnow().isoformat(),
+            "severity": record.levelname,
+            "message": record.getMessage(),
+            "placement": f"{record.filename}:{record.lineno}",
+            "process_name": record.processName,
+            "trace_id": getattr(record, 'trace_id', 'none')
+        }
+        if record.exc_info:
+            log_entry["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_entry)
+
+# usage
+logger = logging.getLogger("backend_service")
+logger.error("Database connection failed", exc_info=True)
+```

package/skills/logging-best-practices/references/logging-standards.md

@@ -0,0 +1,29 @@
+# Logging Standards Reference
+
+This document defines the semantic conventions and levels used in the Logging Best Practices skill.
+
+## Log Levels
+
+| Level | Usage |
+| :--- | :--- |
+| **TRACE** | Fine-grained informational events (mostly for debugging logic flows). |
+| **DEBUG** | Detailed information for developer troubleshooting. |
+| **INFO** | Regular operational events (startup, shutdown, successful requests). |
+| **WARN** | Potential issues or degraded states that don't stop the service. |
+| **ERROR** | Operational failures that affect a specific request or operation. |
+| **CRITICAL** | System-wide failures requiring immediate attention. |
+
+## OpenTelemetry Semantic Conventions
+
+To ensure interoperability, use the following field names where possible:
+
+- `timestamp`: The time when the event occurred.
+- `severity_text`: The string representation of the log level.
+- `body`: The primary log message.
+- `attributes.service.name`: The value of `process_name`.
+- `attributes.container.id`: The value of `container_id`.
+- `attributes.code.filepath`: Path to the source file.
+- `attributes.code.lineno`: Line number in the source file.
+- `attributes.exception.type`: Class name of the exception.
+- `attributes.exception.message`: Message from the exception.
+- `attributes.exception.stacktrace`: Full stack trace.

package/skills/logging-best-practices/skill.json

@@ -0,0 +1,13 @@
+{
+    "name": "Logging Best Practices",
+    "description": "Standardizes structured logging across Backend, Frontend, Realtime, and Algorithmic domains with mandatory exception handling.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "logging",
+        "observability",
+        "json",
+        "opentelemetry",
+        "quality"
+    ]
+}

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-accompanied-development/SKILL.md

@@ -0,0 +1,39 @@
+# 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
+
+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..."

package/skills/test-accompanied-development/skill.json

@@ -0,0 +1,12 @@
+{
+    "name": "Test-Accompanied Development",
+    "description": "Enforces writing unit tests for every new public method created by the agent.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "testing",
+        "quality",
+        "policy",
+        "tdd"
+    ]
+}

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();
+  });
+});
+```