From ee937399315bcb305b34f83a0d37ea477485afbb Mon Sep 17 00:00:00 2001
From: Leo Miranda <leobmiranda@gmail.com>
Date: Tue, 3 Feb 2026 04:28:09 +0000
Subject: [PATCH] Add
 "lessons/patterns/plugin-load-errors---missing-name-field-in-command-frontmatter"

---
 ...ing-name-field-in-command-frontmatter.-.md | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 lessons%2Fpatterns%2Fplugin-load-errors---missing-name-field-in-command-frontmatter.-.md

diff --git a/lessons%2Fpatterns%2Fplugin-load-errors---missing-name-field-in-command-frontmatter.-.md b/lessons%2Fpatterns%2Fplugin-load-errors---missing-name-field-in-command-frontmatter.-.md
new file mode 100644
index 0000000..463bf8a
--- /dev/null
+++ b/lessons%2Fpatterns%2Fplugin-load-errors---missing-name-field-in-command-frontmatter.-.md
@@ -0,0 +1,69 @@
+## Context
+
+Plugin load failures showing only "1 error" with no details about what's wrong.
+
+## Problem
+
+Claude Code's plugin loader doesn't surface specific validation errors. When a plugin fails to load, you see:
+
+```
+viz-platform Plugin · leo-claude-mktplace · ✘ failed to load · 1 error
+```
+
+No indication of WHAT the error is.
+
+## Root Cause
+
+15 command markdown files were missing the required `name:` field in YAML frontmatter:
+
+```yaml
+# WRONG - causes silent load failure
+---
+description: Some description
+---
+
+# CORRECT
+---
+name: command-name
+description: Some description
+---
+```
+
+## Debugging Steps Taken (wasteful)
+
+1. Checked MCP server venvs - OK
+2. Checked symlinks - OK
+3. Checked plugin.json files - OK
+4. Checked hooks.json - OK
+5. Checked run.sh scripts - OK
+6. Finally checked command frontmatter - FOUND IT
+
+## Solution
+
+Add `name:` field to all command files:
+
+```bash
+# Check for missing name fields
+for f in plugins/*/commands/*.md; do
+  grep -q '^name:' "$f" || echo "MISSING: $f"
+done
+```
+
+## Prevention
+
+1. **Validate before commit**: Add pre-commit hook to check all command files have `name:` field
+2. **Template enforcement**: Command file template must include `name:` as first field
+3. **File issue**: Claude Code should show actual validation errors, not just "1 error"
+
+## Time Wasted
+
+Significant token burn debugging every layer when error message should have said:
+"commands/chart.md: missing required 'name' field"
+
+## Filed Issue
+
+GitHub issue template saved to `.scratch/github-issue-plugin-errors.md` for submission to anthropics/claude-code
+
+
+---
+**Tags:** plugins, debugging, frontmatter, claude-code, error-handling
\ No newline at end of file