ma-agents 1.6.0 → 1.8.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/bin/cli.js

@@ -120,60 +120,113 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
   const skills = listSkills();
   const agents = listAgents();
 
+  let selectedSkillIds = preselectedSkill ? [preselectedSkill] : [];
+  let selectedAgentIds = preselectedAgents || [];
+  let installScope = 'project';
+  let installPath = customPath || '';
+
+  const existingStatus = getStatus([], '', 'project');
+  let isUpdate = false;
+
+  // Step 0: Check for existing installation ONLY in interactive mode (no preselected skill)
+  if (!preselectedSkill && !customPath && existingStatus.length > 0) {
+    console.log(chalk.cyan('\n Existing installation detected in project.'));
+
+    const { action } = await prompts({
+      type: 'select',
+      name: 'action',
+      message: 'What would you like to do?',
+      choices: [
+        { title: 'Update (add/remove skills)', value: 'update' },
+        { title: 'Clean reinstall (remove all first)', value: 'reinstall' },
+        { title: 'Uninstall all skills', value: 'uninstall' },
+        { title: 'Cancel', value: 'cancel' }
+      ]
+    });
+
+    if (!action || action === 'cancel') process.exit(0);
+
+    if (action === 'uninstall') {
+      const { confirmed } = await prompts({
+        type: 'confirm',
+        name: 'confirmed',
+        message: 'This will remove all ma-agents skills from this project. Are you sure?',
+        initial: false
+      });
+      if (!confirmed) process.exit(0);
+
+      for (const entry of existingStatus) {
+        for (const skillId of Object.keys(entry.skills)) {
+          await uninstallSkill(skillId, [entry.agent.id], '', 'project');
+        }
+      }
+      console.log(chalk.bold.green('\n All skills successfully removed!\n'));
+      return;
+    }
+
+    if (action === 'reinstall') {
+      for (const entry of existingStatus) {
+        for (const skillId of Object.keys(entry.skills)) {
+          await uninstallSkill(skillId, [entry.agent.id], '', 'project');
+        }
+      }
+      console.log(chalk.gray(' Clean slate prepared.'));
+    }
+
+    if (action === 'update') {
+      isUpdate = true;
+      // Pre-populate selections from existing status
+      const existingSkillIds = new Set();
+      const existingAgentIds = new Set();
+      existingStatus.forEach(entry => {
+        existingAgentIds.add(entry.agent.id);
+        Object.keys(entry.skills).forEach(id => existingSkillIds.add(id));
+      });
+      selectedSkillIds = Array.from(existingSkillIds);
+      selectedAgentIds = Array.from(existingAgentIds);
+    }
+  }
+
   // Step 1: Select skills
-  let selectedSkillIds;
-  if (preselectedSkill) {
-    selectedSkillIds = [preselectedSkill];
-  } else {
+  if (selectedSkillIds.length === 0 || isUpdate) {
     const { skills: chosen } = await prompts({
       type: 'multiselect',
       name: 'skills',
-      message: 'Which skills do you want to install?',
+      message: 'Select the skills you want to have installed:',
       choices: skills.map(s => ({
         title: chalk.white(s.name) + chalk.gray(` v${s.version} - ${s.description}`),
         value: s.id,
-        selected: false
+        selected: selectedSkillIds.includes(s.id)
       })),
       instructions: chalk.gray('  Use space to select, enter to confirm'),
       min: 1
     });
 
-    if (!chosen || chosen.length === 0) {
-      console.log(chalk.yellow('No skills selected. Exiting.'));
-      process.exit(0);
-    }
+    if (!chosen) process.exit(0);
     selectedSkillIds = chosen;
   }
 
   // Step 2: Select agents
-  let selectedAgentIds;
-  if (preselectedAgents && preselectedAgents.length > 0) {
-    selectedAgentIds = preselectedAgents;
-  } else {
+  if (selectedAgentIds.length === 0 || isUpdate) {
     const { agents: chosen } = await prompts({
       type: 'multiselect',
       name: 'agents',
-      message: 'Which coding agents do you want to install to?',
+      message: 'Select which coding agents to include:',
       choices: agents.map(a => ({
         title: chalk.white(a.name) + chalk.gray(` v${a.version} - ${a.description}`),
         value: a.id,
-        selected: false
+        selected: selectedAgentIds.includes(a.id)
       })),
       instructions: chalk.gray('  Use space to select, enter to confirm'),
       min: 1
     });
 
-    if (!chosen || chosen.length === 0) {
-      console.log(chalk.yellow('No agents selected. Exiting.'));
-      process.exit(0);
-    }
+    if (!chosen) process.exit(0);
     selectedAgentIds = chosen;
   }
 
-  // Step 3: Installation scope
-  let installPath = customPath || '';
-  let installScope = 'project';
-  if (!installPath) {
+  // Step 3: Scope (Skip if update, we already know it's project)
+  if (!isUpdate && !installPath) {
     const { pathChoice } = await prompts({
       type: 'select',
       name: 'pathChoice',
@@ -209,16 +262,33 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
   const { confirmed } = await prompts({
     type: 'confirm',
     name: 'confirmed',
-    message: 'Proceed with installation?',
+    message: isUpdate ? 'Apply changes?' : 'Proceed with installation?',
     initial: true
   });
 
   if (!confirmed) {
-    console.log(chalk.yellow('Installation cancelled.'));
+    console.log(chalk.yellow('Operation cancelled.'));
     process.exit(0);
   }
 
-  // Step 5: Install each skill (with upgrade detection)
+  // Step 5: Execution
+  if (isUpdate) {
+    // Identify removals
+    const currentlyInstalled = new Set();
+    existingStatus.forEach(entry => Object.keys(entry.skills).forEach(id => currentlyInstalled.add(id)));
+
+    const finalSkills = new Set(selectedSkillIds);
+    const toRemove = [...currentlyInstalled].filter(id => !finalSkills.has(id));
+
+    if (toRemove.length > 0) {
+      console.log(chalk.gray(`\n  Cleaning up ${toRemove.length} removed skills...`));
+      for (const skillId of toRemove) {
+        await uninstallSkill(skillId, selectedAgentIds, installPath, 'project');
+      }
+    }
+  }
+
+  // Install requested skills
   for (const skillId of selectedSkillIds) {
     try {
       await installSkill(skillId, selectedAgentIds, installPath, installScope, { force: !!forceFlag });
@@ -227,7 +297,7 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
     }
   }
 
-  console.log(chalk.bold.green('\n Installation complete!\n'));
+  console.log(chalk.bold.green('\n Done!\n'));
 }
 
 // --- Command handlers ---

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.6.0",
+  "version": "1.8.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

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

@@ -11,5 +11,11 @@
     "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"
+  ]
+}