[DOCS]: Agents field as string in plugin manifest causes installation failure

[Konadu-Akwasi-Akuoko]

Summary

The public plugin docs show agents as a string value in the example manifest schema, but using a string causes plugin installation to fail. Only an array of strings works.

Problem

The Plugin Manifest Schema docs show the following example:

{
  "agents": "./custom/agents/"
}

However, using a string for the agents field causes plugin installation to silently fail. The plugin does not load correctly and no clear error is surfaced to the user.

The only format that works is an array of strings:

{
  "agents": ["./agents/broll-manager.md"]
}

The internal manifest reference (plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md) specifies agents as String or Array of strings with default ["./agents"], but the string variant does not appear to work in practice.

Steps to Reproduce

1. Create a plugin with plugin.json containing "agents": "./agents/"

2. Add the plugin to the marketplace and install it from the marketplace

3. Plugin installation fails -- agents are not loaded and no clear error is surfaced

4. Change to "agents": ["./agents/my-agent.md"]

5. Re-publish and reinstall from the marketplace

6. Agents now load correctly

Expected Behavior

Either:

• The string format ("agents": "./agents/") should work as documented, OR
• The docs should be updated to show only the array-of-strings format that actually works

Related Issues

• [Bug] Plugin TUI validation rejects agents array while CLI install succeeds #13927 -- agents array of objects causes Zod validation error in TUI
• Issue: Silent skill loading failure in plugins, Feature Request: Plugin Manifest Validation with Error Disclosure #20409 -- Silent skill loading failure with unknown/malformed fields
• Plugin installation fails: Invalid manifest file - agents field validation error affaan-m/everything-claude-code#90 -- Community report on manifest schema confusion
• Create PLUGIN_SCHEMA_NOTES.md affaan-m/everything-claude-code#93 -- Community report on skill loading issues

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Plugin agents and skills not discovered - only MCP servers load from plugins #17524
2. [BUG] Inline mcpServers in plugin.json ignored - field dropped during manifest parsing #16143
3. [Bug] Plugin TUI validation rejects agents array while CLI install succeeds #13927

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.