Claude Code crashes on YAML parse error in command frontmatter

Summary

Claude Code crashes with an unhandled exception when a custom command file (.claude/commands/*.md) contains invalid YAML in its frontmatter. The crash occurs during startup when scanning for commands.

Steps to Reproduce

1. Create a command file: .claude/commands/test/crash.md
2. Add frontmatter with brackets containing a colon:

``yaml
---
description: Test command
argument-hint: [optional: some value]
---
``

1. Start Claude Code in that directory
2. Claude Code crashes immediately

Expected Behavior

Claude Code should:

1. Gracefully handle YAML parse errors
2. Display a warning like: "Warning: Failed to parse command file .claude/commands/test/crash.md - invalid YAML"
3. Skip the invalid command and continue loading

Actual Behavior

Unhandled exception crashes the CLI:

file:///Users/mikelane/.nvm/versions/node/v24.12.0/lib/node_modules/@anthropic-ai/claude-code/cli.js:743:8724

- cB (file:///...cli.js:743:8724)
- XB (file:///...cli.js:743:10834)
- QD (file:///...cli.js:743:12402)
...

Root Cause

The argument-hint field uses a convention of [placeholder text] to indicate optional/variable content. However, YAML interprets [...] as flow sequence (array) syntax. When the content inside isn't valid array syntax (e.g., contains colons), YAML parsing fails.

Suggested Fix

1. Wrap YAML parsing in try-catch and log warnings for invalid files
2. Consider documenting that brackets should be quoted or avoided in frontmatter
3. Optionally: auto-quote string values that look like arrays but aren't

Environment

• Claude Code version: latest (via npm @anthropic-ai/claude-code)
• Node.js: v24.12.0
• OS: macOS Darwin 25.3.0

Workaround

Remove brackets from argument-hint values or quote them:

argument-hint: "optional: some value"