Intermediate

Formatting Output & Speaking for Claude

Claude will choose its own format if you don't specify one. Learn to take control: JSON schemas, Markdown structure, table generation, and the powerful prefill technique.

14 min read 10 examples Chapter 5 of 11

Why Output Format Matters for Downstream Use

Claude's response doesn't end when it reaches you — it feeds into something downstream. Maybe it's parsed by code, inserted into a database, displayed in a UI, reviewed by a human, or piped into another prompt. If the format doesn't match what's expected downstream, the whole pipeline breaks.

Format specification is not about aesthetics — it's about making Claude's output machine-readable, predictable, and processable. A JSON extractor that returns prose once will break your entire data pipeline.

💡
Format is a Contract
When you specify an output format, you're defining a contract between Claude and the code or humans that consume its output. A well-specified format is as important as a well-specified API schema.

Format Options: When to Use Each

📋
JSON
Best for structured data extraction, classification results, API responses, database ingestion. Always specify the exact schema. Use when a machine consumes the output.
📝
Markdown
Best for documentation, reports, content that will be rendered (READMEs, wikis, chat UIs). Counterproductive if output will be processed as plain text or displayed in a non-Markdown context.
📊
Tables
Best for comparative information, reference material, multi-attribute data. Use Markdown tables for rendered contexts, CSV format for spreadsheet ingestion.
📃
Plain Text
Best for voice interfaces, contexts where Markdown renders as raw symbols, or downstream systems that strip formatting. Explicitly request plain text to prevent unwanted asterisks and hashes.
</>
XML
Best for structured output in pipelines that parse XML, or when you need Claude to wrap different sections of a response in labeled tags for downstream extraction.
💻
Code Blocks
Always specify the language for syntax highlighting. For programming tasks, request code-only output when you don't need explanation — saves tokens and makes parsing trivial.

JSON Output: Specifying Schema Explicitly

For any task that requires JSON output, always provide the exact schema. Don't just say "return JSON" — show Claude the exact structure, field names, and types you expect.

JSON Schema Specification
Extract structured information from the following job posting.
Return a valid JSON object — no markdown, no explanation, just JSON.

Schema:
{
  "job_title": string,
  "company": string,
  "location": string | null,
  "remote": "yes" | "no" | "hybrid",
  "salary_range": {
    "min": number | null,
    "max": number | null,
    "currency": string
  },
  "required_skills": string[],
  "experience_years_min": number | null,
  "seniority": "junior" | "mid" | "senior" | "lead" | "unknown"
}

<job_posting>
{job_posting_text}
</job_posting>
Pro Tip: Use Type Annotations
Adding string | null, number | null, and enum values like "yes" | "no" | "hybrid" to your schema dramatically improves Claude's JSON output consistency. It signals the valid type domain for each field, reducing type mismatches.

Markdown Formatting: Helpful vs. Cluttering

Markdown formatting is additive when it renders — and visual noise when it doesn't. Know your rendering context:

Markdown Format Control
# Requesting rich Markdown (rendered UI, documentation)
Write a technical README for this Python library.
Use: H2 headers for sections, code blocks for examples,
bold for key terms, bullet lists for features.
Format: standard GitHub README style.

# Requesting no Markdown (plain text contexts, voice, SMS)
Write a short welcome message for our SMS onboarding flow.
Plain text only — no asterisks, no hashes, no bullet characters.
Just clean sentences.

# Controlling Markdown granularly
Write a product comparison.
Use a Markdown table for the feature comparison.
Use plain prose for the recommendation paragraph.
No headers — this will be embedded in a larger document.

The Prefill Technique: Speaking for Claude

The Claude API lets you pre-populate the start of Claude's response. This is called prefilling the assistant turn. It's one of the most powerful format control techniques in the API.

By adding a partial message in the assistant role, you force Claude to continue from that point — anchoring the format, tone, and structure from the very first character.

Prefill Pattern (Python)
import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key financial metrics from this earnings call transcript.\n\n<transcript>{transcript}</transcript>"
        },
        {
            "role": "assistant",
            "content": "{"  # <-- Prefill forces JSON output from character 1
        }
    ]
)

# Claude continues from the "{" — response is guaranteed to start as JSON
raw = "{" + message.content[0].text
import json
data = json.loads(raw)

Anti-Preamble: Eliminating "Certainly!"

Without guidance, Claude often starts responses with filler phrases like "Certainly! I'd be happy to help...", "Great question!", or "Of course! Here's what I found...". These phrases add zero value and waste tokens. Prefill is the most reliable way to eliminate them:

Summarize the following article in 3 bullet points. [article text] --- Claude responds: "Certainly! I'd be happy to summarize this article for you. Here are three key points from the text: • ..."
// Using prefill in the API: messages=[ {"role": "user", "content": "Summarize the following article in 3 bullet points.\n\n[article text]"}, {"role": "assistant", "content": "•"} // starts directly at the bullets ] --- Claude responds (continuing from "•"): "• [First key point] • [Second key point] • [Third key point]"
// If you can't use prefill (e.g., in a chat UI), add explicit instructions: "Summarize the following article in 3 bullet points. Start your response directly with the first bullet point. Do not include any preamble, acknowledgment, or introduction. [article text]" --- This instruction approach works ~90% of the time. Prefill is 100% reliable.

Format Specification Formula

A complete format specification answers five questions about the output:

1
Structure: What format?
JSON, Markdown, plain text, XML, table, numbered list, bullet list. Be specific about the top-level structure.
2
Schema: What fields/sections?
For JSON, specify the exact schema. For documents, specify the sections and headers. For lists, specify if numbered or bulleted and how many items.
3
Length: How much content?
Word count, character count, number of items, number of sentences. Don't leave this to Claude's discretion if it matters.
4
Tone: What register?
Formal, casual, technical, accessible. Specifying tone ensures the content inside the format matches the format's purpose.
5
Exclusions: What to omit?
Explicitly exclude elements you don't want: no preamble, no caveats, no examples, no explanation — only the output.

Before / After: With and Without Format Spec

Analyze the pros and cons of remote work.
Analyze the pros and cons of remote work for a mid-size B2B software company. Format: a Markdown table with two columns (Pros | Cons). Include exactly 5 rows — most impactful items only. After the table: one paragraph (3 sentences max) with a net recommendation. No preamble. No headers other than the table. Start with the table directly.
No Format Spec: 4+ paragraphs of prose, some with headers, some without. Lists or no lists — unpredictable. Might include "Great question!" opener. Might be 200 words or 800 words. Hard to parse, hard to compare with other analyses. With Format Spec: Exactly as requested — a clean 5-row table, followed by one concise recommendation paragraph. Parseable, comparable, and consistent across runs. Every regeneration produces the same structure.
Chapter 5 Takeaway
Format specification transforms Claude from a general-purpose text generator into a precision output machine. Use the five-question formula (structure, schema, length, tone, exclusions) for any output that feeds a downstream system or follows a template. Use prefill in the API to guarantee format compliance from character one.