feat: multi-skill install with interactive selection, --list, and --skill flags

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thanks for your interest in contributing! Here's how you can help.
 git clone https://github.com/sametcelikbicak/rolecraft.git
 cd rolecraft
 npm link                  # now `rolecraft` runs from your local checkout
-npm test                  # 676+ tests should pass
+npm test                  # 721+ tests should pass
 ```
 
 **Requirements:** Node.js >= 20, no other dependencies.

README.md

@@ -299,7 +299,7 @@ cd rolecraft
 npm link                   # rolecraft CLI runs from local checkout
 npm install                # for docs site (VitePress)
 npm run docs:dev           # local docs preview
-npm test                   # 678 tests, 0 fails expected
+npm test                   # 721+ tests, 0 fails expected
 ```
 
 [→ Contributing guide](CONTRIBUTING.md)

bin/rolecraft.js

@@ -81,7 +81,8 @@ ${agentFlags.join('\n')}
   --frozen-lockfile  Fail if skill already installed
   --symlink          Install as symlink instead of copy
   --copy             Install as copy (default)
-  --interactive      Choose and install a skill from search results
+  --list             List available skills from a source without installing
+  --skill <names>    Install specific skills by name (comma-separated, e.g. "skill1,skill2")
 
 Examples:
   rolecraft install ./my-skill
@@ -128,6 +129,12 @@ export async function main() {
       options.dryRun = flags.includes('--dry-run')
       options.yes = flags.includes('--yes') || flags.includes('-y')
       options.noMcp = flags.includes('--no-mcp')
+      options.list = flags.includes('--list')
+
+      const skillIndex = flags.indexOf('--skill')
+      if (skillIndex !== -1 && flags[skillIndex + 1] && !flags[skillIndex + 1].startsWith('-')) {
+        options.skill = flags[skillIndex + 1].split(',').map(s => s.trim())
+      }
 
       await installCommand(source, options)
       break

docs/commands/install.md

@@ -2,6 +2,10 @@
 
 Install a skill from a local path, GitHub repository, or npm package.
 
+Supports **single-skill** and **multi-skill** repositories. If a source contains
+multiple `SKILL.md` files (e.g. under `skills/`), you will be prompted to
+select which ones to install.
+
 ## Usage
 
 ```bash
@@ -27,9 +31,11 @@ Shorthand `owner/repo`:
 ```bash
 rolecraft install sametcelikbicak/task-decomposer
 rolecraft install sametcelikbicak/coverage-guard
+rolecraft install mattpocock/skills
 ```
 
-The CLI clones with `--depth 1`, finds `SKILL.md` recursively, installs it, and cleans up.
+The CLI clones with `--depth 1`, discovers all `SKILL.md` files (including
+those under `skills/`, `.agents/skills/`, etc.), and lets you choose.
 
 ### npm package
 
@@ -42,7 +48,18 @@ rolecraft install npm:package@1.0.0
 rolecraft install npm:@scope/package@latest
 ```
 
-The CLI fetches package metadata from the npm registry, downloads and extracts the tarball, finds `SKILL.md` recursively, installs it, and cleans up.
+The CLI fetches package metadata from the npm registry, downloads and extracts
+the tarball, finds `SKILL.md` recursively, installs it, and cleans up.
+
+## Selection flags
+
+| Flag                      | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `--list`                  | List available skills from the source without installing |
+| `--skill <names>`         | Install specific skills by name (comma-separated)      |
+
+Without these flags and with more than one skill found, you will be prompted
+interactively to select which skills to install.
 
 ## Scope flags
 
@@ -74,6 +91,15 @@ rolecraft install ./my-skill
 # Install from GitHub
 rolecraft install sametcelikbicak/task-decomposer
 
+# Install from a multi-skill repo (interactive selection)
+rolecraft install mattpocock/skills
+
+# List skills in a repo without installing
+rolecraft install mattpocock/skills --list
+
+# Install specific skills by name (comma-separated)
+rolecraft install mattpocock/skills --skill "grill-me,tdd"
+
 # Install from npm
 rolecraft install npm:some-skill-package
 rolecraft install npm:@org/skill-package@1.0.0
@@ -96,3 +122,81 @@ rolecraft install ./my-skill --dry-run
 # Fail if already installed
 rolecraft install ./my-skill --frozen-lockfile
 ```
+
+## Multi-skill repositories
+
+When a source contains multiple `SKILL.md` files (e.g., `mattpocock/skills` has
+15+ skills under `skills/engineering/` and `skills/productivity/`), the CLI:
+
+1. Discovers all skills by scanning `skills/`, `.agents/skills/`, and other
+   known container directories, plus a recursive fallback search (max depth 3).
+2. If `--list` is passed, prints all available skills and exits.
+3. If `--skill` is passed, installs only the matching skills.
+4. If `--yes` is passed, installs all skills without prompting.
+5. Otherwise, shows an interactive numbered list to select skills.
+
+Each skill is installed to its own subdirectory (slug-based name) under the
+target agent's skills directory.
+
+### Interactive selection example
+
+```text
+$ rolecraft install mattpocock/skills
+
+Resolving skills...
+Found 15 skill(s)
+
+  1. ask-matt
+      slug: ask-matt
+  2. domain-modeling
+      slug: domain-modeling
+  3. diagnosing-bugs
+      slug: diagnosing-bugs
+  4. grill-me
+      slug: grill-me
+  5. grill-with-docs
+      slug: grill-with-docs
+  6. grilling
+      slug: grilling
+  ...
+
+Enter numbers (space-separated) to select, "all" for all, or press Enter to confirm selection: 4 5
+
+   grill-me selected
+   grill-with-docs selected
+```
+
+### `--list` output example
+
+```text
+$ rolecraft install mattpocock/skills --list
+
+Found 15 skill(s)
+
+  ask-matt
+    Slug:       ask-matt
+    Owner:      mattpocock
+    Description: Ask which skill or flow fits your situation
+    Files:      SKILL.md
+
+  grill-me
+    Slug:       grill-me
+    Owner:      mattpocock
+    Description: Get relentlessly interviewed about a plan or design
+    Files:      SKILL.md
+
+  ...
+```
+
+### `--skill` usage example
+
+```bash
+# Install only specific skills by name (comma-separated)
+rolecraft install mattpocock/skills --skill "grill-me,tdd"
+
+# Install a single skill
+rolecraft install mattpocock/skills --skill diagnose-bugs
+
+# Non-interactive: install all skills with --yes
+rolecraft install mattpocock/skills --yes --global
+```