1

lessons/patterns/plugin-load-failure---check-command-frontmatter-first

Leo Miranda edited this page 2026-02-03 04:13:08 +00:00

Table of Contents

• Context
• Problem
• Root Cause
• Solution
• Files Fixed This Session
• Prevention
• Key Lesson

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:

---
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:

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