[Bug] Agent frontmatter parsing fails with verbose descriptions containing XML tags

Resolved 💬 3 comments Opened Dec 3, 2025 by svenschroeder Closed Dec 7, 2025

Bug Description
I created an agent with the wizard. It created a markdown document with the frontmatter below. Claude didn't pick up this agent to do documentation although I had prompts like 'Add this topic to the documenation' or 'Document this in the iac folder'. After asking Claude in the browser for help, it stated that my frontmatter is way too verbose and even contains xml-tags and examples.

I would expect, that the generated frontmatter would work and be reason for Claude to pick it up on documentation tasks.

For the time being I will work with commands instead.

---
name: infra-docs
description: Use this agent when you need to create, update, or improve documentation related to infrastructure, deployment pipelines, Docker configurations, CI/CD workflows, or Cloud66/Hetzner setup. This agent excels at documenting complex deployment architectures, writing clear runbooks, and creating infrastructure guides that bridge the gap between development and operations.\n\nExamples:\n\n<example>\nContext: User has just created a new deployment script and needs documentation.\nuser: "I just added a new deployment script at scripts/deploy-production.sh"\nassistant: "Let me review the script and then use the infra-docs-writer agent to create proper documentation for it."\n<commentary>\nSince the user has created deployment-related code, use the infra-docs-writer agent to document it properly.\n</commentary>\n</example>\n\n<example>\nContext: User wants to document the Cloud66 deployment process.\nuser: "We need to document how our Cloud66 deployment works for new team members"\nassistant: "I'll use the infra-docs-writer agent to create comprehensive deployment documentation."\n<commentary>\nDeployment and infrastructure documentation is the core use case for this agent.\n</commentary>\n</example>\n\n<example>\nContext: User has modified Docker configuration.\nuser: "I updated the Dockerfile to use multi-stage builds"\nassistant: "Good improvement. Let me use the inra-docs-writer agent to update the Docker documentation to reflect these changes."\n<commentary>\nProactively document infrastructure changes to keep docs in sync with code.\n</commentary>\n</example>
tools: Edit, Write, NotebookEdit, Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput
model: inherit
color: purple
---

Environment Info

  • Platform: linux
  • Terminal: vscode
  • Version: 2.0.57
  • Feedback ID: baaf1430-52e4-447a-b247-ef38ecf0749d

Errors
Claude Code didn't use the agent for documentation purposes.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗