ai-agent-skills 1.6.0 → 1.6.2

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" />
@@ -29,16 +29,14 @@
 ## Quick Start
 
 ```bash
-# Browse skills interactively
-npx ai-agent-skills browse
-
-# Install from our curated catalog
+# Install a skill to ALL agents with one command
 npx ai-agent-skills install frontend-design
 
-# Install for specific agents
+# Install to a specific agent only
 npx ai-agent-skills install frontend-design --agent cursor
-npx ai-agent-skills install frontend-design --agent codex
-npx ai-agent-skills install frontend-design --agent amp
+
+# Browse skills interactively
+npx ai-agent-skills browse
 
 # Install from any GitHub repo
 npx ai-agent-skills install anthropics/skills
@@ -48,7 +46,7 @@ npx ai-agent-skills install anthropics/skills/pdf    # specific skill
 npx ai-agent-skills install ./my-custom-skill
 ```
 
-That's it. The skill installs to the right location for your agent automatically.
+**One command. Every agent.** By default, skills install to Claude Code, Cursor, Codex, Amp, VS Code, Copilot, Goose, Letta, and OpenCode simultaneously.
 
 ## Why This Exists
 
@@ -58,7 +56,7 @@ This repo curates the best in one place. Quality over quantity. All skills follo
 
 ## Compatible Agents
 
-Works with **Claude Code**, **Cursor**, **Amp**, **VS Code**, **GitHub Copilot**, **Goose**, **Letta**, **OpenCode**, and **Claude.ai**.
+Works with **Claude Code**, **Cursor**, **Codex**, **Amp**, **VS Code**, **GitHub Copilot**, **Goose**, **Letta**, and **OpenCode**.
 
 ## Available Skills
 
@@ -109,6 +107,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 |
@@ -132,12 +131,11 @@ npx ai-agent-skills list
 npx ai-agent-skills list --category development
 npx ai-agent-skills list --installed --agent cursor
 
-# Install from catalog, GitHub, or local path
-npx ai-agent-skills install <name>                    # from catalog
-npx ai-agent-skills install <owner/repo>              # from GitHub
-npx ai-agent-skills install <owner/repo/skill>        # specific skill from GitHub
-npx ai-agent-skills install ./path                    # from local path
-npx ai-agent-skills install <name> --agent cursor     # for specific agent
+# Install (defaults to ALL agents)
+npx ai-agent-skills install <name>                    # installs to ALL agents
+npx ai-agent-skills install <name> --agent cursor     # install to specific agent only
+npx ai-agent-skills install <owner/repo>              # from GitHub (all agents)
+npx ai-agent-skills install ./path                    # from local path (all agents)
 npx ai-agent-skills install <name> --dry-run          # preview only
 
 # Manage installed skills
@@ -155,15 +153,17 @@ npx ai-agent-skills config --default-agent cursor
 
 ### Supported Agents
 
+By default, `install` targets **all agents**. Use `--agent <name>` to install to a specific one.
+
 | Agent | Flag | Install Location |
 |-------|------|------------------|
-| Claude Code | `--agent claude` (default) | `~/.claude/skills/` |
+| Claude Code | `--agent claude` | `~/.claude/skills/` |
 | Cursor | `--agent cursor` | `.cursor/skills/` |
+| Codex | `--agent codex` | `~/.codex/skills/` |
 | Amp | `--agent amp` | `~/.amp/skills/` |
 | VS Code / Copilot | `--agent vscode` | `.github/skills/` |
 | Goose | `--agent goose` | `~/.config/goose/skills/` |
-| OpenCode | `--agent opencode` | `~/.opencode/skills/` |
-| Codex | `--agent codex` | `~/.codex/skills/` |
+| OpenCode | `--agent opencode` | `~/.opencode/skill/` |
 | Letta | `--agent letta` | `~/.letta/skills/` |
 | Portable | `--agent project` | `.skills/` (works with any agent) |
 

package/cli.js

@@ -151,6 +151,7 @@ function parseArgs(args) {
     param: null,
     agents: [],           // New: array of agents
     allAgents: false,     // New: --all-agents flag
+    explicitAgent: false, // Track if user explicitly specified agent(s)
     installed: false,
     all: false,
     dryRun: false,
@@ -163,6 +164,7 @@ function parseArgs(args) {
 
     // --agents claude,cursor,codex (multiple agents)
     if (arg === '--agents') {
+      result.explicitAgent = true;
       const value = args[i + 1] || '';
       value.split(',').forEach(a => {
         const agent = a.trim();
@@ -174,6 +176,7 @@ function parseArgs(args) {
     }
     // --agent cursor (single agent, backward compatible)
     else if (arg === '--agent' || arg === '-a') {
+      result.explicitAgent = true;
       let agentValue = args[i + 1] || defaultAgent;
       agentValue = agentValue.replace(/^-+/, '');
       if (validAgents.includes(agentValue) && !result.agents.includes(agentValue)) {
@@ -183,6 +186,7 @@ function parseArgs(args) {
     }
     // --all-agents (install to all known agents)
     else if (arg === '--all-agents') {
+      result.explicitAgent = true;
       result.allAgents = true;
     }
     else if (arg === '--installed' || arg === '-i') {
@@ -205,6 +209,7 @@ function parseArgs(args) {
     else if (arg.startsWith('--')) {
       const potentialAgent = arg.replace(/^--/, '');
       if (validAgents.includes(potentialAgent)) {
+        result.explicitAgent = true;
         if (!result.agents.includes(potentialAgent)) {
           result.agents.push(potentialAgent);
         }
@@ -1055,7 +1060,8 @@ ${colors.bold}Commands:${colors.reset}
   ${colors.green}list${colors.reset}                             List all available skills
   ${colors.green}list --installed${colors.reset}                 List installed skills for an agent
   ${colors.green}list --category <cat>${colors.reset}            Filter by category
-  ${colors.green}install <name>${colors.reset}                   Install a skill from catalog
+  ${colors.green}install <name>${colors.reset}                   Install to ALL agents (default)
+  ${colors.green}install <name> --agent cursor${colors.reset}    Install to specific agent only
   ${colors.green}install <owner/repo>${colors.reset}             Install from GitHub repository
   ${colors.green}install ./path${colors.reset}                   Install from local path
   ${colors.green}install <name> --dry-run${colors.reset}         Preview installation without changes
@@ -1069,39 +1075,36 @@ ${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 single agent (default: claude)
+  ${colors.cyan}--agent <name>${colors.reset}       Target specific agent (install defaults to ALL)
   ${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/
-  ${colors.cyan}cursor${colors.reset}   .cursor/skills/ in current project
+${colors.bold}Agents:${colors.reset} (install targets ALL by default)
+  ${colors.cyan}claude${colors.reset}   ~/.claude/skills/
+  ${colors.cyan}cursor${colors.reset}   .cursor/skills/ (project)
+  ${colors.cyan}codex${colors.reset}    ~/.codex/skills/
   ${colors.cyan}amp${colors.reset}      ~/.amp/skills/
-  ${colors.cyan}vscode${colors.reset}   .github/skills/ in current project
+  ${colors.cyan}vscode${colors.reset}   .github/skills/ (project)
   ${colors.cyan}copilot${colors.reset}  .github/skills/ (alias for vscode)
   ${colors.cyan}goose${colors.reset}    ~/.config/goose/skills/
   ${colors.cyan}opencode${colors.reset} ~/.opencode/skill/
-  ${colors.cyan}codex${colors.reset}    ~/.codex/skills/
   ${colors.cyan}letta${colors.reset}    ~/.letta/skills/
-  ${colors.cyan}project${colors.reset}  .skills/ in current directory (portable)
+  ${colors.cyan}project${colors.reset}  .skills/ (portable)
 
 ${colors.bold}Categories:${colors.reset}
   development, document, creative, business, productivity
 
 ${colors.bold}Examples:${colors.reset}
   npx ai-agent-skills browse                              # Interactive browser
-  npx ai-agent-skills install frontend-design             # Install from catalog
+  npx ai-agent-skills install frontend-design             # Install to ALL agents
+  npx ai-agent-skills install pdf --agent cursor          # Install to Cursor only
+  npx ai-agent-skills install pdf --agents claude,cursor  # Install to specific agents
   npx ai-agent-skills install anthropics/skills           # Install from GitHub
-  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
@@ -1207,7 +1210,8 @@ function setConfig(key, value) {
 // ============ MAIN CLI ============
 
 const args = process.argv.slice(2);
-const { command, param, agents, installed, dryRun, category, tags, all } = parseArgs(args);
+const { command, param, agents, explicitAgent, installed, dryRun, category, tags, all } = parseArgs(args);
+const ALL_AGENTS = Object.keys(AGENT_PATHS);
 
 // Handle config commands specially
 if (command === 'config') {
@@ -1252,11 +1256,12 @@ 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 <name> [--agents claude,cursor] [--all-agents]');
+      log('Usage: npx ai-agent-skills install <name> [--agent cursor]');
       process.exit(1);
     }
-    // Install to all specified agents
-    for (const agent of agents) {
+    // Default to ALL agents when no agent explicitly specified
+    const installTargets = explicitAgent ? agents : ALL_AGENTS;
+    for (const agent of installTargets) {
       if (isLocalPath(param)) {
         installFromLocalPath(param, agent, dryRun);
       } else if (isGitHubUrl(param)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-skills",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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
     }
   ]
 }