Allium plugin registers 0 agents in Claude Code: the "agents" key in plugin.json suppresses discovery

[mfehlhaber]

First, thank you for Allium. Your work here is very much appreciated.

Summary

Installing allium from the marketplace registers the seven skills, the two
hooks, and the LSP server, but none of the five agents. The agent files ship
correctly and are well-formed; the explicit "agents" array in
.claude-plugin/plugin.json appears to suppress their discovery. Removing that
key makes all five register.

The install reports success and nothing warns, so the agents go missing
silently. Unlike #24, there is no /doctor error to follow.

Reproduction

/plugin marketplace add juxt/claude-plugins
/plugin install allium

claude plugin details allium@juxt-plugins

Observed:

Component inventory
  Skills (7)  allium, distill, elicit, propagate, tend, weed, witness
  Agents (0)
  Hooks (2)  PreToolUse, PostToolUse  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (1)  allium  (out-of-process tooling; no model context cost)

Expected: Agents (5) distill, propagate, tend, weed, witness

What we narrowed it down to

Removing the "agents" key from the installed manifest:

~/.claude/plugins/cache/juxt-plugins/allium/3.15.0/.claude-plugin/plugin.json

immediately changes the inventory to:

  Agents (5)  weed, witness, tend, propagate, distill

Nothing else was touched — the five agents/*.md files are unchanged, and
convention-based discovery of agents/ finds them fine on its own.

Two things we ruled out along the way:

• Agent frontmatter. We first suspected the YAML-sequence form of tools:
  in agents/weed.md, since the Claude Code docs show a comma-separated string.
  Rewriting it as tools: Read, Glob, Grep, Edit, Write, Bash changed nothing —
  still Agents (0). We restored the file.
• Directory layout. agents/ at the plugin root is correct. As a control,
  codex@openai-codex uses the same layout, declares no component keys at
  all in its plugin.json, and registers its agent normally (Agents (1)).

So the difference between the two plugins is the presence of the explicit
declaration, not the file location or contents.

Possible fix

Dropping "agents" from plugin.json and letting convention handle it seems to
be all that's needed. We haven't checked whether the key is simply unsupported
in the current manifest schema or whether it's being parsed and then discarded —
you'll have a much better sense of which.

It may be worthwhile to look at "skills" too: those do register today, so the two keys are
evidently treated differently, and it might be worth confirming which component
keys the schema actually honours. #24 and #39 suggest this manifest has been
accreting keys over time.

Environment

Claude Code	2.1.247
Plugin	allium@juxt-plugins 3.15.0 (scripts/allium-ref.txt = v3.15.0)
allium CLI	3.5.3 (language versions: 1, 2, 3)
OS	Linux (WSL2)
Install scope	user

Workaround for anyone else hitting this

Delete the "agents" key from the installed plugin.json at the path above.
Note that any plugin update restores the vendored copy and the agents disappear
again, so it isn't a durable fix.

Happy to test a patch or supply any further detail — and thanks again for the
pinned-vendoring setup in juxt/claude-plugins; sync-allium.sh plus the drift
check made it straightforward to work out exactly what we had installed.

[mfehlhaber]

Re-tested on Claude Code 2.1.250 (2.1.247 when I filed this). The original
reproduction still holds, but I want to correct one guess I made above.

I had wondered whether "agents" was simply unsupported by the manifest schema.
It isn't — it's recognised and strictly validated. Each of these fails the
manifest outright with agents: Invalid input:

"agents": ["./agents"]                     // directory
"agents": ["agents/distill.md"]            // no ./ prefix
"agents": ["/abs/path/agents/distill.md"]  // absolute

Only the ./-relative .md form you already use passes validation. But the
contents are then ignored:

agents value	Result
five ./agents/*.md entries (as shipped)	Agents (0)
one ./agents/distill.md entry	Agents (0)
[]	Agents (0)
key absent	Agents (5)

A single valid entry and an empty array are indistinguishable, so the values
are never read — it's the key's presence that disables convention discovery.

That points the root cause at the Claude Code plugin loader rather than at this
manifest: you're using a recognised key in the only shape it will accept, and
the host validates it and then discards it. Dropping "agents" still works as a
workaround and I'd still suggest it, but it may be worth raising upstream too,
since any plugin that declares agents explicitly will hit the same thing.

Apologies for the sharper framing in my original report — the manifest isn't at
fault.