From 04ee20827c4be88882338bb6496e80d3347b2c29 Mon Sep 17 00:00:00 2001
From: Graceme Kamei <73515951+pangerlkr@users.noreply.github.com>
Date: Thu, 29 Jan 2026 12:34:58 +0530
Subject: [PATCH] docs: add plugin manifest validation notes

---
 .claude-plugin/README.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .claude-plugin/README.md

diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md
new file mode 100644
index 00000000..7464685e
--- /dev/null
+++ b/.claude-plugin/README.md
@@ -0,0 +1,5 @@
+### Plugin Manifest Gotchas
+
+If you plan to edit `.claude-plugin/plugin.json`, be aware that the Claude plugin validator enforces several **undocumented but strict constraints** that can cause installs to fail with vague errors (for example, `agents: Invalid input`). In particular, component fields must be arrays, `agents` must use explicit file paths rather than directories, and a `version` field is required for reliable validation and installation.
+
+These constraints are not obvious from public examples and have caused repeated installation failures in the past. They are documented in detail in `.claude-plugin/PLUGIN_SCHEMA_NOTES.md`, which should be reviewed before making any changes to the plugin manifest.