agentsop-structured-output-picker
Decide where to enforce structured LM output (constrain at decode time with Outlines vs validate-and-retry with Instructor vs grammar with Guidance) and which failure stance to take (Assert/hard-fail vs Suggest/soft-retry). Use when an LM's output is parsed or typed by downstream code and you must pick one enforcement library plus its failure handling, when malformed output is burning tokens on retries, or when choosing between decode-time vs validation-time constraints for local vs API models.
npx skills add agentsope/SkillAlchemy --skill agentsop-structured-output-picker --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Decides how to enforce that LM output follows a predefined structure, and how to handle violations (hard fail vs soft retry). It offers options to constrain at decode time using Outlines, Guidance, or provider-native outputs, or at validate time using Instructor. It also specifies a failure stance (Assert or Suggest) to determine what happens on violation. The skill is activated after the output shape has been decided and before parsing, and it guides whether to enforce via decode-time grammars, validate-time checks, or provider-native guarantees, based on how costly malformed output would be and whether the decoder is controllable.
How it works
- Assess how costly a malformed output would be and decide between constraints at decode vs validate time.
- Determine decoder control: if you control the decoder, you may apply decode-time constraints (Outlines or Guidance); if using closed APIs, decode-time constraints may be unavailable. Use validate-time enforcement (Instructor) for API models.
- Choose a library based on model type and needs: Outlines (decode-time grammar), Guidance (decode-time control flow + grammar), Instructor (validate-time with Pydantic), or provider-native structured outputs.
- Pick a failure stance: Assert (hard, with retry/halt) or Suggest (soft, log and continue). Default in production is Suggest; Assert reserved for dev/test or critical values.
- Follow a decision workflow: decide enforcement strength, pick the library, then choose the failure stance; apply the appropriate combination to the LM output processing pipeline.
When to use it
- After you decide the output shape and before parsing, when multiple enforcement layers exist and you must pick one plus its failure handling.
- When malformed output is costly to retry (e.g., large batches, real-time processing) or when you need strict shape guarantees with local models.
- When the LM output is consumed by downstream code and you must ensure the content adheres to a predefined structure (JSON, enum, regex, etc.).
What it can touch
- Libraries: Outlines, Instructor, Guidance, provider native structured outputs / tool_use.
- It guides choosing between these depending on whether you can access the decoder and the model type.
Caveats
- For API models without decoder access, Outlines and Guidance are not applicable; Instructor-time validation is typical in that scenario.
- Provider-native structured outputs guarantee schema validity but not content quality; semantic checks may still require an Assert/Suggest stance.
- Unbounded retries are discouraged; finite caps should be enforced for stability.
# Structured-Output-Picker — 在解码处约束，还是在校验处约束？ > **One-liner**: Three local libraries (Outlines, Instructor, Guidance) plus > provider-native structured outputs all "make the model emit valid structure", > but they enforce at *different points* and *fail differently*. Pick by **how > costly a malformed output is** and **whether you control the decoder**. Then > pick the failure stance — **Assert** (hard-fail + retry) vs **Suggest** (soft > nudge, degrade gracefully) — borrowed from DSPy's constraint primitives. This is an **ENHANCE overlay**. The four enforcement mechanisms each have a working local skill; what no single one provides is the cross-library *which-one + how-to-handle-failure* decision. That gap is hit every time an LM output is consumed by code. For **what shape the content should take** (code vs JSON vs prose), descend first to `[[agentsop-output-format-by-model]]` — this skill assumes the shape is already chosen and asks only **how to enforce it**. --- ## 1. 何时激活 (When to activate) Activate **after** you have decided the output *shape* (via `[[agentsop-output-format-by-model]]`) and the answer was "a typed/validated object", and **before** you write the parsing code.
- 1. 何时激活 (When to activate)
- 2. 核心心智模型 (Core mental model)
- 2.1 The axis: where is the constraint applied?
- 2.2 Two prerequisites that gate the choice
- 2.3 Failure stance is orthogonal — Assert vs Suggest
- 3. SOP 工作流 (Decision workflow)
- Step 1 — Decide enforcement strength (how costly is malformed?)
- Step 2 — Pick the library (gated by decoder access + provider)
- Step 3 — Choose the failure stance (Assert vs Suggest)
- 4. 操作模型 (Picker table — task → mechanism + stance)
- 5. 困境决策案例 (Dilemma cases / worked examples)
- 6. 反模式与边界 (Anti-patterns & boundaries)
- Anti-patterns
- Boundaries (when this skill doesn't apply)
What does the agentsop-structured-output-picker skill do?
Decide where to enforce structured LM output (constrain at decode time with Outlines vs validate-and-retry with Instructor vs grammar with Guidance) and which failure stance to take (Assert/hard-fail vs Suggest/soft-retry). Use when an LM's output is parsed or typed by downstream code and you must pick one enforcement library plus its failure handling, when malformed output is burning tokens on retries, or when choosing between decode-time vs validation-time constraints for local vs API models.
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-structured-output-picker --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.