Follow-ups to #888: 58 components without frontmatter, duplicated nested paths, CONTRIBUTING template

Author: guioliveCreated Sep 12, 2026Updated Sep 12, 2026

Follow-ups from #888, which repairs every component whose frontmatter exists but doesn't parse. These three items are what's left after that PR, and none of them is a mechanical fix.

1. 58 components ship with no frontmatter block at all

npm run frontmatter:check (added in #888) reports FM_MISSING for 5 agents and 53 commands. These files open directly with a # heading, so Claude Code has no name/description to load — the component is listed in the catalog and installs, but never becomes usable.

Each one needs a name and description written by someone who knows the component, so this isn't something --fix can do.

Agents (5)
  • cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md
  • cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md
  • cli-tool/components/agents/development-team/sdd-spec-writer.md
  • cli-tool/components/agents/git/commit-guardian.md
  • cli-tool/components/agents/security/supply-chain-security.md
Commands (53)
  • cli-tool/components/commands/analysis/supply-chain-audit.md
  • cli-tool/components/commands/git-workflow/create-pr.md
  • cli-tool/components/commands/git-workflow/create-pull-request.md
  • cli-tool/components/commands/git-workflow/create-worktrees.md
  • cli-tool/components/commands/git-workflow/fix-github-issue.md
  • cli-tool/components/commands/git-workflow/pr-review.md
  • cli-tool/components/commands/git-workflow/update-branch-name.md
  • cli-tool/components/commands/orchestration/archive.md
  • cli-tool/components/commands/orchestration/commit.md
  • cli-tool/components/commands/orchestration/find.md
  • cli-tool/components/commands/orchestration/log.md
  • cli-tool/components/commands/orchestration/move.md
  • cli-tool/components/commands/orchestration/optimize.md
  • cli-tool/components/commands/orchestration/remove.md
  • cli-tool/components/commands/orchestration/report.md
  • cli-tool/components/commands/orchestration/resume.md
  • cli-tool/components/commands/orchestration/start.md
  • cli-tool/components/commands/orchestration/status.md
  • cli-tool/components/commands/orchestration/sync.md
  • cli-tool/components/commands/performance/optimize-build.md
  • cli-tool/components/commands/performance/system-behavior-simulator.md
  • cli-tool/components/commands/svelte/svelte-a11y.md
  • cli-tool/components/commands/svelte/svelte-debug.md
  • cli-tool/components/commands/svelte/svelte-migrate.md
  • cli-tool/components/commands/svelte/svelte-optimize.md
  • cli-tool/components/commands/svelte/svelte-scaffold.md
  • cli-tool/components/commands/svelte/svelte-storybook-migrate.md
  • cli-tool/components/commands/svelte/svelte-storybook-mock.md
  • cli-tool/components/commands/svelte/svelte-storybook-setup.md
  • cli-tool/components/commands/svelte/svelte-storybook-story.md
  • cli-tool/components/commands/svelte/svelte-storybook-troubleshoot.md
  • cli-tool/components/commands/svelte/svelte-storybook.md
  • cli-tool/components/commands/svelte/svelte-test-coverage.md
  • cli-tool/components/commands/svelte/svelte-test-fix.md
  • cli-tool/components/commands/svelte/svelte-test-setup.md
  • cli-tool/components/commands/svelte/svelte-test.md
  • cli-tool/components/commands/utilities/all-tools.md
  • cli-tool/components/commands/utilities/architecture-scenario-explorer.md
  • cli-tool/components/commands/utilities/check-file.md
  • cli-tool/components/commands/utilities/clean-branches.md
  • cli-tool/components/commands/utilities/clean.md
  • cli-tool/components/commands/utilities/code-permutation-tester.md
  • cli-tool/components/commands/utilities/code-to-task.md
  • cli-tool/components/commands/utilities/context-prime.md
  • cli-tool/components/commands/utilities/debug-error.md
  • cli-tool/components/commands/utilities/directory-deep-dive.md
  • cli-tool/components/commands/utilities/explain-code.md
  • cli-tool/components/commands/utilities/fix-issue.md
  • cli-tool/components/commands/utilities/generate-linear-worklog.md
  • cli-tool/components/commands/utilities/git-status.md
  • cli-tool/components/commands/utilities/initref.md
  • cli-tool/components/commands/utilities/prime.md
  • cli-tool/components/commands/utilities/refactor-code.md

2. Agent committed at duplicated nested paths

vital-health-content-agent.md exists only at these two paths (identical content), and not at cli-tool/components/agents/business-marketing/vital-health-content-agent.md where it belongs:

cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md
cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md

Because the catalog generator only scans one level of category, the agent is absent from components.json entirely. Fix: move one copy to the correct path (and give it frontmatter — it's also on the list above), delete the nested cli-tool/ directories.

There's a similar stray file inside a skill: cli-tool/components/skills/business-marketing/app-builder/templates/cli-tool/TEMPLATE.md.

3. CONTRIBUTING.md documents a format with no frontmatter

The "Adding Agents" and "Adding Commands" sections both show a file template that starts at # Agent Name / # /command-name with no YAML block. That's very likely where the 58 files above came from, so fixing the docs closes the tap:

  • Add a frontmatter block to both templates, with name + description (agents) and description + argument-hint (commands), quoting values as the sub-agents and slash-commands docs show.
  • Mention npm run frontmatter:check as the local pre-flight.
  • The "Available Categories" list (domain-experts/, creative-team/, business-team/, development-tools/) no longer matches the actual tree under cli-tool/components/agents/.

Related: #65 raised the same point about command metadata belonging in frontmatter.

I'm happy to take item 3 and the path cleanup in item 2 as a small PR if that's welcome. Item 1 is best split among whoever authored those components.

Source: davila7/claude-code-templates