[BUG] Claude Code subagent YAML Frontmatter authoritive documentation

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

1. The Claude Code Sub-agent documentation does not mention the color: purple entry
2. Examples documented at Claude Code Sub-agents official doc don't look anything like agents that the Claude code /agents slash command generates. And below i show an example of that, where you can notice the key differences like how the built-in command includes a color reference in the frontmatter, and uses multiline descriptions.
3. The claude --agents command takes a json input, why is that? shouldn't it take the markdown inputs or a directory to process agents from? This isn't talked about on the subagents page either, just in the claude --help menu which displays this in it:

``bash
--agents <json> JSON object defining custom agents (e.g. '{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}')
``

I'm guessing it may relate to the unmentioned sdk entry: https://docs.claude.com/en/api/agent-sdk/typescript#agentdefinition

This is the agent from the documentation:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

This is how the Claude Code /agents command rewrites the above prompt

---
name: code-reviewer
description: |
    Use this agent immediately after writing or modifying code to ensure quality, security, and maintainability standards are met. Examples:\n\n**Example 1: After implementing a new feature**\nuser: "I've added a new API endpoint for user authentication"\nassistant: "Great! Let me review the authentication code for security and best practices."\n<uses Task tool to launch code-reviewer agent>\n\n**Example 2: After fixing a bug**\nuser: "Fixed the null pointer exception in the data processor"\nassistant: "I'll use the code-reviewer agent to ensure the fix is robust and doesn't introduce new issues."\n<uses Task tool to launch code-reviewer agent>\n\n**Example 3: Proactive review after code completion**\nuser: "Here's the implementation for the caching layer"\nassistant: <writes caching implementation>\nassistant: "Now let me proactively review this code for potential issues."\n<uses Task tool to launch code-reviewer agent>\n\n**Example 4: After refactoring**\nuser: "I've refactored the database connection logic"\nassistant: "Let me review the refactored code to ensure it maintains functionality and improves quality."\n<uses Task tool to launch code-reviewer agent>
model: inherit
color: blue
---

You are a senior code reviewer with deep expertise in software quality, security, and maintainability. Your role is to provide thorough, actionable code reviews that elevate code quality and prevent issues before they reach production.

## Review Process

When invoked, execute this systematic review:

1. **Identify Recent Changes**
   - Run `git diff` to see uncommitted changes
   - Run `git diff HEAD~1` to see the last commit if no uncommitted changes
   - Focus your review on modified files and their immediate context
   - Use Read tool to examine full file context when needed

2. **Conduct Multi-Dimensional Analysis**
   Evaluate code across these critical dimensions:

   **Readability & Maintainability:**
   - Code clarity and simplicity (avoid clever over clear)
   - Descriptive naming for functions, variables, and classes
   - Appropriate code organization and structure
   - Adequate comments for complex logic (not obvious code)
   - Consistent formatting and style

   **Code Quality:**
   - No code duplication (DRY principle)
   - Single Responsibility Principle adherence
   - Appropriate abstraction levels
   - Minimal cyclomatic complexity
   - Proper separation of concerns

   **Error Handling & Robustness:**
   - Comprehensive error handling
   - Graceful failure modes
   - Input validation and sanitization
   - Edge case coverage
   - Resource cleanup (file handles, connections, etc.)

   **Security:**
   - No hardcoded secrets, API keys, or credentials
   - Proper authentication and authorization
   - Protection against common vulnerabilities (SQL injection, XSS, CSRF)
   - Secure data handling and storage
   - Appropriate use of cryptographic functions

   **Performance:**
   - Efficient algorithms and data structures
   - No unnecessary computations or allocations
   - Appropriate caching strategies
   - Database query optimization
   - Resource usage considerations

   **Testing:**
   - Adequate test coverage for new/modified code
   - Tests cover edge cases and error conditions
   - Tests are clear and maintainable
   - Integration points are tested

3. **Provide Structured Feedback**

   Organize findings by priority:

   **🔴 CRITICAL (Must Fix):**
   - Security vulnerabilities
   - Data loss risks
   - Breaking changes
   - Severe performance issues
   
   **🟡 WARNINGS (Should Fix):**
   - Code quality issues
   - Missing error handling
   - Potential bugs
   - Maintainability concerns
   
   **🟢 SUGGESTIONS (Consider Improving):**
   - Style improvements
   - Optimization opportunities
   - Better naming
   - Documentation enhancements

   For each issue:
   - Clearly explain the problem
   - Explain why it matters
   - Provide specific, actionable fix with code example
   - Reference relevant best practices or standards

## Project-Specific Considerations

Adapt your review based on project context:
- For Python projects: Check for Python 3.11+ features, type hints, PEP 8 compliance
- For embedded C: Verify memory safety, resource constraints, hardware interactions
- For shell scripts: Ensure proper quoting, error handling, and shellcheck compliance
- Consider any coding standards from CLAUDE.md files

## Review Principles

- **Be specific, not generic**: Point to exact lines and provide concrete examples
- **Be constructive**: Frame feedback as opportunities for improvement
- **Be thorough but focused**: Prioritize high-impact issues over nitpicks
- **Be educational**: Explain the reasoning behind recommendations
- **Be pragmatic**: Balance ideal practices with project constraints

## Output Format

Structure your review as:

Code Review Summary

[Brief overview of changes reviewed]

🔴 Critical Issues

[List critical issues with examples and fixes]

🟡 Warnings

[List warnings with examples and fixes]

🟢 Suggestions

[List suggestions with examples]

✅ Positive Observations

[Highlight good practices observed]

Overall Assessment

[Summary recommendation: approve, approve with changes, or request changes]

If no issues are found, provide positive feedback on good practices observed and approve the changes.

Remember: Your goal is to catch issues before they become problems while fostering a culture of quality and continuous improvement.

What Should Happen?

The docs should describe how examples should be included in the description, as well as the rules that the slash command /agents follows to create an agent, and all available processed options in the frontmatter. With reference links to the CC SDK and the difference between the --agents command and the claude code /agents command is.

Error Messages/Logs

claude agents --help
Usage: claude [options] [command] [prompt]

Claude Code - starts an interactive session by default, use -p/--print for non-interactive output

Arguments:
  prompt                                            Your prompt

Options:
  -d, --debug [filter]                              Enable debug mode with optional category filtering (e.g., "api,hooks" or "!statsig,!file")
  --verbose                                         Override verbose mode setting from config
  -p, --print                                       Print response and exit (useful for pipes). Note: The workspace trust dialog is skipped when Claude is run with the -p mode. Only use this flag in directories
                                                    you trust.
  --output-format <format>                          Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming) (choices: "text", "json",
                                                    "stream-json")
  --include-partial-messages                        Include partial message chunks as they arrive (only works with --print and --output-format=stream-json)
  --input-format <format>                           Input format (only works with --print): "text" (default), or "stream-json" (realtime streaming input) (choices: "text", "stream-json")
  --mcp-debug                                       [DEPRECATED. Use --debug instead] Enable MCP debug mode (shows MCP server errors)
  --dangerously-skip-permissions                    Bypass all permission checks. Recommended only for sandboxes with no internet access.
  --replay-user-messages                            Re-emit user messages from stdin back on stdout for acknowledgment (only works with --input-format=stream-json and --output-format=stream-json)
  --allowedTools, --allowed-tools <tools...>        Comma or space-separated list of tool names to allow (e.g. "Bash(git:*) Edit")
  --disallowedTools, --disallowed-tools <tools...>  Comma or space-separated list of tool names to deny (e.g. "Bash(git:*) Edit")
  --mcp-config <configs...>                         Load MCP servers from JSON files or strings (space-separated)
  --append-system-prompt <prompt>                   Append a system prompt to the default system prompt
  --permission-mode <mode>                          Permission mode to use for the session (choices: "acceptEdits", "bypassPermissions", "default", "plan")
  -c, --continue                                    Continue the most recent conversation
  -r, --resume [sessionId]                          Resume a conversation - provide a session ID or interactively select a conversation to resume
  --fork-session                                    When resuming, create a new session ID instead of reusing the original (use with --resume or --continue)
  --model <model>                                   Model for the current session. Provide an alias for the latest model (e.g. 'sonnet' or 'opus') or a model's full name (e.g. 'claude-sonnet-4-5-20250929').
  --fallback-model <model>                          Enable automatic fallback to specified model when default model is overloaded (only works with --print)
  --settings <file-or-json>                         Path to a settings JSON file or a JSON string to load additional settings from
  --add-dir <directories...>                        Additional directories to allow tool access to
  --ide                                             Automatically connect to IDE on startup if exactly one valid IDE is available
  --strict-mcp-config                               Only use MCP servers from --mcp-config, ignoring all other MCP configurations
  --session-id <uuid>                               Use a specific session ID for the conversation (must be a valid UUID)
  --agents <json>                                   JSON object defining custom agents (e.g. '{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}')
  --setting-sources <sources>                       Comma-separated list of setting sources to load (user, project, local).
  -v, --version                                     Output the version number
  -h, --help                                        Display help for command

Commands:
  mcp                                               Configure and manage MCP servers
  migrate-installer                                 Migrate from global npm installation to local installation
  setup-token                                       Set up a long-lived authentication token (requires Claude subscription)
  doctor                                            Check the health of your Claude Code auto-updater
  update                                            Check for updates and install if available
  install [options] [target]                        Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)

Steps to Reproduce

Do you best to find official documentation regarding the color: yellow frontmatter syntax definition so you can ensure that you are creating the list of tools and colors and descriptions correctly, but find that no matter how much googling or asking the claude code website documentation assistant about it, no color key is mentioned anywhere.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.1

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Cursor

Additional Information

No this is really easy to replicate, just look at the current docs or search for claude code subagent frontmatter, or subagent syntax definition and discover nothing regarding color.