agentsop-output-format-by-model

What it does

The skill instructs an agent to select an appropriate output format for LM responses based on the task, the consumer, and the model. It argues that different formats impose different cognitive load and provides concrete guidance on when to prefer plain text with diffs, JSON schemas, Pydantic or typed fields, tool_use envelopes, or markdown prose. It includes model-specific recommendations and a decision workflow that maps content type, consumer constraints, and target model to a preferred format. It also enumerates ten concrete operation scenarios where specific formats are recommended, plus worked examples showing how to handle composite tasks (e.g., extraction plus rewriting) with multi-pass or multi-zone strategies. The emphasis is on matching format to content and downstream needs to preserve quality and reliability, rather than forcing a single format across all tasks.

How it works

• Activate before committing to an output schema in coder-agent design, tool integration, extraction/classification, evaluation wiring, or migrating to structured outputs.
• Use a three-step decision workflow: Step 1 assess what's being consumed (content type) to pick a default format; Step 2 assess who consumes the output (human, parser, downstream LM, compiler, tool dispatcher, diff applier) to adjust formatting; Step 3 assess which model is targeted to select a model-specific best code-edit format (e.g., udiff, diff, json tool_use, whole-file rewrite).
• Provide concrete pairings of tasks to formats (e.g., edit code → plain-text diff in markdown; extract fields → JSON / Pydantic; answer math problems → markdown reasoning with a final line; tool calls → JSON tool_use with scalar args).
• Include dilemma cases showing how to handle mixed contents, two-pass solutions, and how to avoid nesting large blocks inside JSON when code-like payloads are involved.

When to use it

Use this skill when designing or debugging an LM's output schema, choosing between plain text / diff / JSON / tool-call / grammar-constrained output, or when a model’s quality drops after wrapping its output in a structured format. It is activated before committing to an output schema in coder-agent design, tool integration, extraction/classification, evaluator wiring, or structured-output migrations.

What it can touch

• It references formats and tool names such as plain text, diff formats (udiff, SEARCH/REPLACE diff, unified diff), JSON tool_use, Pydantic / typed OutputField, markdown, and a variety of tool interfaces (e.g., code editors, SQL in tool bodies).
• It prescribes a per-model edit-format default and cites model-specific recommendations (e.g., GPT-4 Turbo prefers udiff or diff; Claude Sonnet prefers diff; Gemini uses diff-fenced).

Caveats

• It relies on empirical anchors from cited sources (e.g., models’ sensitivity to JSON-wrapped code, and Let Me Speak Freely? findings); outcomes depend on model behavior and downstream parsers.
• It cautions against forcing JSON schemas for content that is better served as prose or code, to avoid escaping penalties and degraded quality.