personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: lessons/patterns/command-frontmatter-missing-name-field-causes-silent-load-failure
Pages
Change V5.4.0: Multi-Model Agent Support Proposal Change V5.4.0: Multi-Model Support (Sprint 7 Implementation) Change V04.1.0: Proposal (Implementation 1) Change V04.1.0: Proposal Change-V5.2.0:-Plugin-Enhancements-(Sprint-4-Commands) Change-V5.2.0:-Plugin-Enhancements-(Sprint-5-Documentation) Change-V5.2.0:-Plugin-Enhancements-Proposal.- Change-V5.5.0:-Hook-Efficiency-Quick-Wins-(Sprint-8-Implementation) Change-V5.6.0:-Domain-Advisory-Pattern-(Sprint-9-Implementation).- Change V5.6.0: Domain Advisory Pattern Proposal Change-V5.7.0:-Data-Platform-Domain-Advisory-(Sprint-10-Implementation) RFC-Hook-Efficiency-Improvements RFC-Perf-Sentinel-Plugin Sprint-1-viz-platform-Implementation-Plan branding/header-templates branding/plugin-registry branding/progress-templates branding/visual-spec lessons/patterns/agent-model-field-not-supported-by-claude-code lessons/patterns/command-frontmatter-missing-name-field-causes-silent-load-failure lessons/patterns/hook-message-wording-affects-claude-continuation-behavior lessons/patterns/mcp-venv-symlinks-lost-on-marketplace-update---5-hour-debug-loop lessons/patterns/mcp_servers-field-in-pluginjson---another-failed-debug-theory lessons/patterns/plugin-hooks-must-be-in-separate-file-not-inline lessons/patterns/plugin-load-errors---missing-name-field-in-command-frontmatter lessons/patterns/plugin-load-failure---check-command-frontmatter-first lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements lessons/patterns/plugin-version-mismatch-causes-silent-load-failure lessons/patterns/reset-pandas-index-after-filtering-to-prevent-column-pollution lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures lessons/patterns/setup-wizard-url-format-mismatch lessons/patterns/sprint-4---new-commands-not-discoverable-until-session-restart lessons/patterns/startup-hooks-must-check-venv-cache-path-first lessons/patterns/sync-entire-plugin-directory-not-individual-files lessons/patterns/use-fixes-n-keyword-for-automatic-issue-closing-in-prs lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session lessons/sprints/sprint-1---viz-platform-plugin-implementation lessons/sprints/sprint-10---domain-advisory-pattern-replication-success lessons/sprints/sprint-2---contract-validator-plugin-implementation lessons/sprints/sprint-3---agent-runaway-detection-and-timeout-handling lessons/sprints/sprint-3---background-agent-permissions-must-be-pre-granted lessons/sprints/sprint-3---mcp-server-branch-detection-bug-runs-from-installed-dir lessons/sprints/sprint-4---plugin-commands-implementation lessons/sprints/sprint-6---visual-branding-and-documentation-maintenance lessons/sprints/sprint-8---parallel-hook-optimization-success lessons/sprints/v400-release---wiki-workflow-and-versioning-patterns lessons/sprints/versioning-workflow---use-unreleased-and-release-script lessons-learned/sprints/hook-efficiency-rfc unnamed
Clone
1
lessons/patterns/command-frontmatter-missing-name-field-causes-silent-load-failure
Leo Miranda edited this page 2026-02-03 04:02:39 +00:00
Table of Contents

Command Frontmatter Missing Name Field

Date

2026-02-03

Summary

Commands MUST have a name: field in their YAML frontmatter. Without it, the skill won't be registered and the plugin appears to silently fail to load.

What Happened

  1. During the projman refactor (commit 2e65b60), commands were rewritten
  2. The name: field was NOT added to projman commands
  3. Other plugins (git-flow, claude-config-maintainer) got the name field during their refactors
  4. projman commands only had description: and agent: fields
  5. Skills for projman never appeared in the session

Correct Command Frontmatter

---
name: sprint-plan
description: Start sprint planning with AI-guided architecture analysis
agent: planner
---

Wrong (what we had)

---
description: Start sprint planning with AI-guided architecture analysis
agent: planner
---

Why This Wasn't Caught

  1. No validation script checks for name: field in command frontmatter
  2. The plugin "loads" but commands aren't registered as skills
  3. User only notices when trying to use the command

Fix

Added name: field to all 12 projman commands matching the filename (without .md extension).

Prevention

Add validation to validate-marketplace.sh to check that all command files have name: field in frontmatter.

Tags: command, frontmatter, name-field, plugin-loading, stupid-mistakes