feat: improve CLI help discoverability (SKILZ-66)

.speckit/features/02-skill-management/specify.md

@@ -81,22 +81,25 @@ skilz remove <skill-id> [--agent claude|opencode] [--project] [--yes]
 
 ### List Output (Default)
 ```
-Skill                          Version    Installed           Status
-─────────────────────────────────────────────────────────────────────
-spillwave/plantuml             f2489dcd   2025-01-15 14:32   up-to-date
-anthropics/web-artifacts       00756142   2025-01-15 14:33   outdated
-spillwave/design-doc-mermaid   e1c29a38   2025-01-15 14:34   up-to-date
+Agent    Skill                          Version    Mode     Status
+────────────────────────────────────────────────────────────────────────────
+claude   spillwave/plantuml             f2489dcd   [copy]   up-to-date
+gemini   anthropics/web-artifacts       00756142   [copy]   outdated
+claude   spillwave/design-doc-mermaid   e1c29a38   [copy]   up-to-date
 ```
 
 ### List Output (JSON)
 ```json
 [
   {
     "skill_id": "spillwave/plantuml",
+    "skill_name": "plantuml",
+    "agent": "claude",
     "git_sha": "f2489dcd...",
     "installed_at": "2025-01-15T14:32:00Z",
     "status": "up-to-date",
-    "path": "/Users/.../.claude/skills/plantuml"
+    "path": "/Users/.../.claude/skills/plantuml",
+    "project_level": false
   }
 ]
 ```

SKILZ-68-JIRA-descriptions.md

@@ -0,0 +1,97 @@
+# SKILZ-68 List Command Issues - JIRA Ticket Descriptions
+
+## SKILZ-68-A: Only two agents when --agent omitted
+
+### Observed
+When running `skilz list` without `--agent`, only skills from 2 agents are shown (claude, opencode), despite having 14+ agents in the registry.
+
+### Expected
+`skilz list` should scan all agents in the registry and show skills from all installed agents.
+
+### Repro Steps
+1. Install skills for multiple agents (e.g., claude, gemini, opencode)
+2. Run `skilz list` (no --agent flag)
+3. Only see skills from 2 agents instead of all agents
+
+### Root Cause
+Scanner uses hardcoded `AGENT_PATHS.keys()` which only contains ["claude", "opencode"], instead of `registry.list_agents()` which returns all 14+ agents.
+
+### Notes
+- Spec requires scanning all agents when --agent omitted
+- Registry has 14+ agents but scanner only checks 2
+- Affects user experience - users can't see all their installed skills
+
+---
+
+## SKILZ-68-B: Duplicate rows when --agent omitted
+
+### Observed
+When running `skilz list` without `--agent`, the same skill appears multiple times in the output.
+
+### Expected
+Each skill should appear only once, with an "Agent" column showing which agent it belongs to.
+
+### Repro Steps
+1. Install same skill for multiple agents
+2. Run `skilz list` (no --agent flag)
+3. See duplicate entries for the same skill
+
+### Root Cause
+- No "Agent" column in table output
+- Scanner scans overlapping directories (same skill in .claude/skills/ and .gemini/skills/)
+- No deduplication logic
+
+### Notes
+- Table format needs Agent column
+- JSON output already includes "agent" field
+- Spec shows table without Agent column, but this causes confusion
+
+---
+
+## SKILZ-68-C: Home installs not reliably discovered
+
+### Observed
+`skilz list` doesn't find skills installed at user-level for some agents (e.g., ~/.claude/skills/).
+
+### Expected
+`skilz list` should find all skills installed at user-level for all agents.
+
+### Repro Steps
+1. Install skill for claude: `skilz install skill --agent claude`
+2. Run `skilz list` (no --agent flag)
+3. Skill may not appear in list
+
+### Root Cause
+- Agent home dir mapping may not match actual on-disk layouts
+- Scanner may only scan project-level paths unless explicitly told otherwise
+- Path resolution issues between registry config and actual filesystem
+
+### Notes
+- Works for some agents but not others
+- May be related to config overrides or path resolution
+- Affects discoverability of installed skills
+
+---
+
+## SKILZ-68-D: Status always unknown
+
+### Observed
+Status column always shows "unknown" for all skills in `skilz list` output.
+
+### Expected
+Status should show "up-to-date", "outdated", or "unknown" based on registry comparison.
+
+### Repro Steps
+1. Install any skill
+2. Run `skilz list`
+3. Status column shows "unknown" for all skills
+
+### Root Cause
+- Status logic depends on registry identity via `lookup_skill(skill.skill_id)`
+- For git installs, `skill_id` is "git/skill-name" which doesn't exist in registry
+- Should use `skill.manifest.skill_id` (the original registry ID) instead
+
+### Notes
+- Registry skills should show proper status
+- Git-installed skills should show "unknown" (not in registry)
+- Spec shows status working, but implementation doesn't match

docs/USER_MANUAL.md

@@ -249,8 +249,9 @@ skilz list [options]
 **Options:**
 | Option | Description |
 |--------|-------------|
-| `--agent {claude,opencode}` | Filter by agent type |
+| `--agent {claude,opencode,...}` | Filter by agent type |
 | `--project` | List project-level skills instead of user-level |
+| `--all` | Scan all agents (default: top 5) |
 | `--json` | Output as JSON (for scripting) |
 | `-v, --verbose` | Show detailed output |
 
@@ -266,18 +267,21 @@ skilz list --project
 # List only Claude Code skills
 skilz list --agent claude
 
+# List skills from all agents (not just top 5)
+skilz list --all
+
 # Get JSON output for scripting
 skilz list --json
 ```
 
 **Table Output:**
 
 ```
-Skill                               Version   Installed   Status
-────────────────────────────────────────────────────────────────────────
-anthropics_skills/algorithmic-art   00756142  2025-01-15  up-to-date
-anthropics_skills/brand-guidelines  f2489dcd  2025-01-15  up-to-date
-anthropics_skills/theme-factory     e1c29a38  2025-01-15  outdated
+Agent         Skill                               Version   Mode     Status
+────────────────────────────────────────────────────────────────────────────────
+Claude Code   anthropics_skills/algorithmic-art   00756142  [copy]   up-to-date
+OpenAI Codex  anthropics_skills/brand-guidelines  f2489dcd  [copy]   up-to-date
+Claude Code   anthropics_skills/theme-factory     e1c29a38  [copy]   outdated
 ```
 
 **Status Values:**
@@ -300,6 +304,7 @@ anthropics_skills/theme-factory     e1c29a38  2025-01-15  outdated
     "status": "up-to-date",
     "path": "/Users/you/.claude/skills/algorithmic-art",
     "agent": "claude",
+    "agent_display_name": "Claude Code",
     "project_level": false
   }
 ]