ma-agents 2.20.0 → 2.20.2

package/.gemini/skills/python-dependency-mgmt/SKILL.md

@@ -1,42 +0,0 @@
----
-name: Python Dependency Management
-description: Standardize Python dependency handling using uv and pip (requirements.txt).
----
-# Python Dependency Management (uv & pip)
-
-This skill ensures consistent and reproducible Python environments using modern tools like `uv` and traditional standards like `requirements.txt`.
-
-## Policies
-
-### 1. Modern Workflow with `uv`
-*   **Rule**: Use `uv` for lightning-fast project management if available.
-*   **Action**: 
-    - Use `uv lock` to generate `uv.lock`.
-    - Use `uv sync` to keep the environment in sync with the lockfile.
-    - Declare dependencies in `pyproject.toml`.
-*   **Rationale**: `uv` is significantly faster than `pip` and provides deterministic builds via lockfiles.
-
-### 2. Standardized `requirements.txt`
-*   **Rule**: If not using a modern manager, use a layered and pinned `requirements.txt` structure.
-*   **Action**: 
-    - **Layered**: Use `requirements.in` (top-level deps) and `requirements.txt` (fully pinned transitive deps).
-    - **Environment Split**: Separate `requirements.txt` from `dev-requirements.txt`.
-    - **Hashes**: Generate hashes for security (`--generate-hashes` via `pip-compile`).
-
-### 3. Strict Version Pinning
-*   **Rule**: All production dependencies must be pinned to a specific version.
-*   **Action**: Use `package==1.2.3`, never `package>=1.2.3` in the final lock/txt file.
-
-### 4. Virtual Environment Discipline
-*   **Rule**: Never install dependencies globally. 
-*   **Action**: 
-    - Always create a `.venv` in the project root.
-    - For `uv`, it handles this automatically with `uv venv` or implicitly via `uv run`.
-
-### 5. Standard Build Systems (PEP 517/518)
-*   **Rule**: Use `pyproject.toml` as the source of truth for build metadata.
-
-## Tools of Choice
-1. **uv**: (Recommended) Fastest all-in-one manager.
-2. **pip-tools**: For generating pinned `requirements.txt` from `.in` files.
-3. **venv**: Core standard for isolation.

package/.gemini/skills/python-dependency-mgmt/examples/dependency_mgmt.md

@@ -1,67 +0,0 @@
-# Python Dependency Management Examples
-
-### 1. Modern Workspace with `uv`
-**pyproject.toml:**
-```toml
-[project]
-name = "my-app"
-version = "0.1.0"
-dependencies = [
-    "requests==2.31.0",
-    "structlog>=24.1.0",
-]
-
-[tool.uv]
-managed = true
-```
-
-**Commands:**
-```bash
-# Add a new dependency and update lockfile
-uv add pandas
-
-# Run a script within the isolated environment
-uv run main.py
-
-# Sync environment with the lockfile
-uv sync
-```
-
-### 2. Traditional `requirements.txt` (pip-tools)
-**requirements.in:**
-```text
-flask
-psycopg2-binary
-```
-
-**Workflow:**
-```bash
-# Generate pinned requirements.txt with hashes
-pip-compile --generate-hashes requirements.in
-
-# Install exactly what is pinned
-pip install -r requirements.txt
-```
-
-### 3. Development vs Production Deps
-**dev-requirements.in:**
-```text
--c requirements.txt
-pytest
-black
-ruff
-```
-
-```bash
-# Generate dev-requirements.txt
-pip-compile dev-requirements.in
-```
-
-### 4. Virtual Environment Setup (Standard)
-```bash
-python -m venv .venv
-# Linux/macOS
-source .venv/bin/activate
-# Windows
-.venv\Scripts\activate
-```

package/.gemini/skills/python-security-skill/SKILL.md

@@ -1,56 +0,0 @@
----
-name: Python Security Best Practices
-description: Enforce secure Python coding standards following OWASP Top 10 2025.
----
-# Python Security Best Practices (OWASP 2025 aligned)
-
-This skill provides mandatory security guardrails for Python applications, ensuring protection against common vulnerabilities and alignment with OWASP Top 10 standards.
-
-## Policies
-
-### 1. Zero Insecure Function Usage
-*   **Rule**: Ban functions that allow arbitrary code execution or insecure OS commands.
-*   **Action**: 
-    - NEVER use `eval()` or `exec()`.
-    - Avoid `subprocess.run(..., shell=True)`. Use lists for commands instead.
-    - Avoid `yaml.load()` without specifying a loader (use `yaml.safe_load()`).
-
-### 2. Secure Data Serialization
-*   **Rule**: Protect against insecure deserialization.
-*   - **Action**: 
-    - NEVER use `pickle` for untrusted data. Use `json` instead.
-    - Be cautious with `xml.etree.ElementTree` (vulnerable to XXE); use `defusedxml` if possible.
-
-### 3. Injection Prevention (A05:2025)
-*   **Rule**: Use parameterized queries for all database and API interactions.
-*   **Action**: 
-    - Never use f-strings or `.format()` for SQL queries.
-    - Use ORM features (Django ORM, SQLAlchemy) or parameter placeholders (`%s`, `?`).
-
-### 4. Cryptographic Standards (A04:2025)
-*   **Rule**: Use modern, collision-resistant hashing and encryption.
-*   **Action**: 
-    - Use `hashlib.sha256()` or better. Ban MD5 and SHA1.
-    - Use `secrets` module for tokens/passwords, not `random`.
-
-### 5. Dependency Integrity (A03:2025)
-*   **Rule**: Lock dependencies and scan for known vulnerabilities.
-*   **Action**: 
-    - Always commit lockfiles (`uv.lock`, `poetry.lock`, or `requirements.txt` with hashes).
-    - Periodically run `pip-audit` or `safety`.
-
-### 6. Secure Error Handling (A10:2025)
-*   **Rule**: Do not leak sensitive information in tracebacks or logs.
-*   **Action**: 
-    - Never log `pydantic` models or raw request bodies containing PII/Secrets.
-    - Use generic error messages for end-users while keeping detailed logs internally.
-
-## Python Security Mapping (OWASP 2025)
-
-| Category | Python Vulnerability | Secure Alternative |
-| :--- | :--- | :--- |
-| **A01: Access Control** | URL hijacking in `requests` | Validate redirect targets |
-| **A02: Configuration** | Debug mode in Flask/Django | `DEBUG = False` in production |
-| **A03: Supply Chain** | Typosquatting/Old deps | Pin versions + `pip-audit` |
-| **A05: Injection** | `os.system()` / RAW SQL | `subprocess.run()` list / ORM |
-| **A08: Integrity** | `pickle.load()` | `json.loads()` |

package/.gemini/skills/python-security-skill/examples/security.md

@@ -1,56 +0,0 @@
-# Python Security Examples
-
-### 1. Secure Subprocess (Avoiding Injection)
-**Dangerous:**
-```python
-import os
-def delete_file(filename):
-    os.system(f"rm -rf {filename}") # VULNERABLE to injection
-```
-
-**Secure:**
-```python
-import subprocess
-def delete_file(filename):
-    # Pass as a list, shell=False by default
-    subprocess.run(["rm", "-rf", filename], check=True)
-```
-
-### 2. Secure Serialization
-**Dangerous:**
-```python
-import pickle
-def load_user(data):
-    return pickle.loads(data) # VULNERABLE to arbitrary code execution
-```
-
-**Secure:**
-```python
-import json
-def load_user(data):
-    return json.loads(data) # Safe for untrusted input
-```
-
-### 3. Preventing SQL Injection
-**Dangerous:**
-```python
-cursor.execute(f"SELECT * FROM users WHERE id = '{user_id}'")
-```
-
-**Secure:**
-```python
-cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
-```
-
-### 4. Secure Randomness
-**Dangerous:**
-```python
-import random
-token = str(random.random()) # Predictable
-```
-
-**Secure:**
-```python
-import secrets
-token = secrets.token_urlsafe(32) # Cryptographically secure
-```

package/.gemini/skills/self-signed-cert/SKILL.md

@@ -1,42 +0,0 @@
----
-name: Self-Signed Certificate Generator
-description: Generates secure self-signed certificates and Root CAs using OpenSSL.
----
-# Self-Signed Certificate Generator
-
-## Purpose
-Automate the creation of Root CAs and self-signed certificates for internal services, local development, and testing environments.
-
-## Instructions
-1.  **Environment Check**: Ensure `openssl` is installed and available in the PATH.
-2.  **Workflow Selection**:
-    - **Standalone Self-Signed**: Quickest for single service testing.
-    - **Root CA + Signed Cert**: Recommended for internal architectures where multiple services need to trust a single authority.
-3.  **Security Standards**:
-    - Key Size: Minimum 2048-bit (4096-bit preferred).
-    - Hashing: SHA-256 or higher.
-    - Permissions: Private keys must be set to `600`.
-
-## Rules
-- NEVER store private keys in version control.
-- ALWAYS include Subject Alternative Names (SANs) for modern browser compatibility.
-- Ensure the certificate Common Name (CN) matches the intended hostname.
-
-## Usage
-The skill provide both Bash (Linux/macOS) and PowerShell (Windows) scripts.
-
-### Linux / macOS
-Run `scripts/generate-cert.sh` with:
-- `TYPE`: `root` or `cert`
-- `NAME`: Base name for the files
-- `DNS`: Primary domain/IP
-
-Example: `bash scripts/generate-cert.sh cert my-service localhost`
-
-### Windows (PowerShell)
-Run `scripts/generate-cert.ps1` with:
-- `-Type`: `root` or `cert`
-- `-Name`: Base name
-- `-Dns`: Primary domain/IP
-
-Example: `.\scripts\generate-cert.ps1 -Type cert -Name my-service -Dns localhost`

package/.gemini/skills/self-signed-cert/scripts/generate-cert.ps1

@@ -1,45 +0,0 @@
-param (
-    [Parameter(Mandatory=$true)]
-    [ValidateSet("root", "cert")]
-    [string]$Type,
-    
-    [string]$Name = "server",
-    
-    [string]$Dns = "localhost",
-    
-    [string]$CaKey,
-    
-    [string]$CaCert
-)
-
-$ErrorActionPreference = "Stop"
-
-if ($Type -eq "root") {
-    Write-Host "Generating Root CA..." -ForegroundColor Cyan
-    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"
-    Write-Host "Root CA created: ${Name}_rootCA.crt" -ForegroundColor Green
-
-} elseif ($Type -eq "cert") {
-    if (-not $CaKey -or -not $CaCert) {
-        Write-Host "Generating standalone self-signed certificate..." -ForegroundColor Cyan
-        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 {
-        Write-Host "Generating certificate signed by CA..." -ForegroundColor Cyan
-        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
-        "subjectAltName = DNS:${Dns}" | Out-File -FilePath "${Name}.ext" -Encoding ascii
-        
-        openssl x509 -req -in "${Name}.csr" -CA "$CaCert" -CAkey "$CaKey" -CAcreateserial `
-            -out "${Name}.crt" -days 365 -sha256 -extfile "${Name}.ext"
-        
-        Remove-Item "${Name}.csr", "${Name}.ext" -ErrorAction SilentlyContinue
-    }
-    Write-Host "Certificate created: ${Name}.crt" -ForegroundColor Green
-}

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

@@ -1,43 +0,0 @@
-#!/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/.gemini/skills/skill-creator/SKILL.md

@@ -1,196 +0,0 @@
----
-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/.gemini/skills/skill-creator/references/output-patterns.md

@@ -1,82 +0,0 @@
-# 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/.gemini/skills/skill-creator/references/workflows.md

@@ -1,28 +0,0 @@
-# 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]
-```