[FEATURE] Subagent YAML frontmatter description field has UX and design issues

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The YAML description field for subagents has several design and usability issues:

1. Poor readability with escaped newlines - When descriptions contain formatting, they use \n escapes making them hard to read and maintain
2. Undocumented multi-line syntax - YAML literal block syntax (|) works but isn't shown in docs or examples
3. Description bloat beyond intended purpose - Descriptions significantly exceed the documented 1024 char limit
4. Redundancy with system prompt - Descriptions duplicate content from the Markdown prompt instead of being concise routing hints

Current Examples

python-code-reviewer.md: 1297 characters
description: "Use this agent when...\n\n<example>\nContext: User has...\n..."

react-ui-reviewer.md: 1308 characters
Similar pattern with escaped newlines and full examples in the description field.

Expected Behavior

Descriptions should be brief routing hints (~140 chars):
description: Expert Python code reviewer for FastAPI, async patterns, and backend features. Use after implementing or refactoring Python services.

Or using multi-line syntax:
description: |
Expert Python code reviewer for FastAPI, async patterns, and backend features.
Use after implementing or refactoring Python services.

Proposed Solution

Short-term:

• Document YAML literal block syntax (|) in examples and documentation
• Clarify in docs that descriptions should be minimal routing hints, not full documentation
• Add validation warnings when descriptions exceed 1024 characters
• Update built-in agent examples to demonstrate concise descriptions

Long-term:
Consider auto-generating descriptions from the first paragraph of Markdown prompts, or eliminate the field entirely and use the prompt's opening for routing decisions.

Impact

• Makes agent definitions harder to maintain and read
• Encourages misuse of the description field as documentation
• Creates unnecessary duplication between description and system prompt
• Violates the documented 1024 character limit without warning

Alternative Solutions

Explicitly document this issue and enforce using yaml literal block in pull request acceptance

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

Subagents development

Additional Context

This is python reviewer created by Claude itself

name: python-code-reviewer
description: Use this agent when you need expert review of Python code, particularly after implementing FastAPI endpoints, async workflows, service integrations, or completing backend feature work. Examples:\n\n<example>\nContext: User has just implemented a new FastAPI endpoint with WebSocket support.\nuser: "I've created a new WebSocket endpoint for real-time event streaming."\nassistant: "Let me use the python-code-reviewer agent to provide expert feedback on your Python implementation."\n<Task tool call to python-code-reviewer agent>\n</example>\n\n<example>\nContext: User has refactored async/await patterns in a service.\nuser: "I've refactored the reasoning service to use proper async patterns."\nassistant: "I'll use the python-code-reviewer agent to analyze your refactored code for async best practices and Python patterns."\n<Task tool call to python-code-reviewer agent>\n</example>\n\n<example>\nContext: User has completed a logical chunk of backend work and the assistant should proactively suggest review.\nuser: "Here's the new agent implementation I just finished"\nassistant: "Great work on completing the agent! Let me use the python-code-reviewer agent to provide expert feedback on the implementation."\n<Task tool call to python-code-reviewer agent>\n</example>