ma-agents 1.5.0 → 1.7.0

package/CLAUDE.md

@@ -0,0 +1,14 @@
+
+<!-- MA-AGENTS-START -->
+# AI Agent Skills - Planning Instruction
+
+You have access to a library of skills in your skills directory. Before starting any task:
+
+1. Read the skill manifest at skills/MANIFEST.yaml
+2. Based on the task description, select which skills are relevant
+3. Read only the selected skill files
+4. Then proceed with the task
+
+Always load skills marked with always_load: true.
+Do not load skills that are not relevant to the current task.
+<!-- MA-AGENTS-END -->

package/lib/agents.js

@@ -31,7 +31,8 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'claude-code'
+    template: 'claude-code',
+    instructionFiles: ['CLAUDE.md']
   },
   {
     id: 'gemini',
@@ -50,7 +51,8 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'generic'
+    template: 'generic',
+    instructionFiles: [] // Gemini doesn't have a standard project-level instruction file yet
   },
   {
     id: 'copilot',
@@ -69,7 +71,8 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'generic'
+    template: 'generic',
+    instructionFiles: [] // Copilot uses path-scoped instructions, maybe support .github/instructions/ later
   },
   {
     id: 'kilocode',
@@ -88,7 +91,8 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'generic'
+    template: 'generic',
+    instructionFiles: []
   },
   {
     id: 'cline',
@@ -112,7 +116,8 @@ const agents = [
     resourceMap: {
       'references': 'docs',
       'assets': 'templates'
-    }
+    },
+    instructionFiles: ['.clinerules']
   },
   {
     id: 'cursor',
@@ -131,7 +136,8 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'generic'
+    template: 'generic',
+    instructionFiles: [] // Cursor uses .cursorrules or individual .mdc files
   }
 ];
 

package/lib/installer.js

@@ -52,6 +52,84 @@ function getInstalledSkillInfo(installPath, skillId) {
   return manifest.skills[skillId];
 }
 
+async function generateSkillsManifest(installPath, agent) {
+  const skills = listSkills();
+  const manifest = readManifest(installPath);
+  if (!manifest || !manifest.skills) return;
+
+  const manifestYamlPath = path.join(installPath, 'MANIFEST.yaml');
+  let yamlContent = '# skills/MANIFEST.yaml\n\nskills:\n';
+
+  const skillIds = Object.keys(manifest.skills).sort();
+  for (const skillId of skillIds) {
+    const skill = skills.find(s => s.id === skillId);
+    if (!skill) continue;
+
+    yamlContent += `  - id: ${skillId}\n`;
+    yamlContent += `    file: skills/${skillId}/SKILL.md\n`;
+    yamlContent += `    description: ${skill.description}\n`;
+
+    if (skill.applies_when && Array.isArray(skill.applies_when)) {
+      yamlContent += '    applies_when:\n';
+      skill.applies_when.forEach(cond => {
+        yamlContent += `      - ${cond}\n`;
+      });
+    }
+
+    if (skill.always_load) {
+      yamlContent += '    always_load: true\n';
+    }
+
+    yamlContent += '\n';
+  }
+
+  await fs.writeFile(manifestYamlPath, yamlContent, 'utf-8');
+  console.log(chalk.cyan(`    + Generated ${manifestYamlPath}`));
+}
+
+async function updateAgentInstructions(agent, projectRoot) {
+  if (!agent.instructionFiles || agent.instructionFiles.length === 0) return;
+
+  const planningInstruction = `
+# AI Agent Skills - Planning Instruction
+
+You have access to a library of skills in your skills directory. Before starting any task:
+
+1. Read the skill manifest at skills/MANIFEST.yaml
+2. Based on the task description, select which skills are relevant
+3. Read only the selected skill files
+4. Then proceed with the task
+
+Always load skills marked with always_load: true.
+Do not load skills that are not relevant to the current task.
+`;
+
+  const markerStart = '<!-- MA-AGENTS-START -->';
+  const markerEnd = '<!-- MA-AGENTS-END -->';
+  const wrappedInstruction = `\n${markerStart}${planningInstruction}${markerEnd}\n`;
+
+  for (const fileName of agent.instructionFiles) {
+    const filePath = path.join(projectRoot, fileName);
+    let content = '';
+
+    if (fs.existsSync(filePath)) {
+      content = await fs.readFile(filePath, 'utf-8');
+
+      const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
+      if (regex.test(content)) {
+        content = content.replace(regex, wrappedInstruction.trim());
+      } else {
+        content += wrappedInstruction;
+      }
+    } else {
+      content = wrappedInstruction;
+    }
+
+    await fs.writeFile(filePath, content, 'utf-8');
+    console.log(chalk.cyan(`    + Updated ${fileName}`));
+  }
+}
+
 /**
  * Compare two semver strings. Returns -1, 0, or 1.
  */
@@ -252,6 +330,12 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
           delete manifest.skills[skillId];
           writeManifest(installPath, manifest);
           console.log(chalk.green(`    - Removed ${skill.name} from ${agent.name}`));
+
+          // Generate MANIFEST.yaml and update agent instruction files
+          await generateSkillsManifest(installPath, agent);
+          if (scope === 'project') {
+            await updateAgentInstructions(agent, process.cwd());
+          }
           continue;
         }
 
@@ -281,6 +365,12 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
           agentVersion: agent.version
         };
         writeManifest(installPath, manifest);
+
+        // Generate MANIFEST.yaml and update agent instruction files
+        await generateSkillsManifest(installPath, agent);
+        if (scope === 'project') {
+          await updateAgentInstructions(agent, process.cwd());
+        }
       }
     } catch (error) {
       console.log(chalk.red(`    x Failed: ${error.message}`));
@@ -330,6 +420,12 @@ async function uninstallSkill(skillId, agentIds, customPath = '', scope = 'proje
       writeManifest(installPath, manifest);
 
       console.log(chalk.green(`  - Removed ${skillId} v${installed.version} from ${agent.name}`));
+
+      // Generate MANIFEST.yaml and update agent instruction files
+      await generateSkillsManifest(installPath, agent);
+      if (scope === 'project') {
+        await updateAgentInstructions(agent, process.cwd());
+      }
     } catch (error) {
       console.log(chalk.red(`    x Failed: ${error.message}`));
     }
@@ -353,9 +449,9 @@ function getStatus(agentIds, customPath = '', scope = 'project') {
     const pathsToCheck = customPath
       ? [{ path: customPath, scope: 'custom' }]
       : [
-          { path: projectPath, scope: 'project' },
-          { path: globalPath, scope: 'global' }
-        ];
+        { path: projectPath, scope: 'project' },
+        { path: globalPath, scope: 'global' }
+      ];
 
     for (const { path: checkPath, scope: checkScope } of pathsToCheck) {
       const manifest = readManifest(checkPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

package/skills/README.md

@@ -7,7 +7,7 @@ This directory contains reusable skills for development workflows.
 ### 1. Git Workflow Skill
 **Directory:** `git-workflow-skill/`
 
-Mandatory feature branch workflow for Git operations. Enforces branch creation from dev, conventional commits, automatic PR creation, and returns to dev branch after push.
+**MANDATORY** feature branch workflow for ALL file-changing operations. Enforces branch creation via worktrees, conventional commits, automatic PR creation, and returns to dev branch after push. Agents MUST use this skill for every activity that modifies tracked repository files.
 
 **Usage:**
 ```bash

package/skills/git-workflow-skill/SKILL.md

@@ -1,3 +1,15 @@
+# Mandatory Usage Policy (CRITICAL)
+
+**This skill is MANDATORY for all activities that modify tracked files in this repository.**
+
+1.  **Before starting ANY work** that changes source code, config files, or documentation: You MUST run `./scripts/start-feature.sh` (or the equivalent `git worktree add`) to create an isolated feature branch and worktree.
+2.  **During development**: You MUST perform all file-writing activities inside the newly created worktree directory.
+3.  **After completing work**: You MUST run `./scripts/finish-feature.sh` (or the equivalent rebase/push/PR/cleanup sequence) to integrate your changes and clean up the worktree.
+
+**Failure to follow this workflow is a violation of repository standards.**
+
+---
+
 # Git Workflow (Worktree-Based)
 
 Multi-agent parallel development using git worktrees. Each agent gets an isolated working directory — no branch switching, no conflicts between agents.
@@ -168,10 +180,11 @@ git worktree prune
 
 ## Critical Rules
 
-- **NEVER** modify tracked files without being in a worktree on a feature branch
-- **NEVER** commit directly to `dev` or `main`
-- **ALWAYS** check if file is gitignored before applying this workflow
-- **ALWAYS** create a worktree before any tracked file changes
-- **ALWAYS** rebase on `dev` before pushing
-- **ALWAYS** use conventional commit format
-- **ALWAYS** add `.worktrees/` to your `.gitignore`
+- **NEVER** modify tracked files without being in a worktree on a feature branch.
+- **NEVER** commit directly to `dev` or `main`.
+- **ALWAYS** check if a file is gitignored before applying this workflow.
+- **ALWAYS** create a worktree **BEFORE** calling any file-writing tools (write_to_file, replace_file_content, etc.).
+- **ALWAYS** rebase on `dev` before pushing.
+- **ALWAYS** use conventional commit format.
+- **ALWAYS** add `.worktrees/` to your `.gitignore`.
+- **ALWAYS** finish the workflow by creating a PR and removing the worktree once work is verified.

package/skills/git-workflow-skill/skill.json

@@ -1,7 +1,21 @@
 {
   "name": "Git Workflow",
-  "description": "Worktree-based feature branch workflow for parallel multi-agent development with conventional commits and PR-based merging",
-  "version": "2.0.0",
+  "description": "MANDATORY worktree-based workflow for ALL file-changing activities. Enforces isolated feature branches, conventional commits, and PR-based merging.",
+  "version": "2.1.0",
   "author": "AI Agent Skills",
-  "tags": ["git", "worktrees", "workflow", "branching", "conventional-commits", "pull-requests", "multi-agent"]
-}
+  "tags": [
+    "git",
+    "worktrees",
+    "workflow",
+    "branching",
+    "conventional-commits",
+    "pull-requests",
+    "multi-agent"
+  ],
+  "applies_when": [
+    "committing changes",
+    "creating branches or PRs",
+    "any code writing or modification task"
+  ],
+  "always_load": true
+}

package/skills/js-ts-security-skill/skill.json

@@ -3,5 +3,16 @@
   "description": "Verify security of JavaScript and TypeScript codebases against OWASP Top 10 2025 standards",
   "version": "1.0.0",
   "author": "AI Agent Skills",
-  "tags": ["javascript", "typescript", "security", "OWASP", "vulnerability-scanning"]
-}
+  "tags": [
+    "javascript",
+    "typescript",
+    "security",
+    "OWASP",
+    "vulnerability-scanning"
+  ],
+  "applies_when": [
+    "writing or reviewing security-critical code",
+    "analyzing third-party dependencies",
+    "performing security audits"
+  ]
+}

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

@@ -9,5 +9,10 @@
         "json",
         "opentelemetry",
         "quality"
+    ],
+    "applies_when": [
+        "writing new service classes",
+        "reviewing or modifying existing log statements",
+        "adding error handling"
     ]
 }

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

@@ -8,5 +8,10 @@
         "quality",
         "policy",
         "tdd"
+    ],
+    "applies_when": [
+        "writing or reviewing public APIs",
+        "adding new public methods to a class",
+        "code review tasks"
     ]
 }

package/skills/test-generator/skill.json

@@ -3,5 +3,15 @@
   "description": "Generates comprehensive unit and integration tests",
   "version": "1.0.0",
   "author": "AI Agent Skills",
-  "tags": ["testing", "unit-tests", "integration-tests", "quality"]
-}
+  "tags": [
+    "testing",
+    "unit-tests",
+    "integration-tests",
+    "quality"
+  ],
+  "applies_when": [
+    "creating new code files",
+    "adding complex logic",
+    "refactoring existing code"
+  ]
+}

package/skills/vercel-react-best-practices/skill.json

@@ -4,5 +4,17 @@
   "version": "1.0.0",
   "author": "vercel-labs",
   "source": "https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices",
-  "tags": ["react", "nextjs", "performance", "optimization", "vercel", "best-practices"]
-}
+  "tags": [
+    "react",
+    "nextjs",
+    "performance",
+    "optimization",
+    "vercel",
+    "best-practices"
+  ],
+  "applies_when": [
+    "working on React or Next.js components",
+    "optimizing page performance",
+    "reviewing frontend code architecture"
+  ]
+}