Skip to content

fix: --agent-help omits the skills subcommand group and metadata.command labels say 'plugin skills' #371

@christso

Description

@christso

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:

  1. 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.
  2. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions