agentsop-output-format-by-model

Output-Format-by-Model — 让格式服务于任务，而不是反过来

One-liner: Different output formats carry different cognitive load for the model. Code-in-JSON is the canonical proof: the same model writes worse code when wrapped in a JSON tool-call than when emitted as plain text + diff. The reverse failure (asking for prose when you need a typed object) is just as common. Pick format per (task × consumer), not by reflex.

---

1. 何时激活 (When to activate)

Activate this skill before committing to an output schema in any of these situations:

Trigger	Signal
Designing a coder-agent	"should the model return a apply_patch tool call or plain-text diff?"
Adding a tool to an existing agent	"tool input has a code / query / sql / regex field — should I nest it in JSON or leave it as a string?"
Building extraction / classification	"should I use dspy.Predict typed fields, Pydantic + response_format=json_schema, or just markdown?"
Wiring an evaluator	"the metric needs a number — but the model also has to reason to produce it"
Migrating a working prompt to "structured outputs"	someone said "let's make it safer with JSON schema"
Tool-call harness adds latency / errors	repeated json.JSONDecodeError, escaping bugs, truncated outputs

Anti-triggers (skip this skill):

• The format is fixed by an external API (e.g. you must return OpenAI function-call JSON — no choice).
• One-shot exploratory prompting where no consumer parses the output yet.
• The task is itself about JSON (e.g. "fix this malformed JSON") — see §6.

---

2. 核心心智模型 (Core mental model)

2.1 Three-layer claim

            ┌──────────────────────────────────────────────────┐
            │ FORMAT FOLLOWS FUNCTION                          │
            │                                                  │
            │  Some formats add cognitive load to the model    │
            │  and measurably degrade quality on the           │
            │  *content* the format is supposed to wrap.       │
            └──────────────────────────────────────────────────┘
                         ▲                          ▲
                         │                          │
         What's being consumed?       Who consumes it?
         (code? prose? entities?      (human reader? parser?
          number? action selection?)   downstream LM? compiler?)
                         │                          │
                         └──────────┬───────────────┘
                                    ▼
                       FORMAT SELECTION
                  (text+diff | markdown | JSON | tool_use
                   | grammar-constrained | typed field)