fix: remove unsupported agents field from plugin.json

[gaurav0107]

Hey! Ran into this while trying to install the plugin — claude plugin install fails with:

Validation errors: agents: Invalid input

Turns out the "agents" array in .claude-plugin/plugin.json isn't recognized by Claude Code's plugin validator at all. Same thing that happened with the hooks field a while back (already documented in PLUGIN_SCHEMA_NOTES.md).

What I changed

• Removed the agents array (38 entries) from plugin.json — this is the actual fix
• Removed the agents property from schemas/plugin.schema.json so the local schema stays in sync
• Updated PLUGIN_SCHEMA_NOTES.md — added a "DO NOT ADD" section for agents, same pattern as the existing hooks warning
• Updated README.md — the old text said "agents must use explicit file paths" which is now wrong
• Updated tests — swapped the 3 old agents-validation tests for one regression test that ensures agents doesn't come back

The actual agent .md files in agents/ are untouched — they're auto-discovered by convention, same as hooks. This only removes the manifest declaration that was breaking installs.

Testing

node tests/plugin-manifest.test.js → 51 passed, 0 failed

The new test mirrors the existing hooks pattern:

'claude plugin.json does NOT have agents field (unsupported by Claude Code validator)'

Closes #1459

---

Summary by cubic

Remove the unsupported agents field from .claude-plugin/plugin.json to stop plugin install failures ("agents: Invalid input"). Align the schema, docs, and tests, and document that agents are auto-discovered by convention.

• Bug Fixes
  • Removed agents from .claude-plugin/plugin.json and schemas/plugin.schema.json.
  • Updated .claude-plugin/PLUGIN_SCHEMA_NOTES.md and .claude-plugin/README.md to state agents is not a supported manifest field and is auto-loaded (like hooks).
  • Replaced agent-related tests with a single regression test asserting the field is absent.

^{Written for commit 53a599f. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation

  • Clarified manifest guidance: the agents field is unsupported and must not be included; examples, anti-patterns, and contributor guidance updated with an explicit critical warning.

• Chores

  • Removed explicit agent registration from manifests—agents and hooks are auto-loaded by convention.

• Tests

  • Updated manifest tests to assert that agents must not be declared.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b553cf5c-83f8-4016-8477-08bbf17564c4

📥 Commits

Reviewing files that changed from the base of the PR and between 7156985 and 53a599f.

📒 Files selected for processing (5)

• .claude-plugin/PLUGIN_SCHEMA_NOTES.md
• .claude-plugin/README.md
• .claude-plugin/plugin.json
• schemas/plugin.schema.json
• tests/plugin-manifest.test.js

💤 Files with no reviewable changes (2)

• schemas/plugin.schema.json
• .claude-plugin/plugin.json

✅ Files skipped from review due to trivial changes (2)

• tests/plugin-manifest.test.js
• .claude-plugin/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• .claude-plugin/PLUGIN_SCHEMA_NOTES.md

---

📝 Walkthrough

Walkthrough

The PR removes the top-level agents field from the plugin manifest, schema, and tests, and updates documentation to state that agents (and hooks) must not be declared in plugin.json because the validator rejects them with agents: Invalid input. Agent discovery is convention-based.

Changes

Cohort / File(s)	Summary
Documentation .claude-plugin/PLUGIN_SCHEMA_NOTES.md, .claude-plugin/README.md	Removed examples showing an agents field; added explicit warning that plugin.json must not include "agents" (or "hooks") as the validator rejects them; updated contributor guidance and history note.
Manifest .claude-plugin/plugin.json	Removed the exported agents array (previously listed ~40 ./agents/*.md entries).
Schema schemas/plugin.schema.json	Removed top-level agents property from the JSON Schema (was type: "array" of strings).
Tests tests/plugin-manifest.test.js	Replaced tests that required agents to be an array of file paths with a single assertion that manifest must not declare an agents property.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• feat(codex): add Codex native plugin manifest and fix Claude plugin.json #960 — Modifies the same plugin manifest and validation/tests around agents (direct code-level relation/conflict).
• Create PLUGIN_SCHEMA_NOTES.md #93 — Prior edits to PLUGIN_SCHEMA_NOTES and schema about agents; this PR updates/reverts that guidance.
• fix: use array format for plugin manifest fields #92 — Changes handling/shape of the agents field in the manifest/schema; directly related.

Poem

🐰
I hopped through schema, docs, and file,
Took care to tidy every mile.
No agents listed, conventions steer,
A lighter manifest — hoppity cheer!
✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: removing the unsupported agents field from plugin.json to fix the validation error reported in issue #1459.
Linked Issues check	✅ Passed	The PR fully addresses issue #1459 by removing the agents field causing validation failures, updating documentation and schema accordingly, and adding regression tests to prevent reintroduction.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the agents field validation error: removing from manifest/schema, updating documentation, and adding tests. No unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR fixes a plugin install failure by removing the unsupported agents field from .claude-plugin/plugin.json, syncing the local JSON schema, updating documentation, and replacing the now-stale agent path tests with a regression test that prevents the field from being re-introduced. The change is minimal, well-scoped, and mirrors the existing pattern already established for the hooks field.

Confidence Score: 5/5

Safe to merge — removes a field that was actively breaking installs, with no functional regressions.

All changes are targeted removals of an unsupported field. The local schema already had additionalProperties: false, so removing agents from properties automatically guards against it being re-added. The new regression test correctly uses 'agents' in claudePlugin and mirrors the established hooks pattern. No P0/P1 issues found.

No files require special attention.

Important Files Changed

Filename	Overview
.claude-plugin/plugin.json	Removes the 38-entry agents array that caused claude plugin install to fail with "agents: Invalid input".
schemas/plugin.schema.json	Removes the top-level agents array property; with additionalProperties: false already set, the local schema now mirrors the Claude Code validator and will reject any future re-introduction of the field.
tests/plugin-manifest.test.js	Replaces three agent path-validation tests with a single regression test asserting agents is absent from the manifest, matching the existing hooks pattern.
.claude-plugin/PLUGIN_SCHEMA_NOTES.md	Rewrites the agents section from "how to declare agents correctly" to "DO NOT ADD agents — it is auto-discovered and the field is unsupported by Claude Code's validator".
.claude-plugin/README.md	One-line update correcting the gotcha note: agents must not be included rather than "must use explicit file paths".

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[claude plugin install] --> B{Validate plugin.json}
    B -->|Before PR: agents field present| C["❌ agents: Invalid input\n(Claude Code validator rejects field)"]
    B -->|After PR: agents field absent| D["✅ Validation passes"]
    D --> E[Plugin installs successfully]
    F["agents/*.md files"] -->|Auto-discovered by convention| E
    G["schemas/plugin.schema.json\nadditionalProperties: false"] -->|Rejects agents if re-added| B

Loading

_{Reviews (2): Last reviewed commit: "docs: update README to reflect agents fi..." | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".claude-plugin/PLUGIN_SCHEMA_NOTES.md">

<violation number="1" location=".claude-plugin/PLUGIN_SCHEMA_NOTES.md:162">
P2: The new docs overgeneralize hooks behavior: they claim any explicit `hooks` field causes errors, conflicting with the documented exception that additional hook files may be declared.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}