ma-agents 1.3.0 → 1.4.0

package/README.md

@@ -1,264 +1,213 @@
-# AI Agent Skills
+# ma-agents
 
-A universal NPX tool to install skills for AI coding agents including Claude Code, Gemini, Copilot, Kilocode, Cline, and Cursor.
+A universal NPX tool to install AI coding agent skills. Write skills once, install them across Claude Code, Gemini, Copilot, Cline, Cursor, and Kilocode.
 
-## Features
+## Quick Start
 
-- 🤖 Support for multiple AI coding agents
-- 📦 Easy skill installation via NPX
-- 🔧 Extensible architecture for adding new agents
-- 📝 Simple skill creation system
-- 🎯 Interactive CLI for user-friendly installation
+```bash
+# Interactive wizard
+npx ma-agents
 
-## Supported Agents
+# Direct install
+npx ma-agents install code-review claude-code
+
+# Install a skill to multiple agents at once
+npx ma-agents install code-review claude-code copilot cline
+```
 
-- **Claude Code** - Anthropic's Claude Code CLI
-- **Google Gemini** - Google Gemini Code Assist
-- **GitHub Copilot** - GitHub Copilot Agent Mode
-- **Kilocode** - Kilocode AI Assistant
-- **Cline** - Cline AI Assistant (VSCode Extension)
-- **Cursor** - Cursor AI Editor
+## How It Works
 
-## Installation
+Skills are written in a **unified generic format** and stored in this package. When you install a skill, the installer:
+
+1. Reads the skill's `SKILL.md` (or agent-specific template if available)
+2. Injects YAML frontmatter from `skill.json` (the single source of metadata)
+3. Copies the skill and its resources into the target agent's directory
+4. Renames resource directories to match the agent's native structure (e.g., `references/` becomes `docs/` for Cline)
+
+```
+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/
+```
 
-No installation required! Use directly with NPX:
+## Supported Agents
 
+| Agent | Project Path | Template |
+|-------|-------------|----------|
+| Claude Code | `.claude/skills/` | `claude-code` |
+| Google Gemini | `.gemini/skills/` | `generic` |
+| GitHub Copilot | `.github/copilot/skills/` | `generic` |
+| Cursor | `.cursor/skills/` | `generic` |
+| Cline | `.cline/skills/` | `cline` |
+| Kilocode | `.kilocode/skills/` | `generic` |
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `code-review` | Comprehensive code reviews following industry best practices and security guidelines |
+| `commit-message` | Generates conventional commit messages from code changes |
+| `test-generator` | Generates comprehensive unit and integration tests |
+| `git-workflow-skill` | Worktree-based feature branch workflow for parallel multi-agent development |
+| `skill-creator` | Guide for creating skills that extend AI agent capabilities |
+| `vercel-react-best-practices` | 57 actionable performance rules for React and Next.js projects |
+| `create-hardened-docker-skill` | Creates production-ready hardened Docker configurations (CIS, OWASP, NIST) |
+| `verify-hardened-docker-skill` | Security verification for Docker configurations against CIS/OWASP/NIST |
+| `js-ts-security-skill` | Security verification for JS/TS codebases against OWASP Top 10 2025 |
+
+List all skills:
 ```bash
-npx ai-agent-skills
+npx ma-agents list
 ```
 
-## Usage
+## CLI Usage
 
-### Interactive Mode
+```
+npx ma-agents                              Interactive wizard
+npx ma-agents install                      Interactive install wizard
+npx ma-agents install <skill> <agents...>  Install directly
+npx ma-agents list                         List available skills
+npx ma-agents agents                       List supported agents
+npx ma-agents help                         Show help
+```
 
-Simply run the command and follow the prompts:
+### Install Options
 
 ```bash
-npx ai-agent-skills
+# 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
 ```
 
-You'll be able to:
-1. Choose an action (install skill, list skills, list agents)
-2. Select a skill to install
-3. Choose which agents to install for
-4. Specify a custom installation path (optional)
+### Installation Scope
 
-### Available Skills
+By default, skills install at **project level** (relative to where the command is run):
 
-The package comes with example skills:
+| Agent | Project Path |
+|-------|-------------|
+| Claude Code | `.claude/skills/<skill-name>/SKILL.md` |
+| Gemini | `.gemini/skills/<skill-name>/SKILL.md` |
+| Copilot | `.github/copilot/skills/<skill-name>/SKILL.md` |
+| Cursor | `.cursor/skills/<skill-name>/SKILL.md` |
+| Cline | `.cline/skills/<skill-name>/SKILL.md` |
+| Kilocode | `.kilocode/skills/<skill-name>/SKILL.md` |
 
-- **Code Review** - Comprehensive code review following best practices
-- **Test Generator** - Generate unit and integration tests
-- **Commit Message Generator** - Create conventional commit messages
+Use `--global` to install to user-level directories instead.
 
-## Project Structure
+## Skill Structure
+
+Every skill follows a unified structure. See [SKILLS_STRUCTURE.md](SKILLS_STRUCTURE.md) for full documentation.
 
 ```
-ai-agent-skills/
-├── bin/
-│   └── cli.js              # CLI entry point
-├── lib/
-│   ├── agents.js           # Agent configurations
-│   └── installer.js        # Installation logic
-├── skills/
-│   ├── code-review/
-│   │   ├── skill.json      # Skill metadata
-│   │   ├── claude-code.md  # Claude Code template
-│   │   ├── generic.md      # Generic template
-│   │   └── cline.md        # Cline-specific template
-│   ├── test-generator/
-│   │   ├── skill.json
-│   │   └── ...
-│   └── commit-message/
-│       ├── skill.json
-│       └── generic.md
-├── package.json
-└── README.md
+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)
 ```
 
-## How to Add a New Skill
+### Key Design Decisions
 
-Adding a new skill is straightforward. Follow these steps:
+- **`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.
 
-### 1. Create Skill Directory
+## Creating a New Skill
 
-Create a new directory under `skills/` with your skill name (use kebab-case):
+### 1. Create the skill directory
 
 ```bash
-mkdir skills/my-awesome-skill
+mkdir -p skills/my-skill
 ```
 
-### 2. Create Skill Metadata
-
-Create a `skill.json` file in your skill directory:
+### 2. Create `skill.json`
 
 ```json
 {
-  "name": "My Awesome Skill",
-  "description": "Brief description of what this skill does",
+  "name": "My Skill",
+  "description": "What this skill does in one sentence",
   "version": "1.0.0",
   "author": "Your Name",
-  "tags": ["tag1", "tag2", "tag3"]
+  "tags": ["category", "keywords"]
 }
 ```
 
-**Fields:**
-- `name`: Display name for the skill
-- `description`: Short description (shown in skill list)
-- `version`: Semantic version number
-- `author`: Your name or organization
-- `tags`: Array of tags for categorization
-
-### 3. Create Skill Templates
+### 3. Create `SKILL.md`
 
-Create at least one template file. You can create:
-
-#### Generic Template (recommended)
-`generic.md` - Works for all agents
+Write pure Markdown instructions. Do **not** add YAML frontmatter — the installer injects it from `skill.json`.
 
 ```markdown
-# My Awesome Skill
+# My Skill
 
-Brief description of the skill.
+## Purpose
+What problem this skill solves.
 
 ## Instructions
+Step-by-step instructions for the agent.
 
-Step-by-step instructions for the AI agent...
-
-## Examples
-
-Example interactions...
-```
-
-#### Agent-Specific Templates (optional)
-Create specialized templates for specific agents:
-
-- `claude-code.md` - Claude Code specific
-- `cline.md` - Cline specific
-- `generic.md` - Fallback for all other agents
-
-**Template Naming Convention:**
-- Use the agent's `template` field from [lib/agents.js](lib/agents.js)
-- Add the agent's `fileExtension` (usually `.md`)
-
-### 4. Template Content Guidelines
-
-Your skill template should include:
-
-```markdown
-# Skill Name
-
-## Description
-Clear explanation of what the skill does
+## Rules
+Constraints the agent must follow.
 
-## Usage
-How to invoke or use this skill
-
-## Instructions
-Detailed instructions for the AI agent:
-1. Step 1
-2. Step 2
-3. ...
-
-## Examples
-Example interactions showing:
-- User input
-- Expected AI behavior
-
-## Output Format (if applicable)
-Template or structure for the AI's output
+## Output Format
+What the agent should produce.
 ```
 
-### 5. Test Your Skill
-
-After creating your skill, test it:
+### 4. Add optional resources
 
 ```bash
-npx ai-agent-skills
-# Select "List available skills" to verify it appears
-# Then install it to test
+mkdir -p skills/my-skill/scripts      # Executable scripts
+mkdir -p skills/my-skill/references    # Documentation
+mkdir -p skills/my-skill/examples      # Sample outputs
 ```
 
-### Example: Creating a "Documentation Generator" Skill
+### 5. (Optional) Create agent-specific templates
 
-```bash
-# 1. Create directory
-mkdir skills/doc-generator
+If a skill needs different instructions for different agents:
 
-# 2. Create skill.json
-cat > skills/doc-generator/skill.json << 'EOF'
-{
-  "name": "Documentation Generator",
-  "description": "Generate comprehensive documentation for code",
-  "version": "1.0.0",
-  "author": "AI Agent Skills",
-  "tags": ["documentation", "docs", "jsdoc"]
-}
-EOF
-
-# 3. Create template
-cat > skills/doc-generator/generic.md << 'EOF'
-# Documentation Generator
-
-Generate comprehensive documentation for code including API docs, JSDoc, docstrings, etc.
-
-## Instructions
-
-1. Analyze the code structure
-2. Identify public APIs, functions, classes
-3. Generate documentation following the language's convention:
-   - JavaScript/TypeScript: JSDoc
-   - Python: Docstrings (Google/NumPy style)
-   - Java: JavaDoc
-   - C#: XML documentation
-4. Include parameters, return types, examples
-5. Add usage examples where helpful
-
-## Output Format
-
-Include:
-- Function/method description
-- Parameters with types
-- Return value with type
-- Examples (if complex)
-- Exceptions/errors thrown
+```bash
+# Claude Code gets tailored instructions
+skills/my-skill/claude-code.md
 
-## Example
+# Cline gets its own version
+skills/my-skill/cline.md
 
-```javascript
-/**
- * Calculates the sum of two numbers
- * @param {number} a - The first number
- * @param {number} b - The second number
- * @returns {number} The sum of a and b
- * @example
- * add(2, 3) // returns 5
- */
-function add(a, b) {
-  return a + b;
-}
-```
-EOF
+# All other agents use SKILL.md
 ```
 
-## How to Add a New Agent
-
-Adding support for a new AI agent is simple. Follow these steps:
-
-### 1. Open Agent Configuration
+### 6. Test
 
-Edit [lib/agents.js](lib/agents.js)
+```bash
+npx ma-agents list                          # Verify it appears
+npx ma-agents install my-skill claude-code  # Test installation
+```
 
-### 2. Add Agent Object
+## Adding a New Agent
 
-Add a new agent object to the `agents` array:
+Edit [lib/agents.js](lib/agents.js) and add a new entry to the `agents` array:
 
 ```javascript
 {
   id: 'my-agent',
   name: 'My Agent',
-  description: 'Brief description of the agent',
-  getSkillsPath: () => {
+  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');
@@ -269,152 +218,95 @@ Add a new agent object to the `agents` array:
     }
   },
   fileExtension: '.md',
-  template: 'my-agent'
+  template: 'generic',
+  // Optional: rename resource directories to match agent's native structure
+  resourceMap: {
+    'references': 'docs',
+    'assets': 'templates'
+  }
 }
 ```
 
-### 3. Agent Configuration Fields
-
-**Required Fields:**
-
-- `id` (string): Unique identifier (kebab-case)
-  - Used internally and in CLI selection
-  - Example: `'claude-code'`, `'my-agent'`
-
-- `name` (string): Display name
-  - Shown to users in the interactive menu
-  - Example: `'Claude Code'`, `'My Agent'`
-
-- `description` (string): Brief description
-  - Helps users identify the agent
-  - Example: `'Anthropic Claude Code CLI'`
-
-- `getSkillsPath` (function): Returns the default skills directory path
-  - Must handle Windows, macOS, and Linux
-  - Returns absolute path to where skills should be installed
-  - Platform-specific paths:
-    - **Windows**: `AppData/Roaming/[Agent]/skills`
-    - **macOS**: `Library/Application Support/[Agent]/skills`
-    - **Linux**: `.config/[agent]/skills`
-
-- `fileExtension` (string): File extension for skill files
-  - Usually `'.md'` for markdown
-  - Could be `'.txt'`, `'.json'`, etc. depending on agent
-
-- `template` (string): Template identifier
-  - Used to find agent-specific skill templates
-  - Should match template filename (e.g., `'my-agent'` → `my-agent.md`)
-  - Falls back to `'generic'` if template doesn't exist
-
-### 4. Finding the Skills Directory
+### Agent Configuration Fields
 
-To find where your agent stores skills:
+| 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 |
 
-1. **Check agent documentation** - Look for skills, plugins, or extensions directory
-2. **Check agent config** - Look in the agent's settings/configuration file
-3. **Common locations:**
-   - Windows: `%APPDATA%` or `%LOCALAPPDATA%`
-   - macOS: `~/Library/Application Support/`
-   - Linux: `~/.config/` or `~/.local/share/`
-
-### 5. Test Your Agent
-
-After adding the agent configuration:
-
-```bash
-npx ai-agent-skills
-# Select "List supported agents"
-# Verify your agent appears
-# Try installing a skill to your new agent
-```
-
-### Example: Adding "Windsurf" Agent
-
-```javascript
-{
-  id: 'windsurf',
-  name: 'Windsurf',
-  description: 'Windsurf AI Code Editor',
-  getSkillsPath: () => {
-    const platform = os.platform();
-    if (platform === 'win32') {
-      return path.join(os.homedir(), 'AppData', 'Roaming', 'Windsurf', 'skills');
-    } else if (platform === 'darwin') {
-      return path.join(os.homedir(), 'Library', 'Application Support', 'Windsurf', 'skills');
-    } else {
-      return path.join(os.homedir(), '.config', 'windsurf', 'skills');
-    }
-  },
-  fileExtension: '.md',
-  template: 'generic'  // Use generic template
-}
-```
-
-## Advanced: Agent-Specific Templates
-
-If your agent has unique requirements, create agent-specific templates:
-
-1. Set `template: 'my-agent'` in agent configuration
-2. Create `my-agent.md` files in skill directories
-3. The installer will use agent-specific templates when available
-4. Falls back to `generic.md` if agent-specific template doesn't exist
-
-**Example:** Claude Code might need specific formatting:
+## Project Structure
 
 ```
-skills/code-review/
-├── skill.json
-├── claude-code.md    # Claude-specific format
-├── cline.md          # Cline-specific format
-└── generic.md        # Works for all others
+ma-agents/
+├── bin/
+│   └── cli.js                  # CLI entry point (wizard + commands)
+├── lib/
+│   ├── agents.js               # Agent configurations and paths
+│   └── installer.js            # Skill discovery, frontmatter injection, installation
+├── skills/
+│   ├── code-review/            # 9 bundled skills
+│   ├── 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/
+├── SKILLS_STRUCTURE.md         # Full skill authoring documentation
+├── package.json
+└── README.md
 ```
 
 ## Development
 
-### Setup
-
 ```bash
 # Clone the repository
-git clone <your-repo-url>
-cd ai-agent-skills
+git clone https://github.com/mayafit/AI_Agents.git
+cd AI_Agents
 
 # Install dependencies
 npm install
 
-# Test locally
+# Run locally
 node bin/cli.js
+
+# Test skill listing
+node bin/cli.js list
+
+# Test agents listing
+node bin/cli.js agents
 ```
 
-### Publishing
+## Programmatic API
 
-To publish to NPM:
+```javascript
+const { installSkill, listSkills, listAgents } = require('ma-agents');
 
-```bash
-# Login to NPM
-npm login
+// List all available skills
+const skills = listSkills();
 
-# Publish
-npm publish
-```
+// List all supported agents
+const agents = listAgents();
 
-After publishing, users can run:
-```bash
-npx ai-agent-skills
+// Install a skill programmatically
+await installSkill('code-review', ['claude-code', 'copilot'], '', 'project');
 ```
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit:
+Contributions welcome:
 
-- New skills
-- Support for additional agents
-- Bug fixes
-- Documentation improvements
+- **New skills** — Follow the structure in [SKILLS_STRUCTURE.md](SKILLS_STRUCTURE.md)
+- **New agents** — Add to [lib/agents.js](lib/agents.js) with both project and global paths
+- **Bug fixes** and improvements
 
 ## License
 
 MIT
-
-## Support
-
-For issues or questions, please open an issue on the GitHub repository.