plugin.json manifest fails schema validation — plugin cannot be installed

[travisrecupero]

plugin.json manifest fails schema validation — plugin cannot be installed

Problem

custom-plugin-flutter cannot be installed via Claude Code. The installer rejects the manifest with:

Plugin has an invalid manifest file at .../.claude-plugin/plugin.json.
Validation errors: author: Invalid input: expected object, received string,
commands: Invalid input, agents: Invalid input, skills: Invalid input

After working around that, a second error occurs:

Hook load failed: "Invalid input: expected record, received array"

Analysis

I verified these against the Claude Code plugin schema (Zod validation in the v2.1.77 binary) and the official plugin reference docs. These are not regressions — the current manifest has never matched the schema.

Issue 1: author is a string, schema requires an object

Current (plugin.json line 7):

"author": "Custom Plugin Development Team",

Required format (per schema and docs):

"author": {
  "name": "Custom Plugin Development Team"
},

The Zod schema defines author as S.object({ name: S.string().min(1), email: S.string().optional(), url: S.string().optional() }). There is no union with S.string() — a bare string has never been valid. The official superpowers plugin uses the object format across all versions.

Issue 2: agents, commands, skills arrays use wrong format

These fields are valid in plugin.json, but only as path overrides (a string or array of strings pointing to directories/files). They are not meant to hold arrays of metadata objects.

Current (invalid):

"agents": [
  { "name": "...", "displayName": "...", "description": "...", "path": "..." },
  ...
]

Valid usage would be:

"agents": "./agents"

Recommended fix: Remove agents, commands, and skills from plugin.json entirely. Claude Code auto-discovers these from the agents/, commands/, and skills/ directories when the fields are omitted — which is the standard approach used by official plugins.

Issue 3: hooks/hooks.json uses an array, schema requires a record

Current (invalid):

{
  "hooks": [
    { "event": "user-prompt-submit", "action": "track", ... },
    ...
  ]
}

Required format:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "...",
        "hooks": [
          { "type": "command", "command": "...", "async": false }
        ]
      }
    ]
  }
}

The current hook entries (track, log actions) don't correspond to valid Claude Code hook types. Either implement valid hooks per the schema or use an empty object:

{
  "hooks": {}
}

Suggested Fix

Minimal diff to make the plugin installable:

1. .claude-plugin/plugin.json — change author to an object, remove agents/commands/skills/metadata arrays
2. hooks/hooks.json — replace hooks array with empty object (or valid hook definitions)

Workaround

Users can manually patch the cached files after a failed install attempt, then add the plugin entry to ~/.claude/plugins/installed_plugins.json. However, any plugin update will re-fetch the broken manifest from this repo.

Environment

• Claude Code v2.1.77
• Plugin version: 1.0.0 (manifest internally says 2.0.0)