structured-output-contract
Skill1 starsChanged 23 days agoMITView on GitHub
'When output feeds a program, define the schema before calling the model.
In this repository46 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- .gemini/AGENTS.mdAGENTS.md
- .cursor/rules/agent-foundry-orchestrator.mdcCursor rule
- .cursor/rules/agent-foundry-skills.mdcCursor rule
- web/llms.txtllms.txt
- anti-slopSkill
- api-designSkill
- automation-pickSkill
- bottleneck-gatingSkill
- budget-guardSkill
- cache-identitySkill
- constraint-then-solveSkill
- context-optimizationSkill
- cron-troubleshootSkill
- e2e-test-strategySkill
- engram-routingSkill
- execution-observabilitySkill
- fallback-model-routingSkill
- feedback-loopSkill
- judge-integritySkill
- knowledge-extractSkill
- landscape-firstSkill
- measure-firstSkill
- plan-before-codeSkill
- plan-then-actSkill
- prompt-disciplineSkill
- pushback-when-wrongSkill
- quality-protocolSkill
- read-before-buildSkill
- re-verify-findingsSkill
- session-closeoutSkill
- session-distillSkill
- show-your-workSkill
- verify-firstSkill
- workflow-decomposeSkill
- agent-memory-vaultSkill
- agent-team-standardsSkill
- autonomous-briefingSkill
- book-to-skillSkill
- chrome-devtools-mcp-bridgeSkill
- design-languageSkill
- funnel-pr-guardSkill
- persistent-memorySkill
- sql-migration-trioSkill
- token-compressionSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 51
No optional fields unless the consumer handles absence.
- Distinctive: line 56
Ask for exactly one JSON value.
- Distinctive: line 57
Keep the schema in the final user turn where it is closest to generation.
- Distinctive: line 101
When a response contains several sections, wrap the machine-readable block in explicit sentinels and parse only that block.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Structured Output Contract
A program will read this output. Treat the schema as the contract, not a hint.
When to Use
- The caller passes a JSON Schema or names required fields.
- Output is parsed by code, stored in a database, or passed to another tool.
- A workflow branches on a field the model must emit.
- The model answers with prose around what should be a single value.
- Tool arguments, function-call payloads, extraction tasks.
- Classification where the label set is closed.
- Reports consumed by a dashboard or evaluator.
- Any retry loop where malformed output would waste a paid call.
Procedure
1 — Define the schema first
State the exact shape before prompting:
{
"type": "object",
"required": ["decision", "reasons"],
"properties": {
"decision": {"type": "string", "enum": ["allow", "deny"]},
"reasons": {"type": "array", "items": {"type": "string"}}
}
}Rules:
requiredlists every field the consumer reads.- Closed choices use
enum, not prose instructions. - No optional fields unless the consumer handles absence.
- Numbers state integer versus number. Booleans never arrive as strings.
2 — Constrain the prompt to one value
Ask for exactly one JSON value. Forbid fences, preamble, and trailing notes. Keep the schema in the final user turn where it is closest to generation.
3 — Parse tolerantly, validate strictly
Extraction may unwrap a fenced block or surrounding prose. Validation does not soften: missing required field, wrong type, or out-of-enum value is a failure.
4 — One repair, then stop
On failure, send the invalid reply back with the exact validation errors and ask for corrected JSON. One repair. A second failure returns an error; it does not silently coerce, drop fields, or substitute a default.
5 — Surface validity separately
Return the parsed value and a validity flag. A caller must be able to tell "valid structured output" from "best-effort text" without re-parsing.
Anti-patterns
- Accepting
"true"where a boolean is required. - Filling missing fields with guesses.
- Looping repairs until the budget disappears.
- Letting markdown fences reach the parser as data.
- Declaring success when validation only warned.
References
- precedence
Verification Checklist
- Every field the consumer reads is in
required - Invalid output produces an error, not a default value
- One repair attempt is enforced
- Validity is reported to the caller
- Tests cover missing field, wrong type, and fenced JSON
Constraint Precedence
- Allow exactly one output constraint per request. Precedence: tool-call block, then JSON Schema, then regex.
- Record whether the backend enforced the constraint or only the prompt did.
prompt_onlyis weaker and must be visible in request metadata. - On parse failure, keep the raw output and report
failure_kind="schema". Never discard the text or return a silent default. - Parse balanced braces, not a
\{[^{}]*\}regex; nested objects and arrays are normal. - When a response contains several sections, wrap the machine-readable block in explicit sentinels and parse only that block.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

