ma-agents 2.3.1 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +89 -49
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,7 +5,7 @@ A universal NPX tool to install AI coding agent skills. Write skills once, insta
5
5
  ## Quick Start
6
6
 
7
7
  ```bash
8
- # Interactive wizard
8
+ # Interactive wizard (Install All / Custom Select / Update / Uninstall)
9
9
  npx ma-agents
10
10
 
11
11
  # Direct install
@@ -23,6 +23,8 @@ Skills are written in a **unified generic format** and stored in this package. W
23
23
  2. Injects YAML frontmatter from `skill.json` (the single source of metadata)
24
24
  3. Copies the skill and its resources into the target agent's directory
25
25
  4. Renames resource directories to match the agent's native structure (e.g., `references/` becomes `docs/` for Cline)
26
+ 5. **Generates `MANIFEST.yaml`**: A central discovery file for the agent to find all installed skills.
27
+ 6. **Updates Instructions**: Injects planning hints into agent files (e.g., `CLAUDE.md`, `.clinerules`) to ensure the agent uses the skills.
26
28
 
27
29
  ```
28
30
  Generic (this repo) Installed Output
@@ -32,51 +34,90 @@ skills/code-review/
32
34
  ├── SKILL.md ──────────► .claude/skills/code-review/SKILL.md
33
35
  ├── scripts/ ──────────► .claude/skills/code-review/scripts/
34
36
  └── references/ ──────────► .claude/skills/code-review/references/
37
+ + Generated MANIFEST.yaml
38
+ + Updated Agent Instructions (CLAUDE.md, etc.)
35
39
  ```
36
40
 
37
41
  ## Supported Agents
38
42
 
39
- | Agent | Project Path | Template |
40
- |-------|-------------|----------|
41
- | Claude Code | `.claude/skills/` | `claude-code` |
42
- | Google Gemini | `.gemini/skills/` | `generic` |
43
- | GitHub Copilot | `.github/copilot/skills/` | `generic` |
44
- | Cursor | `.cursor/skills/` | `generic` |
45
- | Cline | `.cline/skills/` | `cline` |
46
- | Kilocode | `.kilocode/skills/` | `generic` |
47
-
48
- ## Available Skills
49
-
50
- | Skill | Description |
51
- |-------|-------------|
52
- | `code-review` | Comprehensive code reviews following industry best practices and security guidelines |
53
- | `commit-message` | Generates conventional commit messages from code changes |
54
- | `test-generator` | Generates comprehensive unit and integration tests |
55
- | `git-workflow-skill` | Worktree-based feature branch workflow for parallel multi-agent development |
56
- | `skill-creator` | Guide for creating skills that extend AI agent capabilities |
57
- | `vercel-react-best-practices` | 57 actionable performance rules for React and Next.js projects |
58
- | `create-hardened-docker-skill` | Creates production-ready hardened Docker configurations (CIS, OWASP, NIST) |
59
- | `verify-hardened-docker-skill` | Security verification for Docker configurations against CIS/OWASP/NIST |
60
- | `js-ts-security-skill` | Security verification for JS/TS codebases against OWASP Top 10 2025 |
61
-
62
- List all skills:
63
- ```bash
64
- npx ma-agents list
65
- ```
43
+ | Agent | Project Path | Template | Instruction File |
44
+ |-------|-------------|----------|------------------|
45
+ | Claude Code | `.claude/skills/` | `claude-code` | `CLAUDE.md` |
46
+ | Google Gemini | `.gemini/skills/` | `generic` | - |
47
+ | GitHub Copilot | `.github/copilot/skills/` | `generic` | - |
48
+ | Cursor | `.cursor/skills/` | `generic` | - |
49
+ | Cline | `.cline/skills/` | `cline` | `.clinerules` |
50
+ | Kilocode | `.kilocode/skills/` | `generic` | - |
51
+
52
+ ## Available Skills (22)
53
+
54
+ | Skill ID | Domain | Description |
55
+ | :--- | :--- | :--- |
56
+ | **General** | | |
57
+ | `code-review` | Quality | Comprehensive reviews following best practices and security guidelines |
58
+ | `commit-message` | Git | Generates conventional commit messages from code changes |
59
+ | `test-generator` | Testing | Generates comprehensive unit and integration tests |
60
+ | `test-accompanied-development` | Quality | Enforces "test-alongside" policy for every public method |
61
+ | `code-documentation` | Quality | Enforces PEP 257, Doxygen, JSDoc, and XML standards |
62
+ | `skill-creator` | Meta | Guide for creating new skills to extend agent capabilities |
63
+ | **Security** | | |
64
+ | `python-security-skill` | Python | OWASP Top 10 2025 aligned guardrails for Python |
65
+ | `js-ts-security-skill` | JS/TS | Security verification for JS/TS codebases (OWASP aligned) |
66
+ | `create-hardened-docker-skill` | Docker | Creates production-ready hardened Docker (CIS/NIST) |
67
+ | `verify-hardened-docker-skill` | Docker | Security verification for Docker configurations |
68
+ | **Dependencies** | | |
69
+ | `python-dependency-mgmt` | Python | Best practices for `uv` (lockfiles/sync) and `pip` |
70
+ | `js-ts-dependency-mgmt` | JS/TS | Stability and security for NPM, Yarn, and PNPM |
71
+ | **Modern C++** | | |
72
+ | `cpp-memory-handling` | C++ | RAII, smart pointers, and safe buffer management |
73
+ | `cpp-robust-interfaces` | C++ | Contract-based design and strong typing (C++14+) |
74
+ | `cpp-modern-composition` | C++ | Replaces C-style patterns with STL and Ranges |
75
+ | `cpp-const-correctness` | C++ | Immutability-by-default and `constexpr` logic |
76
+ | `cpp-concurrency-safety` | C++ | RAII locking and task-based parallelism |
77
+ | `cmake-best-practices` | Build | Target-based, property-oriented CMake patterns |
78
+ | **Architecture** | | |
79
+ | `logging-best-practices` | Logic | Standardized structured logging (JSON) across domains |
80
+ | `opentelemetry-best-practices` | Logic | Distributed tracing and semantic conventions |
81
+ | `vercel-react-best-practices` | Web | 57 Performance rules for React and Next.js |
82
+ | `git-workflow-skill` | Git | Worktree-based feature branch workflow |
83
+
84
+ ## Automated Skill Discovery
85
+
86
+ `ma-agents` features an automated discovery system that ensures installed skills are actually used by the agent without manual configuration.
87
+
88
+ ### 1. The Manifest (`MANIFEST.yaml`)
89
+ Every installation automatically generates a `MANIFEST.yaml` in the skills directory. It contains:
90
+ - **Skill IDs and Paths**: Where to find the instructions.
91
+ - **`applies_when` Conditions**: Hints about when a skill should be loaded (e.g., "when writing public APIs").
92
+ - **`always_load` Flags**: Mandatory skills that should always be in context.
93
+
94
+ ### 2. Instruction Injection
95
+ The installer automatically updates agent-specific instruction files (like `CLAUDE.md` or `.clinerules`) with a "Planning Instruction" block. This block tells the agent to:
96
+ 1. Consult the `MANIFEST.yaml` before starting a task.
97
+ 2. Select and read only the relevant skills for the current context.
98
+
99
+ ---
66
100
 
67
101
  ## CLI Usage
68
102
 
69
- ```
70
- npx ma-agents Interactive wizard
71
- npx ma-agents install Interactive install wizard
72
- npx ma-agents install <skill> <agents...> Install directly
73
- npx ma-agents list List available skills
74
- npx ma-agents agents List supported agents
75
- npx ma-agents help Show help
103
+ ```bash
104
+ npx ma-agents # Launch interactive wizard
105
+ npx ma-agents install # Interactive install wizard
106
+ npx ma-agents status # Show installed skills and paths
107
+ npx ma-agents list # List all available skills
108
+ npx ma-agents agents # List supported agents
109
+ npx ma-agents uninstall <skill> <agents> # Direct uninstall
76
110
  ```
77
111
 
78
- ### Install Options
112
+ ### The Interactive Wizard
113
+ The easiest way to manage your skills is to simply run `npx ma-agents`. The wizard will guide you through:
114
+ - **Install All**: One-click setup for the entire 22-skill suite.
115
+ - **Custom Select**: Granularly choose specific skills and agents.
116
+ - **Update**: Add or remove skills from an existing installation.
117
+ - **Clean Reinstall**: Wipe the slate and start fresh.
118
+ - **Uninstall All**: Remove all ma-agents artifacts from the project.
79
119
 
120
+ ### Install Options (Direct)
80
121
  ```bash
81
122
  # Default: installs to project-level paths (current directory)
82
123
  npx ma-agents install code-review claude-code
@@ -88,20 +129,19 @@ npx ma-agents install code-review claude-code --global
88
129
  npx ma-agents install code-review claude-code --path ./my-skills
89
130
  ```
90
131
 
91
- ### Installation Scope
92
-
93
- By default, skills install at **project level** (relative to where the command is run):
132
+ ## Requirements
94
133
 
95
- | Agent | Project Path |
96
- |-------|-------------|
97
- | Claude Code | `.claude/skills/<skill-name>/SKILL.md` |
98
- | Gemini | `.gemini/skills/<skill-name>/SKILL.md` |
99
- | Copilot | `.github/copilot/skills/<skill-name>/SKILL.md` |
100
- | Cursor | `.cursor/skills/<skill-name>/SKILL.md` |
101
- | Cline | `.cline/skills/<skill-name>/SKILL.md` |
102
- | Kilocode | `.kilocode/skills/<skill-name>/SKILL.md` |
134
+ ### Global Requirements
135
+ - **Node.js**: v16+ (npx support)
136
+ - **Git**: Required for git-related skills and version detection.
137
+ - **Bash**: Most skill scripts require a bash-compliant shell.
103
138
 
104
- Use `--global` to install to user-level directories instead.
139
+ ### Skill-Specific Requirements
140
+ - **Python Security/Deps**: `pip`, `uv` (recommended), `pip-audit`.
141
+ - **JS/TS Security/Deps**: `npm`, `yarn`, or `pnpm`.
142
+ - **C++ Skills**: C++14+ compiler recommended.
143
+ - **Docker Skills**: `docker`, `docker-compose`, `trivy` (for scanning).
144
+ - **Git Workflow**: `gh` (GitHub CLI) for PR automation.
105
145
 
106
146
  ## Skill Structure
107
147
 
@@ -250,7 +290,7 @@ ma-agents/
250
290
  │ ├── agents.js # Agent configurations and paths
251
291
  │ └── installer.js # Skill discovery, frontmatter injection, installation
252
292
  ├── skills/
253
- │ ├── code-review/ # 9 bundled skills
293
+ │ ├── code-review/ # 22 bundled skills across 5 domains
254
294
  │ ├── commit-message/
255
295
  │ ├── create-hardened-docker-skill/
256
296
  │ ├── git-workflow-skill/
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ma-agents",
3
- "version": "2.3.1",
3
+ "version": "2.4.0",
4
4
  "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
5
5
  "main": "index.js",
6
6
  "bin": {