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

lessons%2Fpatterns%2Fplugin-manifest-validation---hooks-and-agents-format-requirements.-.md

@@ -0,0 +1,85 @@
+# 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)
+```json
+"hooks": "hooks/hooks.json"
+```
+This attempted to reference an external JSON file for hooks configuration.
+
+### 2. Directory reference for agents (INVALID)
+```json
+"agents": ["./agents/"]
+```
+This assumed agent .md files needed to be registered in the manifest.
+
+## Solution
+
+### Hooks: Must be inline in plugin.json
+
+**WRONG:**
+```json
+"hooks": "hooks/hooks.json"
+```
+
+**CORRECT:**
+```json
+"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:**
+```json
+"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