Plugin agent loading fails silently with no error feedback

Summary

Custom marketplace plugins with agents cannot be loaded under any circumstances. After exhaustive troubleshooting — matching the exact format of official plugins, validating every frontmatter field, reinstalling through the CLI, clearing caches, restarting — /agents returns nothing. No error message, no warning, no diagnostic output whatsoever. The system fails silently and completely.

This is not a user error. This is a broken feature that shipped without basic validation, error handling, or any way for users to self-diagnose.

Environment

• Platform: Linux (RHEL 9)
• Claude Code CLI (latest)
• Custom marketplace via GitHub: whatch-healtheconnections/agentic-orch

What was attempted (in order)

1. Created a custom marketplace (config-hub) pointing to a GitHub repo
2. Created a plugin (my-agents) with 11 agent .md files and 18 command .md files in the correct directory structure
3. Installed via /plugin install my-agents@config-hub
4. /agents showed nothing — no agents, no errors
5. Reviewed and fixed all agent frontmatter to use single-line description fields matching the exact format of official plugins (feature-dev, code-simplifier)
6. Fixed an empty 0-byte agent file (stale-branch-worker.md) with valid frontmatter and body
7. Verified plugin.json matches the documented schema — name, version, description, author, agents, commands fields
8. Committed and pushed all fixes to the source repo
9. Uninstalled the plugin (cleared installed_plugins.json, deleted cache)
10. Reinstalled via /plugin install my-agents@config-hub --scope local
11. Restarted Claude Code
12. /agents still shows nothing. Still no error message.

Every frontmatter block was verified to match this exact pattern from official plugins:

---
name: agent-name
description: Single line plain text description
model: sonnet
color: green
---

The plugin.json was verified to match the documented format:

{
  "name": "my-agents",
  "version": "0.1.0",
  "description": "Agents, commands, and skills",
  "author": { "name": "whatch-healtheconnections" },
  "agents": "./agents/",
  "commands": "./commands/"
}

All files are present on disk in the correct locations. The marketplace is registered. The plugin shows as installed. Nothing works.

What is broken

1. Silent failure with zero diagnostics. When plugin agent loading fails, there is no error, no warning, no log entry. The user has no way to determine what went wrong. This is the most critical issue — even if the root cause is a subtle format problem, the system gives the user absolutely nothing to work with.

1. No documentation on failure modes. The plugin docs describe the happy path. There is no troubleshooting guide, no list of common pitfalls, no explanation of what causes agent discovery to fail.

1. No validation on install. /plugin install succeeds and gives no indication that the agents it just installed will not actually load. If the plugin has structural issues, they should be caught and reported at install time — not discovered later when /agents silently returns empty.

1. /reload-plugins existence is undiscoverable. This command exists but is not surfaced anywhere in the /plugin help or general /help. Users restart Claude Code repeatedly instead of using it, because they don't know it exists.

1. The AI inside Claude Code cannot diagnose plugin issues. Claude itself has no visibility into the plugin loading system, no access to plugin logs, and no documentation on the internals. When the user asks Claude for help, Claude is reduced to guessing — which is exactly what happened here across multiple failed attempts.

Expected behavior

• /plugin install should validate the plugin structure and report errors immediately
• If individual agent files fail to parse, the error should name the file and the problem (e.g., "stale-branch-worker.md: missing required frontmatter field 'name'")
• Valid agents should still load even if one file is malformed — do not fail the entire plugin
• /agents should indicate when plugins are installed but zero agents loaded ("1 plugin installed, 0 agents loaded — run /plugin validate for details")
• A /plugin validate or /plugin doctor command should exist for diagnosing issues
• Plugin loading errors should be written to a log file that users and Claude can inspect

Impact

This feature is currently unusable for custom marketplaces. A user who invests time creating agents, setting up a marketplace repo, and installing plugins will hit a wall with no feedback and no path forward. The only recourse is filing a bug report and waiting — which is not acceptable for a feature that is publicly documented and available.