Skill Output Schema: Stop Agents From Guessing What The Next Step Needs

A Skill output schema is the structured contract a Skill returns after it runs. Many teams already understand that input data should not be buried inside a long prompt, so they begin to define Source Data fields. The task starts more cleanly, but the output often remains free-form text. The next Agent must guess which sentence is the conclusion, which line is evidence, which risk requires a human, and which file should be created. That guessing creates repetitive, time-consuming, manual parsing, inefficient reviews, and error-prone follow-up work.

Input fields answer how the work begins. A Skill output schema answers how the work is handed to the next step. For the input side, read Source Data fields for reusable Agents. For artifact review, connect this idea with the workspace artifact acceptance contract. The output side needs its own discipline: what object does the Skill return, which fields can an Agent read, which fields must be shown to a reviewer, and which risks change Trust Mode?

A Skill without an output contract produces text that may look useful. A Skill with an output contract becomes a stable interface inside Agent orchestration.

Start With Four Returned Objects

Do not begin with an overdesigned schema. Most office workflows can start with four returned objects: result, evidence, risk, and nextAction.

Object	Purpose	Typical fields	Downstream use
result	Carries the business-facing answer	summary, decision, draftText	Report generation, email draft, briefing note
evidence	Shows where the answer came from	sourceId, quote, filePath, confidence	Human review and citation trace
risk	Marks what should not be automated directly	level, reason, affectedObject	Trust Mode and exception routing
nextAction	Tells the Agent what should happen next	actionType, owner, deadline	Scheduling, handoff, or another Skill call

The official JSON Schema overview explains schema as a way to describe JSON data structure. In Axon work, the point is not to show off schema design. The point is to let Agents, reviewers, and workspace artifacts use the same structure instead of interpreting prose differently.

The Result Is Not The Whole Truth

result.summary may be a useful answer. result.draftText may be a good draft. Neither should travel alone when the output can affect customers, files, contracts, or external systems. Evidence and risk must move with the result.

NextAction Must Be Reviewable

"Send this to the customer" is not enough. The output should include actionType, affected object, owner, and allowed options. A reviewer should be able to approve the draft, revise terms, save only, or reject with a reason that the Agent can use on the next run.

Use An Envelope The Agent Can Route

The following envelope shows a research Skill returning a business summary, evidence, risk, and a controlled next action. It is not a universal template; it is a practical target for field granularity.

{
  "skillRunId": "run_20260525_0910_research_note",
  "status": "needs_review",
  "result": {
    "summary": "Supplier A raised prices this week, but delivery commitments did not change.",
    "draftFile": "workspace/output/supplier-brief.md",
    "language": "en"
  },
  "evidence": [
    {
      "sourceId": "quote-sheet-2026-05",
      "filePath": "workspace/input/supplier-quotes.xlsx",
      "cellRange": "B12:E18",
      "confidence": "high"
    }
  ],
  "risk": {
    "level": "medium",
    "reason": "The price change may affect a customer quotation and needs business review.",
    "affectedObject": "customer quotation draft"
  },
  "nextAction": {
    "actionType": "request_confirmation",
    "owner": "sales-ops",
    "allowedOptions": ["approve_draft", "revise_terms", "save_only"]
  }
}

An Agent can route this envelope. If status is complete, it may call a file-generation Skill. If status is needs_review, it can create a human confirmation task. If risk.level is high, it should avoid the automatic send path. OpenAI's Agents SDK tools guide shows why tool outputs matter inside Agent execution. In Axon, a Skill output schema is the governance layer that makes tool output usable in white-collar workflows.

Make The Schema Checkable

Documentation alone is not enough. A team should create a minimal schema for important Skills and use it to check field presence, type consistency, risk markings, and downstream options. In practice, three checks are enough for the first version.

1. Structure check: confirm that status, result, evidence, risk, and nextAction exist, and limit status to complete, needs_review, or blocked.
2. Evidence check: require every evidence item to include a source identifier and a file path, not only a conclusion.
3. Risk check: limit risk.level to low, medium, or high, and make nextAction.allowedOptions specific enough for reviewers to act.

A simplified JSON Schema might look like this:

{
  "type": "object",
  "required": ["skillRunId", "status", "result", "evidence", "risk", "nextAction"],
  "properties": {
    "skillRunId": { "type": "string" },
    "status": { "enum": ["complete", "needs_review", "blocked"] },
    "result": { "type": "object" },
    "evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["sourceId", "filePath"]
      }
    },
    "risk": {
      "type": "object",
      "required": ["level", "reason"],
      "properties": {
        "level": { "enum": ["low", "medium", "high"] }
      }
    },
    "nextAction": { "type": "object" }
  }
}

This structure is especially useful for research, PDF summary, and email-draft workflows. The Research PDF Email Agent workflow is a natural example: summary, source evidence, draft output, and confirmation action should not be blended into one paragraph.

FAQ

Q1: Does every Skill output need to be JSON?
No. Markdown, YAML, and tables can work when humans are the main readers. But if another Agent or Skill needs to use the result, stable fields are more important than the display format.

Q2: Will a schema limit model creativity?
It limits the wrong kind of variation. The draft text can remain natural. Status, evidence, risk, and next action should not drift from run to run.

Q3: When is a Skill output schema mandatory?
Use it when a Skill result feeds another Skill, an Agent, a scheduled task, a workspace artifact, or a human review queue. A private one-off summary can stay lighter.

Give Every Output A Next Step

Start with one high-frequency Skill. Define status/result/evidence/risk/nextAction, then add field types and acceptance examples. Once the contract is stable, connect it to Agent orchestration and Skill change control. Download Axon when you are ready to test a low-risk chain, read the Source Data and workspace artifact articles as the next layer, and start using a Skill output schema to make AI digital work handoffs precise instead of interpretive.