feat: interactive install wizard + spec update for --skill install

docs/SKILLFLAG_SPEC.md

@@ -53,10 +53,12 @@ Skillflag is designed around these constraints:
 
 ### 3.2 Non-goals
 
-- Defining how a specific agent tool discovers skills on disk.
+- Defining how agent tools internally discover, load, or activate skills at runtime.
 - Defining a central skill registry, marketplace, signing infrastructure, or dependency installation mechanism.
 - Defining how installers resolve conflicts, pin versions, or manage lockfiles (those can exist, but are outside the core Skillflag interface).
 
+Note: Skillflag does define where installers place skill files (see skill-install companion spec). Runtime discovery and activation by the agent tool itself is out of scope.
+
 ## 4. Terminology
 
 - **Producer CLI**: The tool that _bundles_ skills and implements the Skillflag interface (e.g., `mycli`).
@@ -79,15 +81,33 @@ A producer CLI **MAY** additionally implement:
 
 Skillflag does **not** require any particular command substructure (`tool skills ...`) because the goal is a "`--help`-class" universal convention based on flags.
 
-## 6. Discovery: `--skill list`
+## 6. Optional convenience: `--skill install [<id>]`
+
+A Skillflag-compliant producer CLI **MAY** implement `--skill install [<id>]` as a convenience that combines export + install in a single step.
+
+Producers **MUST NOT** implement agent-specific path resolution.
+
+The `--skill install` convenience **MUST** delegate installation to a Skillflag-compliant installer (e.g. `skill-install`). Producers are responsible for skill discovery and export; installers are responsible for agent-specific placement.
+
+When invoked without required arguments (`agent`, `scope`) and stdin is a TTY, implementations **SHOULD** offer an interactive selection flow.
+
+The interactive behavior, prompts, defaults, and UX are implementation-defined.
+
+When invoked with all required arguments, it **MUST** behave equivalently to:
+
+```bash
+tool --skill export <id> | skill-install --agent <agent> --scope <scope>
+```
+
+## 7. Discovery: `--skill list`
 
-### 6.1 Behavior
+### 7.1 Behavior
 
 - `tool --skill list` **MUST** print the list of available Skill IDs to **stdout**.
 - Output **MUST NOT** include banners, progress text, or other non-data content on stdout.
 - Diagnostics and errors **MUST** go to **stderr**.
 
-### 6.2 Output format (text)
+### 7.2 Output format (text)
 
 - Each skill **MUST** appear on a single line.
 - The line **MUST** begin with the `Skill ID`.
@@ -103,12 +123,12 @@ If summaries are included:
 
 - `<summary>` **MUST NOT** contain newlines or tabs.
 
-### 6.3 Ordering
+### 7.3 Ordering
 
 - Output ordering **SHOULD** be stable and predictable.
 - Recommended: sort lexicographically by Skill ID.
 
-### 6.4 Optional JSON mode
+### 7.4 Optional JSON mode
 
 If `tool --skill list --json` is provided:
 
@@ -142,7 +162,7 @@ Field requirements:
 
 Optional fields MUST be omitted if not provided. Producers MUST NOT emit `null` values. Empty string (`""`) is invalid for `version` and `digest`.
 
-## 7. Viewing: `--skill show <id>` (optional)
+## 8. Viewing: `--skill show <id>` (optional)
 
 If implemented:
 
@@ -151,16 +171,16 @@ If implemented:
 
 This provides a “manpage-like” experience without OS-specific manpage infrastructure.
 
-## 8. Export: `--skill export <id>`
+## 9. Export: `--skill export <id>`
 
-### 8.1 Behavior
+### 9.1 Behavior
 
 - `tool --skill export <id>` **MUST** write the skill bundle to **stdout** as a tar stream.
 - The tar stream **MUST** contain exactly one top-level directory named `<id>/`.
 - The directory **MUST** include `<id>/SKILL.md`.
 - No additional output is permitted on stdout.
 
-### 8.2 Tar format requirements
+### 9.2 Tar format requirements
 
 To maximize portability, exporters:
 
@@ -175,7 +195,7 @@ Exporters **MUST** ensure:
 - No `..` path traversal segments.
 - All entries are relative under `<id>/`.
 
-### 8.3 Determinism
+### 9.3 Determinism
 
 For reproducible installs and caching:
 
@@ -187,13 +207,13 @@ For reproducible installs and caching:
 
 This ensures identical skill content produces identical tar output and matching digests.
 
-### 8.4 Error handling and exit codes
+### 9.4 Error handling and exit codes
 
 - Exit `0` on success.
 - Exit `1` on any error.
 - Write error details to **stderr**.
 
-## 9. Skill directory layout (bundling convention)
+## 10. Skill directory layout (bundling convention)
 
 Inside the producer CLI’s distribution artifact, skills **SHOULD** be stored under a dedicated resource path:
 
@@ -207,7 +227,7 @@ The producer CLI **MUST** map these bundled resources to the Skillflag interface
 
 This deliberately avoids any assumption about package managers or OS-level install roots.
 
-## 10. Skill ID conventions
+## 11. Skill ID conventions
 
 Skill IDs **SHOULD** be:
 
@@ -217,18 +237,11 @@ Skill IDs **SHOULD** be:
 
 Rationale: IDs appear in shell scripts and filesystem paths.
 
-## 11. Metadata (optional, minimal)
-
-Skillflag does not require a manifest file, but implementations **MAY** include metadata as YAML frontmatter at the top of `SKILL.md`.
-
-If metadata exists, it **SHOULD** be treated as advisory by installers.
-
-Critically:
+## 12. Metadata
 
-- **Producer CLIs MUST NOT execute** any bundled scripts as part of export.
-- Installers **SHOULD NOT execute** bundled scripts by default.
+Skill directories **MUST** conform to the Agent Skills specification (https://agentskills.io/specification). Skillflag does not define additional `SKILL.md` format requirements.
 
-## 12. Security considerations
+## 13. Security considerations
 
 Skillflag keeps the producer CLI in a “data export” role. That reduces risk, but does not eliminate it.
 
@@ -241,7 +254,7 @@ Recommendations:
 
 - Bundles may include binaries or scripts; installers should surface that fact clearly.
 
-## 13. Interoperability with a separate installer
+## 14. Interoperability with a separate installer
 
 Skillflag is designed to compose cleanly with a dedicated installer/adaptor CLI that knows how to install into specific agent tools and scopes.
 
@@ -260,33 +273,33 @@ The installer is responsible for:
 
 None of that logic belongs in the producer CLI.
 
-## 14. Examples
+## 15. Examples
 
-### 14.1 List skills
+### 15.1 List skills
 
 ```bash
 tool --skill list
 ```
 
-### 14.2 View the skill documentation (if supported)
+### 15.2 View the skill documentation (if supported)
 
 ```bash
 tool --skill show tmux
 ```
 
-### 14.3 Export and inspect without installing
+### 15.3 Export and inspect without installing
 
 ```bash
 tool --skill export tmux | tar -tf -
 ```
 
-### 14.4 Export and install via an adaptor
+### 15.4 Export and install via an adaptor
 
 ```bash
 tool --skill export tmux | skill-install --agent codex --scope user
 ```
 
-### 14.5 Export and manually place somewhere (no adaptor needed)
+### 15.5 Export and manually place somewhere (no adaptor needed)
 
 ```bash
 mkdir -p .agents/skills/tmux
@@ -295,13 +308,14 @@ tool --skill export tmux | tar -x -C .agents/skills
 
 (That last example assumes the installer semantics are simply “untar into a skills root”.)
 
-## 15. Conformance checklist
+## 16. Conformance checklist
 
 A producer CLI is **Skillflag-compliant** if:
 
 - [ ] `--skill list` outputs Skill IDs on stdout with no extra stdout noise.
 - [ ] `--skill list --json` includes `digest` for each skill.
 - [ ] `--skill export <id>` emits a tar stream on stdout.
+- [ ] (Optional) `--skill install [<id>]` follows the convenience behavior described in section 6.
 - [ ] The tar stream contains exactly one top-level directory `<id>/`.
 - [ ] `<id>/SKILL.md` exists in the exported stream.
 - [ ] Tar entries are deterministic (stable order, normalized metadata).
@@ -312,13 +326,13 @@ A producer CLI is **Skillflag-compliant** if:
 
 # `skill-install` companion spec (installer side)
 
-Scope: installs **one** skill bundle into **one** target agent/tool + scope.
+Scope: baseline behavior installs one skill bundle into one target agent/tool + scope. Implementations **MAY** additionally support multi-install in a single invocation (multiple sources, agents, and scopes).
 
 ### Motivation
 
 - **Skills are directories**, not just `SKILL.md`: they can include scripts, templates, references, assets, etc. (multiple tools describe skills this way). ([OpenAI Developers][1])
 - **Producer CLIs should not encode per-agent install logic.** The producer just exposes skill bundles (via Skillflag: `--skill list`, `--skill export <id>`). The installer maps to agent-specific locations.
-- **Users must opt in**: installing a CLI must not automatically install all of its skills into every local agent. So `skill-install` targets exactly one agent and one scope at a time.
+- **Users must opt in**: installing a CLI must not automatically install all of its skills into every local agent. A single explicit target remains the baseline, but implementations **MAY** offer explicit multi-target invocations.
 - **Cross-agent portability exists but paths differ**: several tools already read “portable” directories (notably `.agents/skills` and `~/.config/agents/skills`), while others have native roots like `.claude/skills`, `.codex/skills`, `.github/skills`, etc. ([Block][2])
 
 ## 1) Inputs `skill-install` accepts
@@ -328,6 +342,7 @@ Scope: installs **one** skill bundle into **one** target agent/tool + scope.
 Install from a local skill directory:
 
 - `PATH` **must** be a directory containing `SKILL.md` at its root.
+- Implementations **MAY** accept multiple `PATH` values in one command. If supported, each path is treated as an independent source skill bundle.
 
 Example:
 
@@ -355,9 +370,9 @@ producer --skill export tmux | skill-install --agent claude --scope user
 ### 2.1 Synopsis
 
 ```bash
-skill-install [PATH]
+skill-install [PATH ...]
   --agent <pi|opencode|codex|claude|portable|vscode|copilot|amp|factory|cursor|goose>
-  --scope <repo|user|cwd|parent|admin>
+  --scope <repo|user|cwd>
   [--root <path>]
   [--mode <copy|link>]
   [--force]
@@ -369,6 +384,8 @@ skill-install [PATH]
   [--legacy]        # only where a legacy target exists (vscode/copilot -> .claude/skills)
 ```
 
+Implementations **MAY** accept repeated and/or comma-separated `--agent` and `--scope` flags, and apply an install matrix across selected sources and targets.
+
 ### 2.2 Required flags
 
 - `--agent` is **required** unless `--dest` is provided.
@@ -383,11 +400,7 @@ Rationale: avoid silent installs into the wrong agent/tool.
 By default, `skill-install` **must** validate:
 
 - `SKILL.md` exists at bundle root.
-- YAML frontmatter exists and includes:
-  - `name` (string)
-  - `description` (string)
-
-This matches major implementations’ documented expectations. ([Claude Code][3])
+- `name` and `description` are present in `SKILL.md` metadata (as required by the Agent Skills specification).
 
 ### 3.2 Skill ID selection (destination folder name)
 
@@ -444,6 +457,8 @@ If the producer provides a digest (via `--skill list --json`), installers **shou
 
 ## 7) Destination mapping (what `--agent` + `--scope` means)
 
+The agent list below is maintained by the reference implementation and is not normative. Implementations MAY support additional agents. The `--dest` escape hatch provides forward compatibility for unlisted agents.
+
 This section is intentionally concrete and only covers widely-used tools with documented/observable conventions.
 
 ### 7.1 `--agent pi` (Pi / pi-mono)
@@ -462,18 +477,13 @@ OpenCode documents these locations (plus Claude-compatible ones it also searches
 
 ### 7.3 `--agent codex` (OpenAI Codex CLI / IDE)
 
-Codex documents multiple repo layers and user/admin/system scopes. ([OpenAI Developers][1])
+Codex documents repo and user-level scopes. ([OpenAI Developers][1])
 
 Default mapping:
 
 - `repo` → `<project-root>/.codex/skills/<skill_id>/`
 - `user` → `${CODEX_HOME:-~/.codex}/skills/<skill_id>/`
-- `admin` → `/etc/codex/skills/<skill_id>/` (if supported/allowed)
-
-Optional advanced repo scopes (because Codex distinguishes them):
-
 - `cwd` → `$PWD/.codex/skills/<skill_id>/`
-- `parent` → `$PWD/../.codex/skills/<skill_id>/` ([OpenAI Developers][1])
 
 ### 7.4 `--agent claude` (Claude Code)
 

package.json

@@ -51,6 +51,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@clack/prompts": "^1.0.1",
     "tar-stream": "^3.1.7"
   },
   "devDependencies": {

skills/skillflag/SKILL.md

@@ -47,6 +47,18 @@ Tar stream input (from producer):
 skillflag --skill export skillflag | skill-install --agent codex --scope repo
 ```
 
+Tar stream input with interactive target selection (when a TTY is available):
+
+```
+skillflag --skill export skillflag | skill-install
+```
+
+Show installer usage/help:
+
+```
+skill-install --help
+```
+
 ## Notes
 
 - `skillflag` is the producer interface; it never installs.