Priority: high (correctness, not feature) · Surfaced during a side-by-side review against gh skill in cli/cli.
Problem
Two related defects in the agent-help surface:
src/cli/agent-help.ts::allCommands does not include the skills metas (`skillsListMeta`, `skillsAddMeta`, `skillsRemoveMeta`). These metas are defined in `src/cli/metadata/plugin-skills.ts` and imported by `src/cli/commands/plugin-skills.ts` for help text, but never wired into the agent-help tree. An AI agent calling `allagents --agent-help` cannot discover that `skills list / add / remove` exist.
- Each skills meta's `command` field is labeled `'plugin skills list'` / `'plugin skills remove'` / `'plugin skills add'` — but the runtime command path is `skills list` / `skills remove` / `skills add` because `skillsCmd` is registered as a top-level group in `src/cli/index.ts` (not under `pluginCmd`). Even if defect (1) were fixed, the meta's `command` field would direct an agent to the wrong command path.
This is also visible in normal JSON output today, where the envelope's `command` field is wrong:
```json
{
"success": true,
"command": "plugin skills list", ← wrong; actual path is "skills list"
"data": { "scope": "all", "skills": [] }
}
```
Current behavior
```bash
$ allagents --agent-help | jq '.commands | map(.command)'
[
"workspace init",
"update",
"workspace status",
"plugin install",
"plugin uninstall",
"plugin marketplace list",
"plugin marketplace add",
"plugin marketplace remove",
"plugin marketplace update",
"plugin marketplace browse",
"plugin list",
"plugin validate",
"self update"
]
$ allagents --agent-help skills
Unknown command: skills
$ allagents --agent-help "skills list"
Unknown command: skills list
$ allagents --json skills list # runs, but command field is misleading
{
"success": true,
"command": "plugin skills list",
"data": { "scope": "all", "skills": [] }
}
```
Expected behavior
```bash
$ allagents --agent-help | jq '.commands | map(.command)' | grep skills
"skills list"
"skills add"
"skills remove"
$ allagents --agent-help "skills list"
{
"command": "skills list",
"description": "List all skills from installed plugins",
"when_to_use": "To see available skills and their enabled/disabled status",
...
}
$ allagents --json skills list
{
"success": true,
"command": "skills list", ← matches the actual path
"data": { "scope": "all", "skills": [] }
}
```
Verification gate (must pass before closing)
```bash
set -euo pipefail
bun run build
(1) agent-help tree includes all three skills subcommands
allagents --agent-help | jq -e '.commands | map(.command) | contains(["skills list", "skills add", "skills remove"])'
(2) Per-command agent-help works for each skills subcommand
allagents --agent-help "skills list" | jq -e '.command == "skills list"'
allagents --agent-help "skills add" | jq -e '.command == "skills add"'
allagents --agent-help "skills remove" | jq -e '.command == "skills remove"'
(3) The --json envelope's "command" field matches the actual command path
allagents --json skills list | jq -e '.command == "skills list"'
(4) No meta still labeled "plugin skills *"
! grep -RIn "'plugin skills " src/cli/metadata/plugin-skills.ts
```
All four checks must pass.
Implementation notes
- `src/cli/agent-help.ts`: import `skillsListMeta`, `skillsAddMeta`, `skillsRemoveMeta` from `./metadata/plugin-skills.js` and add them to `allCommands`.
- `src/cli/metadata/plugin-skills.ts`: change every `command:` value from `'plugin skills X'` to `'skills X'`. Update any `examples:` entries that read `allagents plugin skills X` to `allagents skills X`.
- `src/cli/commands/plugin-skills.ts`: the JSON envelope uses `command: 'plugin skills list'` etc. inside the handler bodies — update those to match.
- Add a unit test that asserts every `AgentCommandMeta.command` resolves to a real command path in the cmd-ts tree. This guards against future drift between metadata and runtime registration.
Refs
- Comparison context: `gh skill` (cli/cli) has a single source of truth for command metadata because each cobra command's `Use` field is the canonical name; allagents has separate metadata that has drifted from runtime registration.
- Companion wiki page: `concepts/allagents-vs-gh-skill.md` in EntityProcess/ai-research-wiki.
Problem
Two related defects in the agent-help surface:
src/cli/agent-help.ts::allCommandsdoes not include the skills metas (`skillsListMeta`, `skillsAddMeta`, `skillsRemoveMeta`). These metas are defined in `src/cli/metadata/plugin-skills.ts` and imported by `src/cli/commands/plugin-skills.ts` for help text, but never wired into the agent-help tree. An AI agent calling `allagents --agent-help` cannot discover that `skills list / add / remove` exist.This is also visible in normal JSON output today, where the envelope's `command` field is wrong:
```json
{
"success": true,
"command": "plugin skills list", ← wrong; actual path is "skills list"
"data": { "scope": "all", "skills": [] }
}
```
Current behavior
```bash
$ allagents --agent-help | jq '.commands | map(.command)'
[
"workspace init",
"update",
"workspace status",
"plugin install",
"plugin uninstall",
"plugin marketplace list",
"plugin marketplace add",
"plugin marketplace remove",
"plugin marketplace update",
"plugin marketplace browse",
"plugin list",
"plugin validate",
"self update"
]
$ allagents --agent-help skills
Unknown command: skills
$ allagents --agent-help "skills list"
Unknown command: skills list
$ allagents --json skills list # runs, but command field is misleading
{
"success": true,
"command": "plugin skills list",
"data": { "scope": "all", "skills": [] }
}
```
Expected behavior
```bash
$ allagents --agent-help | jq '.commands | map(.command)' | grep skills
"skills list"
"skills add"
"skills remove"
$ allagents --agent-help "skills list"
{
"command": "skills list",
"description": "List all skills from installed plugins",
"when_to_use": "To see available skills and their enabled/disabled status",
...
}
$ allagents --json skills list
{
"success": true,
"command": "skills list", ← matches the actual path
"data": { "scope": "all", "skills": [] }
}
```
Verification gate (must pass before closing)
```bash
set -euo pipefail
bun run build
(1) agent-help tree includes all three skills subcommands
allagents --agent-help | jq -e '.commands | map(.command) | contains(["skills list", "skills add", "skills remove"])'
(2) Per-command agent-help works for each skills subcommand
allagents --agent-help "skills list" | jq -e '.command == "skills list"'
allagents --agent-help "skills add" | jq -e '.command == "skills add"'
allagents --agent-help "skills remove" | jq -e '.command == "skills remove"'
(3) The --json envelope's "command" field matches the actual command path
allagents --json skills list | jq -e '.command == "skills list"'
(4) No meta still labeled "plugin skills *"
! grep -RIn "'plugin skills " src/cli/metadata/plugin-skills.ts
```
All four checks must pass.
Implementation notes
Refs