ma-agents

v3.12.1

Published

21 hours ago

NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)

Downloads

2,572

0High
0Medium
0Low

amayafit

ai agent skills claude-code gemini copilot kilocode cline cursor roo-code npx

ma-agents

A universal NPX tool to install AI coding agent skills. Write skills once, install them across Claude Code, Gemini, Copilot, Cline, Cursor, Kilocode, and Roo Code.

What's New in v3.12.0

Cline .clinerules directory fix — .clinerules is now correctly created as a directory (matching Cline's native structure), not as a file. This prevents ENOTDIR errors during workflow generation and ensures .clinerules/workflows/ is always generated correctly. Legacy installs that had .clinerules as a file are automatically migrated on the next install or update.

What's New in v3.11.0

Cline workflow generation — when Cline is selected during install, update, or migration, ma-agents now auto-generates .clinerules/workflows/<skill-name>.md for every BMAD skill installed to .cline/skills/. Type / in Cline chat to browse and invoke all BMAD skills natively.

What's New in v3.10.0

Jira backend first-run fix — the Jira backend is now correctly detected and activated on the very first run after install, resolving a bug where tracking_system was ignored until a second invocation.
BMAD v6.6.0 — bundled bmad-method updated to v6.6.0.

What's New in v3.9.0

Jira sprint backend — the install wizard now offers Jira as a 4th sprint management option. Select Jira to provide your Jira URL and project key; credentials are stored in _bmad/bmm/config.yaml. All 13 sprint management skills automatically route operations to Jira or file-system based on tracking_system in sprint-status.yaml.
Skill-level Jira routing — every sprint skill reads tracking_system and routes to the Jira backend via whatever Jira-capable tool is available in your agent context (MCP server, plugin, or native integration). Failure prompts offer retry or permanent switch to file management.
Routing alignment (3.8.1) — copilot, roo-code, and kilocode persona skills now land in .agents/skills/ to match bmad-method 6.5.0's unified target directory.

See CHANGELOG.md for full release notes.

Installation & Usage

ma-agents is designed to be run via npx in the root of your project.

1. Interactive Wizard (Recommended)

The wizard is the easiest way to set up or update your environment.

npx ma-agents

2. Direct Command Line

# Install specific skills to specific agents
npx ma-agents install code-review claude-code copilot

# Global installation (user-level)
npx ma-agents install code-review claude-code --global

# CI/CD: skip all prompts, use defaults
npx ma-agents install --yes

# Scope the entire install to one agent (skills, BMAD update, instruction block)
npx ma-agents install --yes --agent claude-code

How It Works

Skills are written in a unified generic format and stored in this package. When you install a skill, the installer:

Reads the skill's SKILL.md (or agent-specific template if available)
Injects YAML frontmatter from skill.json (the single source of metadata)
Copies the skill and its resources into the target agent's directory
Renames resource directories to match the agent's native structure (e.g., references/ becomes docs/ for Cline)
Generates MANIFEST.yaml: A central discovery file for the agent to find all installed skills.
Updates Instruction Blocks: Stamps a universal planning-instruction block into every agent's instruction file (CLAUDE.md, .clinerules, .cline/clinerules.md, .roo/rules/00-ma-agents.md, AGENTS.md) between  /  markers. User content outside the markers is preserved. On-prem profile additionally stamps guardrails for local LLMs.
BMAD Roo Code Modes: Generates .roomodes with 4 BMAD planning-mode custom modes (bmad-pm, bmad-architect, bmad-techlead, bmad-dev), each with fileRegex restrictions that enforce planning-phase file access at the application layer.
BMAD-METHOD Integration: Automatically detects and integrates with BMAD-METHOD, applying project-specific customizations and orchestration.

Generic (this repo)                    Installed Output
───────────────────                    ────────────────
skills/code-review/
├── skill.json        ──────────►     Injected as YAML frontmatter
├── SKILL.md          ──────────►     .claude/skills/code-review/SKILL.md
├── scripts/          ──────────►     .claude/skills/code-review/scripts/
└── references/       ──────────►     .claude/skills/code-review/references/
                                       + Generated MANIFEST.yaml
                                       + Updated Agent Instructions (CLAUDE.md, etc.)

Project Knowledge: _bmad-output/

The _bmad-output/ folder is intentionally tracked in version control as project knowledge. Do not add _bmad-output/ to your .gitignore.

What it contains

_bmad-output/ holds all AI-generated planning artifacts produced by BMAD agents:

planning-artifacts/ — PRDs, architecture documents, UX designs
implementation-artifacts/ — Epics, user stories, sprint status, backlog
- sprint-status.yaml — Unified single source of truth for all sprint and backlog state (epics map, backlog array, sprints map)
- done/ — Archived completed and cancelled stories and bugs
methodology/ — BMAD-METHOD training materials and onboarding presentation

Why it is version-controlled

Team alignment — all team members see the same AI-generated plans and decisions
AI context continuity — AI agents need prior context across sessions to maintain consistency
Decision history — preserves the rationale and evolution of architectural and product decisions

Installer behaviour

The ma-agents installer automatically removes _bmad-output/ from .gitignore if it finds it there. This is intentional — if your IDE or tooling suggests adding _bmad-output/ to .gitignore, you should decline. The folder is project knowledge, not build artefacts.

Do not add _bmad-output/ to your .gitignore — the installer will remove it automatically if it appears there.

Project Context

When you run npx ma-agents install at the project level, ma-agents automatically generates _bmad-output/project-context.md — a constitutional document that governs how AI agents behave in this project.

What it contains:

Mandatory pre-task rules: which MANIFEST.yaml files to read, which skills to load
Git workflow mandate: fresh worktrees per mission (not just branches)
Agent mission lifecycle: 8-step sequence from pre-flight to post-mission cleanup

It is safe to edit. The installer never regenerates the file from scratch once it exists. On reinstall, only the ## AI Agent Mandatory Rules MANIFEST paths section is updated if new agents have been added — all your custom edits are preserved. Edit it freely — it belongs to your project.

Expand it over time:

After architecture phase: run /bmad-generate-project-context to auto-detect your stack
After each sprint: run /bmad-retrospective, then /project-context-expansion
Manually: add conventions you notice agents getting wrong

The file is version-controlled as part of _bmad-output/ project knowledge. Commit it.

On-Prem / Air-Gapped Deployment

When running AI coding agents against a locally-hosted LLM (e.g., Nemotron Super 49B on vLLM), ma-agents install asks a one-time profile question at setup:

? Profile (standard / on-prem):

Your answer is persisted in .ma-agents.json under the profile field and is read on every subsequent install, update, or reconfigure. The manifest also records the toolVersion (ma-agents version) and bmadVersion (bundled bmad-method version) on every install, making it easy to verify what ran last. The standard profile produces the same output as always; the on-prem profile additionally stamps on-prem-specific guardrails into every agent's instruction block — including /no_think directives for planning personas, str_replace_editor prohibition, and home-directory write restrictions.

To change your profile after initial setup: npx ma-agents reconfigure To remove all on-prem profile artifacts: npx ma-agents uninstall --profile-artifacts

What the on-prem profile stamps

| File | What is added | |------|--------------| | CLAUDE.md | Universal instruction block + on-prem guardrails (inside MA-AGENTS-START/END markers) | | .roo/rules/00-ma-agents.md | Same block for Roo Code | | .clinerules + .cline/clinerules.md | Same block for Cline | | AGENTS.md | Same block for OpenCode | | opencode.json | Additive entry in instructions[] array | | .roomodes | 4 BMAD planning modes with fileRegex phase enforcement | | Deployed bmad-agent-*/SKILL.md (across .claude/skills/, .cline/skills/, .github/skills/, .roo/skills/, .kilocode/skills/) | Per-persona phase prefix injected via marker block: planning personas get /no_think; dev personas get careful-coding prefix |

The standard profile stamps the universal block only (no /no_think, no str_replace_editor prohibition, no home-dir restriction).

For vLLM server configuration, quantization tradeoffs, per-phase sampling parameters, and the str_replace_editor hallucination mitigation, see docs/deployment/vllm-nemotron.md.

Supported Coding Tools

Skills can be installed into any of these AI coding agents:

| Tool | Project Path | Template | Instruction File | |------|-------------|----------|------------------| | Claude Code | .claude/skills/ | claude-code | .claude/CLAUDE.md | | Google Gemini | .gemini/skills/ | generic | .gemini/gemini.md | | GitHub Copilot | .github/skills/ | generic | .github/copilot/copilot.md | | Cursor | .cursor/skills/ | generic | .cursor/cursor.md | | Kilocode | .kilocode/skills/ | generic | .kilocode/kilocode.md | | Cline | .cline/skills/ | cline | .cline/clinerules.md | | Roo Code | .roo/skills/ | generic | .roo/rules/00-ma-agents.md | | Antigravity | _bmad/skills/ | generic | _bmad/bmm/agents/antigravity.md | | OpenCode | .opencode/skills/ | generic | opencode.json |

Specialized BMAD Agents

These domain-expert agents are installed alongside BMAD-METHOD and provide guided workflows through their agent menus:

| Agent | Persona | Skills Path | Instruction File | |-------|---------|-------------|------------------| | SRE Agent | Alex | _bmad/skills/sre/ | _bmad/bmm/agents/sre.md | | DevOps Agent | Amit | _bmad/skills/devops/ | _bmad/bmm/agents/devops.md | | Cyber Analyst | Yael | _bmad/skills/cyber/ | _bmad/bmm/agents/cyber.md | | ML Scientist | Demerzel | _bmad/skills/demerzel/ | _bmad/bmm/agents/demerzel.md | | SQA & Standards Expert | Gad | _bmad/skills/sqa/ | _bmad/bmm/agents/qa.md |

Available Skills

General-Purpose Skills (34)

These skills are installed into your coding tool of choice and provide reusable best-practice guidance:

Agent Workflows (34)

These workflows are installed as part of the BMAD agent system and are invoked through the agent's menu (not installed individually):

Automated Skill Discovery

ma-agents features an automated discovery system that ensures installed skills are actually used by the agent without manual configuration.

1. The Manifest (`MANIFEST.yaml`)

Every installation automatically generates a MANIFEST.yaml in the skills directory. It contains:

Skill IDs and Paths: Where to find the instructions.
applies_when Conditions: Hints about when a skill should be loaded (e.g., "when writing public APIs").
always_load Flags: Mandatory skills that should always be in context.

2. Instruction Injection

The installer automatically updates agent-specific instruction files (like CLAUDE.md or .clinerules) with a "Planning Instruction" block. This block tells the agent to:

Consult the MANIFEST.yaml before starting a task.
Select and read only the relevant skills for the current context.

CLI Usage

npx ma-agents                              # Launch interactive wizard
npx ma-agents install                      # Interactive install wizard
npx ma-agents install --yes                # Non-interactive, use defaults (CI/CD)
npx ma-agents install --yes --agent <id>   # Non-interactive, target one agent
npx ma-agents install --log                # Log all output to install_<datetime>.log
npx ma-agents status                       # Show installed skills and paths
npx ma-agents list                         # List all available skills
npx ma-agents agents                       # List supported agents
npx ma-agents uninstall <skill> <agents>   # Direct uninstall
npx ma-agents reconfigure               # Re-run profile prompt and re-stamp all artifacts
npx ma-agents uninstall --profile-artifacts  # Remove on-prem profile content from all agent files

The Update Process

Running ma-agents on a project where skills are already installed triggers the Update Flow:

Detection: Recognizes existing .ma-agents.json manifest.
Selection: Allows you to add new skills or remove existing ones.
Synchronization:
- Re-injects the latest instructions into CLAUDE.md, .clinerules, etc.
- Regenerates the MANIFEST.yaml to reflect the current skill set.
- Updates BMAD-METHOD personas and workflows to the latest versions if detected.
- Cleans up stale tool directories — if a tool's skill path changed between releases (e.g., Copilot migrated from .github/copilot/skills/ to .github/skills/), the old directory is automatically removed when the new one has content.

BMAD-METHOD Integration

ma-agents bundles BMAD-METHOD v6.5.0 to provide advanced orchestration and specialized personas.

Core Features

Auto-Detection: Recognizes existing BMAD installations and prompts for silent updates.
Silent Setup: Non-interactive installation/update of BMAD tailored to your project's agents.
Plugin Staging: A pre-built plugin bundle (lib/bmad-extension-plugin/) is staged into <project>/.ma-agents-plugin-stage/ and installed via bmad-method --custom-source, replacing the legacy post-install manifest-surgery flow.
Persona Overlays: On-prem phase prefixes and user customizations are injected as marker-delimited blocks into the deployed bmad-agent-*/SKILL.md files across every supported tool's skills directory — idempotent on re-runs.
Advanced Agent Templates: Deploys full XML-structured agent definitions directly into the BMAD system.

Bundled & Offline Installation (v2.20+)

ma-agents ships with everything needed to install BMAD without any network access at install time:

bmad-method is a direct npm dependency — no runtime npx bmad-method fetch required. The correct version is pinned and bundled inside node_modules/ when you npm install ma-agents.
External modules pre-bundled — lib/bmad-cache/ ships the 4 optional BMAD modules (bmb, cis, gds, tea) inside the package itself. They are pre-populated to ~/.bmad/cache/external-modules/ before any install runs, so BMAD never needs to clone them from GitHub.
Plugin bundle pre-built — lib/bmad-extension-plugin/ ships as a deterministic, byte-stable bundle (built from lib/bmad-extension/ via scripts/build-plugin.js). At install time it is staged into <project>/.ma-agents-plugin-stage/ and consumed by bmad-method install --custom-source, so the install never touches the network for plugin assembly.
Deterministic installs — same ma-agents version always produces the same _bmad/ output, regardless of network conditions (NFR21). Bundle reproducibility is gated by a CI drift check.
Air-gapped friendly — install from a tarball (npm install ./ma-agents-x.y.z.tgz) and run npx ma-agents install completely offline. Every PR runs an offline-install gate (--network none Docker) to enforce this guarantee (NFR54).

npm install ma-agents          # bundles bmad-method + 4 external modules
npx ma-agents install --yes    # fully offline BMAD install — no network needed

Specialized BMAD Agents

SRE Agent (Alex):
- Focus: High availability, Kubernetes, Docker, and Podman.
- Capabilities: Day 1/2 operations, GitOps (ArgoCD/Flux), and advanced deployment strategies (Canary, Blue-Green).
- Workflows: System status, drift detection, and automated troubleshooting.
DevOps Agent (Amit):
- Focus: Build automation and multi-environment deployment.
- Capabilities: Helm charts/umbrellas, Docker Compose, and infrastructure provisioning (PV/PVC/LB).
- On-Prem Support: Specialized strategies for disconnected (air-gapped) environments.
Cyber Analyst (Yael):
- Focus: Cyber immunity, security auditing, and vulnerability management.
- Capabilities: Immunity estimation (scoring), Vault secret management, and PKI automation.
- Integration: Orchestrates ma-agents security skills for deep scans.
Demerzel (ML Scientist):
- Focus: Hypothesis-driven machine learning lifecycle with scientific rigor.
- Capabilities: EDA, architecture design, locked TechSpec contracts, experiment execution, failure-cost analysis.
- Workflows: 12-stage ML lifecycle from ideation through retrospective, with mandatory review gates.
Gad (SQA & Standards Expert):
- Focus: Software quality assurance and defense documentation standards — a unified persona covering SQA auditing and MIL-STD-498 document generation.
- SQA Capabilities: Multi-dimensional project quality audits, IEEE/ISO/IEC 12207:2017 compliance assessments (23 process areas, 4 groups), requirements evaluation against 14 established quality criteria (scope-selectable: PRD FRs, NFRs, epics, stories).
- MIL-STD-498 Capabilities: Full Data Item Description (DID) generation for SRS, SDD, SDP, OCD, SSS, STD, and SSDD. Requirements quality review tailored to MIL-STD-498 structure and military-standard terminology (CSCI, HWCI, IRS).
- Remediation: All audit and compliance workflows offer an optional remediation plan (sqa-remediation-plan-{date}.md) and per-finding create-bug-story integration for critical gaps.

Operational Workflows

The integration includes a suite of specialized playbooks:

GitOps & Deployment: Canary releases, rolling updates, and sync monitoring.
Infrastructure: PV/PVC management, Load Balancer configuration, and storage setup.
Security & Trust: Vault secrets, certificate generation, and vulnerability scanning.
Diagnostics: Advanced health checks across K8s, Docker, and Podman.

Sprint Management (v4.0+)

ma-agents includes a complete sprint management system built on a unified sprint-status.yaml — a single file that is the sole source of truth for all sprint and backlog state.

Data Model:

The entire sprint state lives in one file at _bmad-output/implementation-artifacts/sprint-status.yaml:

# Metadata
generated: <ISO-8601>
last_updated: <ISO-8601>
project: <string>
project_key: <string>
tracking_system: file-system   # or "jira" (future)
story_location: _bmad-output/implementation-artifacts

# Three data sections
epics:
  epic-17:
    status: in-progress        # backlog | in-progress | done | on-hold | cancelled
    retrospective: optional

backlog:                       # ordered array — position = priority
  - id: "17-10-rework-generate-backlog"
    type: story                # story | bug
    epic: 17
    title: "Rework generate-backlog Skill"
    priority: 1                # denormalized index, kept in sync with array position
    status: ready-for-dev
    severity: null             # null for stories; critical|high|medium|low for bugs

sprints:
  sprint-1:
    name: "Sprint 1"
    status: active             # planning | active | closed
    capacity: 8
    start: "2026-04-01"
    end: "2026-04-14"
    items:
      - id: "17-10-rework-generate-backlog"
        type: story
        epic: 17
        title: "Rework generate-backlog Skill"
        status: in-progress
        severity: null         # no priority field — ordering is implicit in array position

Workflows:

| Command | Description | |---------|-------------| | /bmad-sprint-planning | Bootstrap or refresh the entire sprint-status.yaml from epics | | /generate-backlog | Refresh the backlog section from epic/story definitions | | /add-sprint | Add a new sprint entry to the sprints map | | /add-to-sprint | Move backlog items into a sprint (atomic — removes from backlog, adds to sprint) | | /remove-from-sprint | Return sprint items to the backlog (status reset to ready-for-dev) | | /modify-sprint | Update sprint metadata (name, capacity, dates, status transitions) | | /sprint-status-view | Display sprint progress, backlog, and epic status (read-only) | | /bmad-sprint-status | Sprint health analysis with risk flags and recommendations | | /cleanup-done | Archive done/cancelled items — remove from YAML, move files to done/ | | /close-sprint | Full sprint closure — archive done items, disposition incomplete items | | /prioritize-backlog | Reorder backlog — full, quick-adjust, or AI-suggested modes |

Key Design Principles:

Single file, single truth: all state lives in sprint-status.yaml — no separate backlog or sprint files
Movement semantics: items exist in exactly one location (backlog OR a sprint, never both)
Forward-only transitions: sprint status follows planning → active → closed with no reversals
Single-active-sprint constraint: at most one sprint can have status: active at any time
Done item archival: completed work is removed from the YAML entirely and files moved to done/
Priority as denormalized index: backlog array order is authoritative; priority field mirrors position
Jira-ready: tracking_system: jira routes all operations through a Jira adapter (Epic 14)

Install Options (Direct)

# Default: installs to project-level paths (current directory)
npx ma-agents install code-review claude-code

# Install to global/user-level paths
npx ma-agents install code-review claude-code --global

# Install to a custom directory
npx ma-agents install code-review claude-code --path ./my-skills

# Skip all prompts, use defaults — ideal for CI/CD pipelines
npx ma-agents install --yes
npx ma-agents install --yes --global
npx ma-agents install --yes --agent claude-code

# Target a specific agent (skips agent selection prompt)
npx ma-agents install code-review --agent cursor

# Force overwrite without upgrade prompts
npx ma-agents install code-review claude-code --force

| Flag | Description | |------|-------------| | --yes | Skip all prompts, use defaults. Selects all detected agents, installs/updates BMAD automatically. | | --agent <name> | Scope the entire install to one agent — skill selection, BMAD update, and instruction-block stamping all apply to that tool only. Run npx ma-agents agents for valid names. | | --force | Skip upgrade prompts, always overwrite existing installations. | | --global | Install to global/user-level paths instead of project-level. | | --path <dir> | Custom installation directory. | | --log | Log all console output to install_<datetime>.log in the current directory. |

Requirements

Global Requirements

Node.js: v16+ (npx support)
Git: Required for git-related skills and version detection.
Bash: Most skill scripts require a bash-compliant shell.

Skill-Specific Requirements

Python Security/Deps: pip, uv (recommended), pip-audit.
JS/TS Security/Deps: npm, yarn, or pnpm.
C++ Skills: C++14+ compiler recommended.
Docker Skills: docker, docker-compose, trivy (for scanning).
Git Workflow: gh (GitHub CLI) for PR automation.

Skill Structure

Every skill follows a unified structure. See SKILLS_STRUCTURE.md for full documentation.

skills/<skill-name>/
├── skill.json              # Metadata — single source of truth (required)
├── SKILL.md                # Main instructions in pure Markdown (required)
├── claude-code.md          # Claude Code-specific template (optional)
├── cline.md                # Cline-specific template (optional)
├── generic.md              # Generic template for other agents (optional)
├── template.md             # Output template for the agent (optional)
├── scripts/                # Executable scripts (optional)
├── references/             # Documentation and reference material (optional)
├── examples/               # Sample outputs (optional)
├── hooks/                  # Git hooks or other hook scripts (optional)
└── assets/                 # Config files, templates, resources (optional)

Key Design Decisions

skill.json is the single source of truth for metadata (name, description). YAML frontmatter is injected automatically at install time — you never write it in source files.
Template priority: The installer looks for <agent-template>.md first (e.g., claude-code.md), then generic.md, then falls back to SKILL.md.
Resource mapping: Some agents use different directory names. For example, Cline expects docs/ instead of references/ and templates/ instead of assets/. The installer handles this mapping automatically.

Creating a New Skill

1. Create the skill directory

mkdir -p skills/my-skill

2. Create `skill.json`

{
  "name": "My Skill",
  "description": "What this skill does in one sentence",
  "version": "1.0.0",
  "author": "Your Name",
  "tags": ["category", "keywords"]
}

3. Create `SKILL.md`

Write pure Markdown instructions. Do not add YAML frontmatter — the installer injects it from skill.json.

# My Skill

## Purpose
What problem this skill solves.

## Instructions
Step-by-step instructions for the agent.

## Rules
Constraints the agent must follow.

## Output Format
What the agent should produce.

4. Add optional resources

mkdir -p skills/my-skill/scripts      # Executable scripts
mkdir -p skills/my-skill/references    # Documentation
mkdir -p skills/my-skill/examples      # Sample outputs

5. (Optional) Create agent-specific templates

If a skill needs different instructions for different agents:

# Claude Code gets tailored instructions
skills/my-skill/claude-code.md

# Cline gets its own version
skills/my-skill/cline.md

# All other agents use SKILL.md

6. Test

npx ma-agents list                          # Verify it appears
npx ma-agents install my-skill claude-code  # Test installation

Adding a New Agent

Edit lib/agents.js and add a new entry to the agents array:

{
  id: 'my-agent',
  name: 'My Agent',
  description: 'My Agent Description',
  getProjectPath: () => path.join(process.cwd(), '.my-agent', 'skills'),
  getGlobalPath: () => {
    const platform = os.platform();
    if (platform === 'win32') {
      return path.join(os.homedir(), 'AppData', 'Roaming', 'MyAgent', 'skills');
    } else if (platform === 'darwin') {
      return path.join(os.homedir(), 'Library', 'Application Support', 'MyAgent', 'skills');
    } else {
      return path.join(os.homedir(), '.config', 'my-agent', 'skills');
    }
  },
  fileExtension: '.md',
  template: 'generic',
  // Optional: rename resource directories to match agent's native structure
  resourceMap: {
    'references': 'docs',
    'assets': 'templates'
  }
}

Agent Configuration Fields

| Field | Required | Description | |-------|----------|-------------| | id | Yes | Unique kebab-case identifier (used in CLI) | | name | Yes | Display name shown to users | | description | Yes | Brief description | | getProjectPath | Yes | Returns project-level skills directory | | getGlobalPath | Yes | Returns global/user-level skills directory (platform-specific) | | fileExtension | Yes | File extension for skill files (usually .md) | | template | Yes | Template ID — determines which .md file to look for first | | resourceMap | No | Maps generic directory names to agent-specific names |

Project Structure

ma-agents/
├── bin/
│   └── cli.js                  # CLI entry point (wizard + commands)
├── lib/
│   ├── agents.js               # Agent configurations, paths, and extraInstructionTemplates
│   ├── installer.js            # Skill installation, instruction-block stamping, marker management
│   ├── bmad.js                 # BMAD-METHOD integration, recompile, persona phase prefix
│   ├── profile.js              # Profile persistence (getProfile / setProfile / resolveProfile / clearProfile)
│   ├── reconfigure.js          # ma-agents reconfigure — re-stamp profile-dependent artifacts
│   ├── uninstall.js            # ma-agents uninstall --profile-artifacts
│   ├── merge/
│   │   └── roomodes.js         # YAML merger for .roomodes slug collision / user-slug preservation
│   ├── templates/
│   │   ├── instruction-block-universal.template.md   # Universal planning-instruction block
│   │   ├── instruction-block-onprem.template.md      # On-prem guardrails append (profile=on-prem)
│   │   ├── roomodes.template.yaml                    # 4 BMAD Roo Code modes with fileRegex
│   │   ├── agents-md.template.md                     # AGENTS.md for OpenCode
│   │   ├── clinerules.template.md                    # .clinerules expansion for Cline
│   │   └── project-context.template.md               # project-context.md generation template
│   ├── bmad-customize/         # Source-of-truth: per-persona phase / on_prem_phase_prefix YAML (consumed by the post-install marker-block injector)
│   ├── bmad-cache/             # Pre-bundled BMAD external modules (bmb, cis, gds, tea)
│   ├── bmad-customizations/    # BMAD persona templates (.md) and YAML configs
│   ├── bmad-extension/         # Extension source: sprint management, bug tracking, agent skills (hand-edited)
│   ├── bmad-extension-plugin/  # Generated plugin bundle (deterministic; built from bmad-extension/ via scripts/build-plugin.js)
│   ├── bmad-workflows/         # Specialized BMAD playbooks (SRE, Cyber, etc.)
│   └── mil498-templates/       # MIL-STD-498 DID library (SRS, SSS, SSDD, etc.)
├── scripts/
│   ├── build-bmad-cache.js     # Rebuilds lib/bmad-cache/ from upstream repos
│   └── build-plugin.js         # Rebuilds lib/bmad-extension-plugin/ from lib/bmad-extension/ (run on `npm run build:plugin` and via the prepare hook)
├── skills/
│   ├── code-review/            # 27 bundled skills across 5 domains
│   ├── commit-message/
│   ├── create-hardened-docker-skill/
│   ├── git-workflow-skill/
│   ├── js-ts-security-skill/
│   ├── skill-creator/
│   ├── test-generator/
│   ├── vercel-react-best-practices/
│   └── verify-hardened-docker-skill/
├── test/
│   └── yes-flag.test.js        # Tests for --yes / --agent flag behavior
├── docs/
│   └── validation/             # Manual validation reports (e.g., bundled install)
├── SKILLS_STRUCTURE.md         # Full skill authoring documentation
├── package.json
└── README.md

Development

# Clone the repository
git clone https://github.com/mayafit/AI_Agents.git
cd AI_Agents

# Install dependencies
npm install

# Run locally
node bin/cli.js

# Test skill listing
node bin/cli.js list

# Test agents listing
node bin/cli.js agents

# Run tests
npm test

# Rebuild the bundled BMAD module cache (lib/bmad-cache/)
npm run build:bmad-cache

Programmatic API

const { installSkill, listSkills, listAgents } = require('ma-agents');

// List all available skills
const skills = listSkills();

// List all supported agents
const agents = listAgents();

// Install a skill programmatically
await installSkill('code-review', ['claude-code', 'copilot'], '', 'project');

Contributing

Contributions welcome:

New skills — Follow the structure in SKILLS_STRUCTURE.md
New agents — Add to lib/agents.js with both project and global paths
Bug fixes and improvements

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ma-agents

What's New in v3.12.0

What's New in v3.11.0

What's New in v3.10.0

What's New in v3.9.0

Installation & Usage

1. Interactive Wizard (Recommended)

2. Direct Command Line

How It Works

Project Knowledge: _bmad-output/

What it contains

Why it is version-controlled

Installer behaviour

Project Context

On-Prem / Air-Gapped Deployment

What the on-prem profile stamps

Supported Coding Tools

Specialized BMAD Agents

Available Skills

General-Purpose Skills (34)

Agent Workflows (34)

Automated Skill Discovery

1. The Manifest (MANIFEST.yaml)

2. Instruction Injection

CLI Usage

The Update Process

BMAD-METHOD Integration

Core Features

Bundled & Offline Installation (v2.20+)

Specialized BMAD Agents

Operational Workflows

Sprint Management (v4.0+)

Install Options (Direct)

Requirements

Global Requirements

Skill-Specific Requirements

Skill Structure

Key Design Decisions

Creating a New Skill

1. Create the skill directory

2. Create skill.json

3. Create SKILL.md

4. Add optional resources

5. (Optional) Create agent-specific templates

6. Test

Adding a New Agent

Agent Configuration Fields

Project Structure

Development

Programmatic API

Contributing

License

1. The Manifest (`MANIFEST.yaml`)

2. Create `skill.json`

3. Create `SKILL.md`