The Best Way to Talk to Your AI Agents

What It Covers

Anthropic engineer Tarik Shehpar's viral essay arguing for HTML over Markdown as the primary agent communication format sparked a broader debate about how knowledge workers should structure context for AI agents, reflecting a fundamental shift from producing final outputs to staging conditions for agents to produce them.

Key Questions Answered

• •HTML vs. Markdown selection criteria: Choose between formats using three questions: Who reads it (Claude favors Markdown, humans favor HTML), how often is it edited (frequent edits favor Markdown, one-time documents favor HTML), and how long does it live (permanent indexed files favor Markdown, ephemeral outputs favor HTML). Format selection becomes mechanical once these three variables are answered.
• •Token cost tradeoff: HTML files consume significantly more tokens than equivalent Markdown files, a real cost consideration when using Claude or other paid models. Before switching wholesale to HTML, evaluate whether the richer visual output justifies the increased API spend, particularly for internal agent-to-agent handoffs where human readability provides no additional value.
• •Mixed-doneness encoding: When briefing agents, projects contain three simultaneous states — locked decisions, fully open areas, and provisional directions. HTML's native features (color-coded sections, tabs, expandable panels, visual hierarchy) communicate these states structurally without requiring meta-commentary inside the document, reducing the risk of agents over-constraining or under-constraining their output.
• •Calibration as the core operator skill: Over-specifying agent instructions eliminates the agent's comparative advantages; under-specifying produces generic or directionless output. The productive skill in agentic work is determining exactly how much structure to impose so that the remaining unstructured space contains problems the agent can resolve productively without constant human redirection.
• •Session handoff methodology: When transferring context between AI sessions (Claude app to Claude Code, ChatGPT to Codex), instruct the brainstorming session to explicitly label what is decided versus provisional in the handoff document. Without this, AI-generated summaries present all content as finalized, which artificially constrains the receiving builder agent and degrades output quality.