1

lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements

Leo Miranda edited this page 2026-01-25 20:33:24 +00:00

Table of Contents

• Plugin Manifest Validation - Hooks and Agents Format Requirements
• Context
• Problem
• 1. External hooks file reference (INVALID)
• 2. Directory reference for agents (INVALID)
• Solution
• Hooks: Must be inline in plugin.json
• Agents: Do NOT register .md files in plugin.json
• Prevention
• Validation Checklist for New Plugins
• Reference Working Examples
• Files Changed

Plugin Manifest Validation - Hooks and Agents Format Requirements

Date: 2026-01-25 Impact: Plugin installation fails with "invalid input" errors Severity: Critical - blocks plugin usage entirely

Context

When creating the data-platform plugin (v4.0.0), the plugin.json manifest had invalid formats for hooks and agents fields, causing installation to fail with:

Error: failed to install plugin has an invalid manifest file
validation errors: hooks: invalid input, agents: invalid input

Problem

Two invalid patterns were used in plugin.json:

1. External hooks file reference (INVALID)

"hooks": "hooks/hooks.json"

This attempted to reference an external JSON file for hooks configuration.

2. Directory reference for agents (INVALID)

"agents": ["./agents/"]

This assumed agent .md files needed to be registered in the manifest.

Solution

Hooks: Must be inline in plugin.json

WRONG:

"hooks": "hooks/hooks.json"

CORRECT:

"hooks": {
  "SessionStart": [
    {
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
    }
  ]
}

Agents: Do NOT register .md files in plugin.json

Agent definition files (.md) in the agents/ directory are automatically discovered by Claude Code. They do NOT need to be listed in plugin.json.

WRONG:

"agents": ["./agents/"]

CORRECT: Simply omit the "agents" field entirely. Just have the .md files in the agents/ directory.

Prevention

Validation Checklist for New Plugins

1. Hooks format: Always inline, never reference external files
2. Agents: Don't add "agents" field - .md files auto-discovered
3. Run validation: ./scripts/validate-marketplace.sh before committing
4. Test install: Actually install the plugin before merging

Reference Working Examples

• Hooks inline: plugins/project-hygiene/.claude-plugin/plugin.json
• No agents field: plugins/projman/.claude-plugin/plugin.json (has agents/ dir but no field)

Files Changed

• plugins/data-platform/.claude-plugin/plugin.json - Fixed format
• plugins/data-platform/hooks/hooks.json - Deleted (content inlined)

---

Tags: plugin-development, manifest, validation, hooks, agents, data-platform, critical-fix