anthropics / anthropics/claude-code
Agent frontmatter: unrecognized keys (e.g. outputStyle) are silently ignored with no warning
- Lenguaje dominante
- Python
- Estrellas
- 145k
- Forks
- 23.1k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
### Summary
Unrecognized keys in a subagent definition's YAML frontmatter (`~/.claude/agents/*.md`) are silently dropped. Nothing is printed, logged to the user, or surfaced in any diagnostic, so there is no way to tell that a key had no effect.
I hit this with `outputStyle`, which is not a supported agent frontmatter key. But the silent-ignore applies to any unsupported key or typo, which is the more general problem.
Filing here rather than `/feedback`, which is disabled by policy in my environment.
### Version
`2.1.266`, Linux.
### Reproduction
1. Create `~/.claude/agents/terse.md`:
```markdown
---
name: terse
description: Test agent.
outputStyle: some-style
---
You are a test agent.
```
2. Spawn the agent (Agent tool, or `--agent terse`).
3. Observe: the agent loads and runs fine, the key has no effect, and there is no warning at startup, on load, or in any diagnostic output. Same result for an outright typo (`ouputStyle`, `tool` instead of `tools`, etc.).
### What's happening
From inspecting the bundled CLI:
- The agent frontmatter schema accepts `name`, `description`, `model`, `tools`, `disallowedTools`, `color`, `effort`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `background`, `isolation`, `observer`, `observerMessage`, `observeSubagents`. There is no `outputStyle`.
- The runtime loader parses frontmatter with a non-strict `.parse()`, so unknown keys are stripped.
- A `.strict()` copy of the same schema does exist and is `safeParse`d. On an `unrecognized_keys` issue it only emits a deduped internal telemetry event (keyed `frontmatter_shadow:*`). It never throws, and nothing reaches the user. There is no "unknown frontmatter key" message string anywhere in the bundle.
So the strict check that would catch this already runs — its result just isn't shown to anyone outside telemetry.
### Requests
**1. Surface unrecognized agent frontmatter keys to the user.** This is the actual bug. A startup warning, `--debug` output, or a line in a diagnostic command would all work. Right now a typo in an agent file is undetectable without decompiling the CLI. The same likely applies to skill and output-style frontmatter, which use the same strict-schema table.
**2. Consider supporting `outputStyle` in agent frontmatter.** Separate feature ask, lower priority. Output styles currently apply only to the main REPL thread — the prompt-id helper reads `outputStyle` and yields `repl_main_thread:outputStyle:`, whereas subagents get `agent:custom:` and their system prompt is built by a separate path that never consults the output style. Subagents also don't inherit the session's style. Today the only ways to shape a subagent's output are restating the style prose in the agent's markdown body, or the `@internal` `appendSubagentSystemPrompt` setting gated behind `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT`. Neither is a documented per-agent equivalent of an output style. Given output styles and agent definitions are both user-authored prompt customizations, reaching for `outputStyle:` in an agent file is a natural guess — which is what made the silent ignore costly.
**3. Document the supported agent frontmatter keys.** I could not find a complete list in the docs; I got the one above out of the bundle.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Línea de trabajo
Start with the bundled CLI's agent frontmatter runtime loader and the strict schema/safeParse path described in the report. Trace how unrecognized_keys are handled and where startup, --debug, or diagnostic output is assembled; done means an unknown key produces a user-visible warning while valid keys remain unchanged, with supported keys documented.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Área
- cli, documentation
- Tipo de issue
- Error
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 48/100