Why agent config lives in YAML
Agent definitions, skill frontmatter and MCP server configuration are almost always YAML on disk, while the same structures arrive as JSON from APIs, documentation examples and generators.
YAML wins on disk because configuration is edited by people and reviewed in diffs, where comments matter and quoting noise does not help. JSON wins on the wire because it is unambiguous.
What gets quoted, and why it matters
YAML has a long list of values that change meaning if unquoted. A version like 1.10 becomes a float and loses its trailing zero. The word no becomes false in some parsers. A string beginning with a colon or a dash breaks parsing entirely.
The converter quotes anything ambiguous rather than producing the shortest possible output. Prompt text in particular is quoted aggressively, because it commonly contains colons and quotation marks.
System prompts inside config
A long system prompt embedded in a config file is where this most often goes wrong: it contains colons, quotes and line breaks, all of which are YAML-significant. If the prompt is long, keeping it in a separate file and referencing it usually beats embedding it, for both diffs and correctness.