ai-agent-skills 1.2.3 → 1.6.1

package/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/skills-39-blue?style=flat-square" alt="Skills" />
+  <img src="https://img.shields.io/badge/skills-40-blue?style=flat-square" alt="Skills" />
   <img src="https://img.shields.io/badge/agents-10+-green?style=flat-square" alt="Compatible Agents" />
   <img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License" />
   <img src="https://img.shields.io/npm/v/ai-agent-skills?style=flat-square&color=red" alt="npm" />
@@ -109,6 +109,7 @@ Works with **Claude Code**, **Cursor**, **Amp**, **VS Code**, **GitHub Copilot**
 ### Productivity
 | Skill | Description |
 |-------|-------------|
+| `ask-questions-if-underspecified` | Clarify requirements before implementing |
 | `doc-coauthoring` | Co-author docs, proposals, specs with structured workflow |
 | `job-application` | Cover letters and applications using your CV |
 | `qa-regression` | Automated regression testing with Playwright |

package/cli.js

@@ -143,10 +143,14 @@ function getAvailableSkills() {
 
 function parseArgs(args) {
   const config = loadConfig();
+  const validAgents = Object.keys(AGENT_PATHS);
+  const defaultAgent = config.defaultAgent || 'claude';
+
   const result = {
     command: null,
     param: null,
-    agent: config.defaultAgent || 'claude',
+    agents: [],           // New: array of agents
+    allAgents: false,     // New: --all-agents flag
     installed: false,
     all: false,
     dryRun: false,
@@ -154,17 +158,33 @@ function parseArgs(args) {
     category: null
   };
 
-  const validAgents = Object.keys(AGENT_PATHS);
-
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
-    if (arg === '--agent' || arg === '-a') {
-      let agentValue = args[i + 1] || 'claude';
+    // --agents claude,cursor,codex (multiple agents)
+    if (arg === '--agents') {
+      const value = args[i + 1] || '';
+      value.split(',').forEach(a => {
+        const agent = a.trim();
+        if (validAgents.includes(agent) && !result.agents.includes(agent)) {
+          result.agents.push(agent);
+        }
+      });
+      i++;
+    }
+    // --agent cursor (single agent, backward compatible)
+    else if (arg === '--agent' || arg === '-a') {
+      let agentValue = args[i + 1] || defaultAgent;
       agentValue = agentValue.replace(/^-+/, '');
-      result.agent = validAgents.includes(agentValue) ? agentValue : 'claude';
+      if (validAgents.includes(agentValue) && !result.agents.includes(agentValue)) {
+        result.agents.push(agentValue);
+      }
       i++;
     }
+    // --all-agents (install to all known agents)
+    else if (arg === '--all-agents') {
+      result.allAgents = true;
+    }
     else if (arg === '--installed' || arg === '-i') {
       result.installed = true;
     }
@@ -185,7 +205,9 @@ function parseArgs(args) {
     else if (arg.startsWith('--')) {
       const potentialAgent = arg.replace(/^--/, '');
       if (validAgents.includes(potentialAgent)) {
-        result.agent = potentialAgent;
+        if (!result.agents.includes(potentialAgent)) {
+          result.agents.push(potentialAgent);
+        }
       } else if (!result.command) {
         result.command = arg;
       }
@@ -197,6 +219,17 @@ function parseArgs(args) {
     }
   }
 
+  // Resolve final agents list
+  if (result.allAgents) {
+    result.agents = [...validAgents];
+  } else if (result.agents.length === 0) {
+    // Use config agents or default
+    const configAgents = config.agents && config.agents.length > 0
+      ? config.agents.filter(a => validAgents.includes(a))
+      : [];
+    result.agents = configAgents.length > 0 ? configAgents : [defaultAgent];
+  }
+
   return result;
 }
 
@@ -1036,12 +1069,14 @@ ${colors.bold}Commands:${colors.reset}
   ${colors.green}help${colors.reset}                             Show this help
 
 ${colors.bold}Options:${colors.reset}
-  ${colors.cyan}--agent <name>${colors.reset}   Target agent (default: claude)
-  ${colors.cyan}--installed${colors.reset}      Show only installed skills (with list)
-  ${colors.cyan}--dry-run, -n${colors.reset}    Preview changes without applying
-  ${colors.cyan}--category <c>${colors.reset}   Filter by category
-  ${colors.cyan}--all${colors.reset}            Apply to all (with update)
-  ${colors.cyan}--version, -v${colors.reset}    Show version number
+  ${colors.cyan}--agent <name>${colors.reset}       Target single agent (default: claude)
+  ${colors.cyan}--agents <list>${colors.reset}      Target multiple agents (comma-separated)
+  ${colors.cyan}--all-agents${colors.reset}         Target ALL known agents at once
+  ${colors.cyan}--installed${colors.reset}          Show only installed skills (with list)
+  ${colors.cyan}--dry-run, -n${colors.reset}        Preview changes without applying
+  ${colors.cyan}--category <c>${colors.reset}       Filter by category
+  ${colors.cyan}--all${colors.reset}                Apply to all (with update)
+  ${colors.cyan}--version, -v${colors.reset}        Show version number
 
 ${colors.bold}Agents:${colors.reset}
   ${colors.cyan}claude${colors.reset}   (default) ~/.claude/skills/
@@ -1065,6 +1100,8 @@ ${colors.bold}Examples:${colors.reset}
   npx ai-agent-skills install anthropics/skills/pdf       # Install specific skill from GitHub
   npx ai-agent-skills install ./my-skill                  # Install from local path
   npx ai-agent-skills install pdf --agent cursor          # Install for Cursor
+  npx ai-agent-skills install pdf --agents claude,cursor  # Install for multiple agents
+  npx ai-agent-skills install pdf --all-agents            # Install for ALL agents
   npx ai-agent-skills install pdf --dry-run               # Preview install
   npx ai-agent-skills list --category development
   npx ai-agent-skills search testing
@@ -1127,21 +1164,32 @@ function showConfig() {
   log(`${colors.dim}File: ${CONFIG_FILE}${colors.reset}\n`);
 
   log(`${colors.bold}defaultAgent:${colors.reset} ${config.defaultAgent || 'claude'}`);
+  log(`${colors.bold}agents:${colors.reset}       ${config.agents ? config.agents.join(', ') : '(not set, uses defaultAgent)'}`);
   log(`${colors.bold}autoUpdate:${colors.reset}   ${config.autoUpdate || false}`);
 
-  log(`\n${colors.dim}Edit with: npx ai-agent-skills config --default-agent <agent>${colors.reset}`);
+  log(`\n${colors.dim}Set default agents: npx ai-agent-skills config --agents claude,cursor${colors.reset}`);
 }
 
 function setConfig(key, value) {
   const config = loadConfig();
+  const validAgents = Object.keys(AGENT_PATHS);
 
   if (key === 'default-agent' || key === 'defaultAgent') {
     if (!AGENT_PATHS[value]) {
       error(`Invalid agent: ${value}`);
-      log(`Valid agents: ${Object.keys(AGENT_PATHS).join(', ')}`);
+      log(`Valid agents: ${validAgents.join(', ')}`);
       return false;
     }
     config.defaultAgent = value;
+  } else if (key === 'agents') {
+    // Parse comma-separated agents list
+    const agentsList = value.split(',').map(a => a.trim()).filter(a => validAgents.includes(a));
+    if (agentsList.length === 0) {
+      error(`No valid agents in: ${value}`);
+      log(`Valid agents: ${validAgents.join(', ')}`);
+      return false;
+    }
+    config.agents = agentsList;
   } else if (key === 'auto-update' || key === 'autoUpdate') {
     config.autoUpdate = value === 'true' || value === true;
   } else {
@@ -1159,7 +1207,7 @@ function setConfig(key, value) {
 // ============ MAIN CLI ============
 
 const args = process.argv.slice(2);
-const { command, param, agent, installed, dryRun, category, tags, all } = parseArgs(args);
+const { command, param, agents, installed, dryRun, category, tags, all } = parseArgs(args);
 
 // Handle config commands specially
 if (command === 'config') {
@@ -1184,13 +1232,16 @@ if (command === 'config') {
 switch (command || 'help') {
   case 'browse':
   case 'b':
-    browseSkills(agent);
+    browseSkills(agents[0]);
     break;
 
   case 'list':
   case 'ls':
     if (installed) {
-      listInstalledSkills(agent);
+      for (let i = 0; i < agents.length; i++) {
+        if (i > 0) log('');
+        listInstalledSkills(agents[i]);
+      }
     } else {
       listSkills(category, tags);
     }
@@ -1201,16 +1252,18 @@ switch (command || 'help') {
   case 'add':
     if (!param) {
       error('Please specify a skill name, GitHub repo, or local path.');
-      log('Usage: npx ai-agent-skills install <skill-name|owner/repo|./path> [--agent <agent>] [--dry-run]');
+      log('Usage: npx ai-agent-skills install <name> [--agents claude,cursor] [--all-agents]');
       process.exit(1);
     }
-    // Smart detection: GitHub URL, local path, or catalog skill
-    if (isLocalPath(param)) {
-      installFromLocalPath(param, agent, dryRun);
-    } else if (isGitHubUrl(param)) {
-      installFromGitHub(param, agent, dryRun);
-    } else {
-      installSkill(param, agent, dryRun);
+    // Install to all specified agents
+    for (const agent of agents) {
+      if (isLocalPath(param)) {
+        installFromLocalPath(param, agent, dryRun);
+      } else if (isGitHubUrl(param)) {
+        installFromGitHub(param, agent, dryRun);
+      } else {
+        installSkill(param, agent, dryRun);
+      }
     }
     break;
 
@@ -1219,23 +1272,29 @@ switch (command || 'help') {
   case 'rm':
     if (!param) {
       error('Please specify a skill name.');
-      log('Usage: npx ai-agent-skills uninstall <skill-name> [--agent <agent>]');
+      log('Usage: npx ai-agent-skills uninstall <name> [--agents claude,cursor]');
       process.exit(1);
     }
-    uninstallSkill(param, agent, dryRun);
+    for (const agent of agents) {
+      uninstallSkill(param, agent, dryRun);
+    }
     break;
 
   case 'update':
   case 'upgrade':
     if (all) {
-      updateAllSkills(agent, dryRun);
+      for (const agent of agents) {
+        updateAllSkills(agent, dryRun);
+      }
     } else if (!param) {
       error('Please specify a skill name or use --all.');
-      log('Usage: npx ai-agent-skills update <skill-name> [--agent <agent>]');
-      log('       npx ai-agent-skills update --all [--agent <agent>]');
+      log('Usage: npx ai-agent-skills update <name> [--agents claude,cursor]');
+      log('       npx ai-agent-skills update --all [--agents claude,cursor]');
       process.exit(1);
     } else {
-      updateSkill(param, agent, dryRun);
+      for (const agent of agents) {
+        updateSkill(param, agent, dryRun);
+      }
     }
     break;
 
@@ -1276,7 +1335,9 @@ switch (command || 'help') {
   default:
     // If command looks like a skill name, try to install it
     if (getAvailableSkills().includes(command)) {
-      installSkill(command, agent, dryRun);
+      for (const agent of agents) {
+        installSkill(command, agent, dryRun);
+      }
     } else {
       error(`Unknown command: ${command}`);
       showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-skills",
-  "version": "1.2.3",
+  "version": "1.6.1",
   "description": "Install curated AI agent skills with one command. Works with Claude Code, Cursor, Amp, VS Code, and all Agent Skills compatible tools.",
   "main": "cli.js",
   "bin": {

package/skills/ask-questions-if-underspecified/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ask-questions-if-underspecified
+description: Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.
+---
+
+# Ask Questions If Underspecified
+
+## Goal
+
+Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
+
+## Workflow
+
+### 1) Decide whether the request is underspecified
+
+Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+- Define the objective (what should change vs stay the same)
+- Define "done" (acceptance criteria, examples, edge cases)
+- Define scope (which files/components/users are in/out)
+- Define constraints (compatibility, performance, style, deps, time)
+- Identify environment (language/runtime versions, OS, build/test runner)
+- Clarify safety/reversibility (data migration, rollout/rollback, risk)
+
+If multiple plausible interpretations exist, assume it is underspecified.
+
+### 2) Ask must-have questions first (keep it small)
+
+Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
+
+Make questions easy to answer:
+- Optimize for scannability (short, numbered questions; avoid paragraphs)
+- Offer multiple-choice options when possible
+- Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
+- Include a fast-path response (e.g., reply `defaults` to accept all recommended/default choices)
+- Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
+- Separate "Need to know" from "Nice to know" if that reduces friction
+- Structure options so the user can respond with compact decisions (e.g., `1b 2a 3c`); restate the chosen options in plain language to confirm
+
+### 3) Pause before acting
+
+Until must-have answers arrive:
+- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
+- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
+
+If the user explicitly asks you to proceed without answers:
+- State your assumptions as a short numbered list
+- Ask for confirmation; proceed only after they confirm or correct them
+
+### 4) Confirm interpretation, then proceed
+
+Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
+
+## Question templates
+
+- "Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
+- "Which of these should it be? A) ... B) ... C) ... (pick one)"
+- "What would you consider 'done'? For example: ..."
+- "Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
+- Use numbered questions with lettered options and a clear reply format
+
+```text
+1) Scope?
+a) Minimal change (default)
+b) Refactor while touching the area
+c) Not sure - use default
+2) Compatibility target?
+a) Current project defaults (default)
+b) Also support older versions: <specify>
+c) Not sure - use default
+
+Reply with: defaults (or 1a 2a)
+```
+
+## Anti-patterns
+
+- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
+- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.
+
+---
+
+*Originally created by [@thsottiaux](https://x.com/thsottiaux)*

package/skills.json

@@ -1,7 +1,7 @@
 {
   "version": "1.2.2",
-  "updated": "2025-12-25T00:00:00Z",
-  "total": 39,
+  "updated": "2026-01-01T00:00:00Z",
+  "total": 40,
   "skills": [
     {
       "name": "frontend-design",
@@ -315,6 +315,20 @@
       "featured": true,
       "verified": true
     },
+    {
+      "name": "ask-questions-if-underspecified",
+      "description": "Clarify requirements before implementing. Ask 1-5 must-have questions to avoid wrong work. Use when requests are ambiguous, have multiple valid interpretations, or lack key details like scope, constraints, or acceptance criteria.",
+      "category": "productivity",
+      "author": "thsottiaux",
+      "source": "skillcreatorai/Ai-Agent-Skills",
+      "license": "MIT",
+      "path": "skills/ask-questions-if-underspecified",
+      "tags": ["clarification", "requirements", "workflow", "codex"],
+      "stars": 100,
+      "downloads": 0,
+      "featured": true,
+      "verified": true
+    },
     {
       "name": "artifacts-builder",
       "description": "Create elaborate HTML artifacts using React, Tailwind CSS, and shadcn/ui. Use for building interactive web components and demos.",
@@ -540,7 +554,7 @@
       "id": "productivity",
       "name": "Productivity",
       "description": "Productivity and workflow skills",
-      "count": 11
+      "count": 12
     }
   ]
 }