Bug: Generated agents invisible at project level due to <example> blocks in YAML description

[Cpicon]

Summary

Agents generated by /agent-team-creator:generate-agent-team and /generate-debugger are silently rejected by Claude Code's project-level YAML parser when saved to .claude/agents/. They never appear in claude agents or /agents. No error is shown.

Root Cause

The generated agents use bare multi-line YAML descriptions containing <example> blocks:

---
name: my-agent
description: Use this agent when... Examples:

  <example>
  Context: Something.
  user: "Do something"
  assistant: "I'll do it."
  <commentary>
  This triggers because...
  </commentary>
  </example>

model: inherit
color: blue
---

The < character in <example> is a YAML flow indicator. The project-level parser (.claude/agents/) is stricter than the user-level parser (~/.claude/agents/) and silently rejects the entire file.

Evidence

Created test agents in .claude/agents/ to isolate the parsing:

Format	Discovered?
description: Simple single-line text.	Yes
description: > (folded scalar, multi-line)	Yes
description: | (literal scalar, multi-line)	Yes
description: Text...\n\n <example>... (bare multi-line)	No

The same bare multi-line format works at the user level (~/.claude/agents/), which is why this wasn't caught during development.

Steps to Reproduce

1. Run /agent-team-creator:generate-agent-team in any project
2. Agents are saved to .claude/agents/
3. Run claude agents — no "Project agents" section appears
4. No error is shown

Fix

Change the agent generation templates to use YAML literal block scalar (|) for the description:

# BEFORE (broken at project level)
description: Use this agent when... Examples:

  <example>
  ...
  </example>

# AFTER (works everywhere)
description: |
  Use this agent when working on the CI/CD pipeline, including
  build.py, verify.py, run.py, or the pipeline scheduling logic.

The tradeoff is losing <example> blocks in the description field, which reduces auto-triggering accuracy. However, project-scoped agents are primarily dispatched by an orchestrator (which knows when to call them), so this is acceptable.

Affected Files

• Agent generation templates/prompts that produce frontmatter with <example> blocks in the description field
• skills/agent-generation/ — the skill that generates agent content
• agents/team-architect.md — the agent that analyzes codebases and generates agents

Impact

Every agent generated by the plugin that uses <example> blocks is invisible at the project level. Users get zero working agents with no error indication.

Environment: Claude Code v2.1.79, macOS
Related: Split from #8