From 15b891d7ba2dc81a304818ff0eae11ffcf2f660f Mon Sep 17 00:00:00 2001
From: Leo Miranda <leobmiranda@gmail.com>
Date: Tue, 3 Feb 2026 04:13:08 +0000
Subject: [PATCH] Add
 "lessons/patterns/plugin-load-failure---check-command-frontmatter-first"

---
 ...ure---check-command-frontmatter-first.-.md | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 lessons%2Fpatterns%2Fplugin-load-failure---check-command-frontmatter-first.-.md

diff --git a/lessons%2Fpatterns%2Fplugin-load-failure---check-command-frontmatter-first.-.md b/lessons%2Fpatterns%2Fplugin-load-failure---check-command-frontmatter-first.-.md
new file mode 100644
index 0000000..ef8c5d1
--- /dev/null
+++ b/lessons%2Fpatterns%2Fplugin-load-failure---check-command-frontmatter-first.-.md
@@ -0,0 +1,59 @@
+## Context
+
+When Claude Code plugins show "failed to load · 1 error" in `/plugin` output, multiple plugins may fail simultaneously.
+
+## Problem
+
+Wasted significant debugging time checking:
+- MCP server venvs
+- run.sh scripts
+- hooks.json configuration
+- plugin.json structure
+- Agent files
+
+When the actual issue was **missing YAML frontmatter** on command markdown files.
+
+## Root Cause
+
+Command files in `plugins/{name}/commands/*.md` MUST start with YAML frontmatter:
+
+```yaml
+---
+name: command-name
+description: What the command does
+agent: agent-name  # optional
+---
+```
+
+Files that start directly with `# Title` instead of `---` will cause the plugin to fail to load.
+
+## Solution
+
+**FIRST CHECK when any plugin fails to load:**
+
+```bash
+for f in ~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/{plugin}/commands/*.md; do 
+  first=$(head -1 "$f")
+  if [[ "$first" != "---" ]]; then 
+    echo "MISSING FRONTMATTER: $(basename $f)"
+  fi
+done
+```
+
+## Files Fixed This Session
+
+- pr-review: pr-review.md, pr-diff.md, pr-findings.md, pr-summary.md
+- data-platform: ALL 10 command files (data-quality.md, dbt-test.md, explain.md, ingest.md, initial-setup.md, lineage.md, lineage-viz.md, profile.md, run.md, schema.md)
+
+## Prevention
+
+1. **When creating new commands**: Always start with frontmatter template
+2. **Validation script**: Add frontmatter check to `validate-marketplace.sh`
+3. **PR review**: Check command files have frontmatter before merge
+
+## Key Lesson
+
+**Plugin load errors = check command frontmatter BEFORE anything else.** Don't waste time on venvs, MCP servers, or hooks until frontmatter is verified.
+
+---
+**Tags:** plugin-debugging, frontmatter, command-files, validation, time-waster
\ No newline at end of file