Markdown In, HTML Out: A Crash Course

Write in Markdown. Read in HTML. The two document languages of working with agents.

Most people type a vague request into an AI and get a long wall of text back. The request was vague, so the AI had to guess what they meant. The answer is too long to read, so they skim it. Something is lost in both directions: the AI never really understood them, and they never really read its answer.

This course fixes both directions, with one language for each. Both names may be new to you. Markdown is plain text with a few extra marks that show structure: a # before a heading, a - before each item in a list. You have already seen it without knowing its name: when Claude or ChatGPT makes a word bold or gives you a bullet list, it is writing Markdown. You type it straight into the same chat box you already use; there is nothing to install. HTML is the language web pages are built from: every page you have ever opened in a browser, including this one, is HTML underneath. Neither is programming. Both are ordinary text. The skill is knowing which one to use in which direction.

Power users split the conversation by direction. They write to the AI in Markdown (headings, lists, code blocks), because structure leaves it nothing to guess about. And they ask the AI to answer in HTML (diagrams, tables, color, interactivity), because a designed page is the only long answer a busy human actually reads. The first language takes an hour to learn. The second one you never write at all; you only learn to demand it. (One word before we go on: this book says agent for an AI that does multi-step work on your behalf. Today that is just Claude in a browser tab. Later in the book it gets a terminal and your files. The format rules you learn here are the same either way.)

The whole course, in one picture:

Behind the picture sits one question, and it settles every format decision in this course: who reads this last? If a person will read it in a browser, ask for HTML. If an AI will read it, or you will feed it back to an AI later, keep it in Markdown. If it is going into a social feed, plain text. "Markdown in, HTML out" is just the most common pair of answers. Hold the question; the rest of this page is the details.

Prove it in two minutes

Before any theory, run the whole course once. Open Claude.ai (a free account takes a minute; ChatGPT or Gemini work too) and paste:

Make me a small web page as an HTML artifact: a welcome card for a
neighborhood tuition center. A colorful holiday-notice banner on top,
three example courses with monthly fees in a neat table, and a
WhatsApp contact button. Keep it readable on a phone.

Claude thinks for a moment, then opens a panel beside the chat and builds a real, styled page in it: banner, table, button. That panel is an artifact: a live document the AI builds next to the conversation instead of inside it. (ChatGPT and Gemini call theirs Canvas; same idea.) If you got a wall of code instead of a rendered page, say show it to me as a rendered artifact and it will flip. Now find the share or publish control on the artifact panel, tap it, and open the resulting link on your phone.

Two minutes, and you have already done everything this course teaches, once, by accident: a few structured lines went in, a designed page came out, and a link made it shareable. The thirteen concepts below make each of those steps deliberate, so they keep working when the stakes are higher than a demo. Part 1 frames the split. Part 2 teaches the handful of Markdown you write by hand. Part 3 teaches you to demand, judge, and publish HTML you never write. Part 4 runs one exercise across the three ways you will meet agents in this book. By the end you will be able to write a clean Markdown spec, turn it into a readable HTML artifact someone else can open from a link, and decide for any given output whether it should be Markdown, HTML, or plain text for a feed.

📚 Teaching Aid

Open Full Slideshow

View Full Presentation — Markdown In, HTML Out

---

This crash course assumes you have read AI Prompting in 2026. The habits it taught (load the right context, brainstorm then iterate, grade the output out of 10) all reappear here; this course gives them a file format to live in. The deeper tool walkthroughs live in the Agentic Coding Crash Course and the Cowork & OpenWork Crash Course; you need neither to finish this page.

What you need

• One free chat account. Claude.ai is what the examples use; ChatGPT or Gemini run every chat prompt here unchanged. Where a prompt says "artifact," say "Canvas" on those two; on any other tool, ask for "a single HTML file" and it works the same.
• Web access turned on in the tool, so the AI can fetch the links you include. In most tools it is on by default; if a link example does not work, check the web search setting.
• A phone, to judge what you make the way your readers will actually see it.

Reading takes about an hour; the seven closing prompts add about thirty minutes. Run the prompts as you go: reading gives you the vocabulary, running them gives you the skill.

---

Part 1: The two languages

1. Why agents need structure

Here is the same request, written twice.

Unstructured:

I want a page for my tuition center, it should look professional
and have our courses and timings and a way for parents to contact
us, also fees, and it should work on phones since most parents
use phones, oh and put the Eid holiday notice somewhere visible.

Structured:

# Tuition Center Landing Page Specification

## Goal
A single-page site parents visit from their phones to check
courses, timings, fees, and contact info.

## Requirements
- Mobile-first layout (most visitors are on phones)
- Course list with timings and monthly fees
- Contact section: phone, WhatsApp link, location
- Holiday notice banner at the top (currently: Eid holidays,
  center closed June 6-9)

## Out of scope
- Online payments
- Student login

Both contain the same information. But the first forces the agent to infer the structure: is the holiday notice more important than the fees? Is "professional" a constraint or a vibe? Is "a way to contact us" a form or a phone number? Every inference is a place the agent can guess wrong, and an agent that guesses wrong does not look wrong. It looks confident.

The second version makes the structure explicit. Headings declare what kind of information each block is. Bullets declare that the requirements are a set, each one independently checkable. And the "Out of scope" section does something prose almost never does: it states what you do not want, which is half of every good specification.

This is why Markdown is the specification language of agentic work. Agents are trained on enormous amounts of Markdown (most of the documentation on the internet is written in it), so they parse its structure natively: a # heading is not decoration to them, it is a signal about hierarchy and importance. (Later chapters call the place these written-down intentions live the Intent Layer: human intent, written precisely enough for an agent to act on. You are learning to write it now.)

A non-software example. A school administrator asked an agent to "draft the annual sports day plan, the usual events, and make sure the younger kids aren't in the afternoon heat." The draft scheduled the under-8 races at 2 p.m. anyway: the constraint was buried mid-sentence in prose, and the agent weighted it as a preference. She rewrote the request with a ## Hard constraints heading containing one bullet: "All under-8 events must finish before 11:30 a.m." The next draft complied perfectly. The constraint did not change. Its visibility in the structure changed.

The habit, stated once: anything an agent must not get wrong belongs under its own heading or in its own bullet, never inside a sentence.

2. The asymmetry: Markdown in, HTML out

So Markdown is the input language. Is it the output language too? Until recently, yes: agents answer in Markdown by default, and for short answers that is fine.

But if your mental picture of AI output is walls of bulleted text, that picture is now out of date. In a widely-circulated essay, Thariq Shihipar of Anthropic's Claude Code team described why he and others on the team stopped asking for Markdown outputs and started asking for HTML. His reasoning, paraphrased:

• Long Markdown is unreadable. Past about a hundred lines, humans stop reading Markdown files, and as agents take on bigger tasks, their plans and reports keep getting longer. The hundred is not a magic number; the honest test is whether you would read the thing top to bottom, and at some length the answer becomes no. An unread plan is a plan you did not actually approve.
• Markdown's ceiling is low. Headings, lists, tables, and not much else. When an agent needs to show you a workflow, a color palette, or a layout, Markdown resorts to ASCII art: charming, but a workaround.
• HTML has almost no ceiling. Styled tables, diagrams, annotated code, interactive controls. There is very little an agent can know that HTML cannot show a human efficiently.
• HTML is shareable. Browsers render it natively. A colleague clicks a link; nobody installs anything. People actually read a designed page; they politely ignore a raw text file.
• Markdown's killer feature is fading. Markdown was great because humans could easily hand-edit it. But increasingly you do not hand-edit agent output; you prompt the agent to edit it. Once the agent does the editing, the format only has to suit the reader.

The result is a clean asymmetry, and it is the spine of this entire course:

Direction	Format	Why
You → agent	Markdown	Structure removes ambiguity. Fast to type. Agents parse it natively.
Agent → you	HTML	Rich, readable, shareable, interactive. A 500-line plan you will actually read.
Agent → agent	Markdown	Specs, notes, and context passed between AI sessions stay compact and precise.

You write the first row by hand, which is why Part 2 teaches it properly. You never write the second row; you prompt for it, which is why Part 3 teaches the prompts instead of the tags.

"HTML out" has one condition: the reader is human

Every advantage HTML has is an advantage for eyes and browsers. To an AI, the same file is noise around the meaning: tags, styling, and layout code spending thousands of words to say what Markdown says in fifty. So anything kept for an AI stays Markdown. That includes more than you might think: a new chat remembers nothing, so the notes you save today and paste into tomorrow's conversation are "agent → agent" too, even though both agents are talking to you. Ask the one question: who reads this last?

• A person reads it last → HTML.
• An AI reads it last (including a future chat) → Markdown.
• Honestly unsure → Markdown. A person can read Markdown well enough; an AI reads HTML badly. And you can always render Markdown into HTML at the moment a person needs it.

Where you have already seen this asymmetry

Every chapter of this book is written in Markdown (the source files end in .md), and the diagrams you see are mostly SVG, which is HTML's illustration language. The book practices the asymmetry it preaches: Markdown where precision matters, rich visuals where human reading matters.

---

Part 2: Markdown, the writing language

Markdown has dozens of features. You need five. The five below cover essentially every specification, brief, and context file you will write in this book, and the closing concept of this part assembles them into your first complete spec.

How to practice: every example in this part is a prompt you can paste into Claude.ai right now. The structure you type is the lesson.

3. Headings: hierarchy is meaning

A # makes a heading. More # symbols make deeper levels:

# Document title          (one per document)
## Major section
### Subsection

That is the entire syntax. What matters is what hierarchy does for an agent: it declares which information governs which. Everything under ## Hard constraints is a constraint. Everything under ## Nice to have is negotiable. The agent does not have to infer importance from your adjectives; the tree tells it.

Three rules that prevent 90% of heading mistakes:

Rule	Why it matters to an agent
One # title per document	Two titles means two documents fused together; the agent may treat them as separate tasks.
Never skip levels (# → ###)	A skipped level breaks the tree; the agent can misattach a subsection to the wrong parent.
Make headings claims, not labels	## Budget says less than ## Budget: PKR 50,000 hard ceiling. The heading itself carries the constraint.

Try it now. Paste this into Claude.ai:

Here are my notes for a family Eid dinner, as one messy paragraph:

"around 20 guests, three are vegetarian, budget about 25k rupees,
my mother handles the biryani so don't plan a main rice dish,
need a kids' table, dinner at 8pm, we are renting 4 extra chairs."

Restructure these notes as a Markdown document with headings for
Goal, Hard constraints, Already handled, and Open questions.
Put each fact under the right heading. If a fact could belong to
two headings, choose one and tell me why.

Read what comes back. The agent will make a judgment call or two (is "dinner at 8pm" a constraint or a goal?), and seeing it explain the call teaches you how agents read your structure.

4. Lists: bullets for sets, numbers for sequences

Two list types, one distinction that agents take seriously:

Features the page must have:        Steps to publish:
- Course list with fees             1. Review the draft
- WhatsApp contact button           2. Fix the timings table
- Holiday banner                    3. Publish
- Urdu/English toggle               4. Send the link to parents

• Bullets (-) say: these items are a set; order does not matter; each is independently true. Use them for features, requirements, constraints, options.
• Numbers (1.) say: these items are a sequence; order is the point; step 3 assumes step 2 happened. Use them for procedures, workflows, anything where doing it backwards breaks it.

This sounds cosmetic. It is not. Give an agent a numbered list and it treats the order as part of the instruction; it will almost never start step 4 before step 1. Give it bullets and it feels free to address items in whatever order is efficient. Choosing the wrong list type sends the wrong signal about your intent.

Nesting adds one more dimension: sub-items belong to their parent.

- Contact section
  - Phone number (clickable on mobile)
  - WhatsApp deep link
  - Map pin, not a full embedded map

The checkable-bullet habit. The best requirement bullets are ones a reviewer could mark ✅ or ❌ without discussion. "Page should be fast" is not checkable. "Page loads in under 3 seconds on a 3G connection" is. When you write a spec, reread each bullet and ask: could the agent, or I, verify this one objectively? This is the grade-out-of-10 discipline from AI Prompting in 2026, applied one bullet at a time.

5. Code blocks: showing instead of describing

Triple backticks fence off a block of literal content, content the agent should treat as exact rather than as more instructions. (The backtick ` lives above the Tab key on most laptop keyboards; on a phone keyboard, long-press the apostrophe.)

```python
def greet(name):
    return f"Assalam-o-Alaikum, {name}!"
```

The language tag after the opening fence (python, bash, text, html) tells both humans and agents how to interpret the block. Single backticks do the same job inline: write `npm install` when you mean the literal command, not the concept of installing.

Why this matters more with agents than it ever did with humans: an agent strongly tends to treat fenced content as data and unfenced content as instructions. The fence is a quoting mechanism. Three situations where it saves you:

Situation	Without fences	With fences
Showing an error message you want diagnosed	Agent may "helpfully" act on words inside the error	Agent analyzes the error as a literal artifact
Including example output you want matched	Agent paraphrases the format	Agent reproduces the format exactly
Quoting someone else's text inside your prompt	Agent can confuse their voice with your instructions	Clean boundary between quoted text and your ask

And the non-obvious one: fence your expected output. The single highest-leverage use of a code block in a spec is showing the agent exactly what a correct result looks like:

The timings table must look exactly like this:

| Course        | Days     | Time          | Monthly fee |
| ------------- | -------- | ------------- | ----------- |
| Matric Math   | Mon-Wed  | 4:00-5:30 pm  | PKR 3,500   |

Same columns, same order, same fee format.

One example row replaces three paragraphs of format description, and the agent cannot misread it.

6. Links and images: pointing at the world

The last two pieces of syntax:

[link text](https://example.com)
![description of the image](path/or/url.png)

Links matter in specs for one big reason: a link is context the agent can fetch. Modern agents follow links. Claude.ai fetches URLs you include when web access is on, and the file-reading tools you will meet in Part 4 follow file paths the same way. So instead of summarizing your school's fee policy from memory (and summarizing it wrong), link the policy page and write "fees must match this." You just replaced a paragraph of possibly-wrong context with the source of truth. This is the get-the-right-context-in move from the prompting course, expressed as syntax.

Images matter for the reverse reason: the ! prefix embeds rather than links, and the description in the brackets (the alt text) is what an agent, a screen reader, and a search engine read when they cannot see the image. When your spec includes a mockup screenshot, the alt text is your chance to say what the agent should notice: ![Mockup: banner on top, course table in the middle, contact buttons pinned to bottom].

7. Your first complete specification

Everything above assembles into one artifact: the specification. This is the document shape you will write hundreds of times in this book: for web pages now and, later in the book, for Digital FTEs, AI agents built to carry a whole role the way an employee would (a digital "full-time equivalent"). A spec like this is how you brief one. The skeleton:

# [What you are building] Specification

## Goal

One paragraph: what this is and who it serves.

## Context

Links and facts the agent needs. Attach files; link sources.

## Requirements

- Checkable bullet
- Checkable bullet
- Checkable bullet

## Hard constraints

- Things that must not be violated (budget, deadline, platform)

## Out of scope

- Things you are explicitly NOT asking for

## Expected output

A fenced example, a format description, or a mockup image.

Two sections of this skeleton do disproportionate work. Out of scope kills the agent's most common failure: enthusiastic over-delivery, the login system you never asked for, the seventeen features that bury the three you wanted. Expected output kills the second most common: format drift.

And then the move that separates a spec from a wish: validate the spec before you execute it. Do not hand your first draft to an agent and hope. Hand it to an agent and ask it to attack it:

Here is my specification: [paste spec]

Do not build anything yet. First, review the spec itself:
1. List every ambiguity: every place where two reasonable
   readers would build two different things.
2. List every missing constraint you would need to guess.
3. Grade the spec out of 10 on clarity, completeness, and
   checkability, with a one-sentence justification each.
4. Suggest the single change that would raise the grade most.

This is the grade-and-iterate loop from AI Prompting in 2026, aimed at your spec instead of the agent's output. Two or three rounds typically takes a spec from 6 to 9, and a 9/10 spec is the cheapest quality improvement in all of agentic work, because every downstream artifact inherits its clarity. Fixing one ambiguous bullet in a spec costs one minute. Fixing the wrong thing the agent built from that bullet costs an afternoon.

The spec is the deliverable

A mindset shift this book will keep reinforcing: in AI-native work, the specification is not paperwork before the real work. It is the real work. The agent's output is a function of your spec; improve the spec and every regeneration improves with it. The book calls building this way spec-driven development, and Part 1 of the book develops it fully. This skeleton is its seed.

---

Part 3: HTML, the reading language

You now write structured input. The second half of the skill is demanding structured output, and here the rule inverts completely. You will not learn HTML tags here, because you will not write them. The agent writes them. Your job is to know when to ask for HTML, what to ask for, and how to judge what comes back.

8. Why ask for HTML at all

Run this experiment once and you will never need convincing again. Take any plan or report an agent has produced for you in Markdown, something longer than a screen. (No long answer in your history yet? Ask for a detailed two-week study plan for anything you are learning, then use that.) Then ask:

Turn this into a single HTML file designed for reading:
clear visual hierarchy, a small table of contents, the key
numbers as a styled table, and one SVG diagram of the overall
flow. Optimize it for someone reading it once on a phone.

What you get back is the same information, but you will actually read it this time. That difference, read versus skimmed, is the entire argument. You felt a small version of it in the two-minute proof at the top; the appendix shows it end to end with a real spec. Unpacking the difference into its parts:

What HTML adds	What it looks like in practice
Information density	Tables, color-coding, SVG diagrams, annotated code, instead of ASCII art and walls of bullets
Navigability	Tabs, a table of contents, collapsible sections: a 500-line plan you can move through
Shareability	Opens in any browser; publish an artifact link and a parent, student, or colleague clicks it, with no app and no account
Interactivity	Sliders, toggles, draggable cards, live previews: the document becomes an instrument, not a printout
A "copy back" loop	A button that exports your choices as text you paste back to the agent: you adjust visually, the agent receives precisely

That last row is worth a closer look, because it is the least obvious and the most powerful. Some preferences are miserable to express in words: a color, an animation speed, the priority order of thirty items. Asking the agent to build controls for them, plus a copy as text button, turns "make it a bit warmer, no, less orange" into thirty seconds of dragging a slider and one paste. You stay in the loop; the loop gets tighter.

A non-software example. A principal asked an agent for a report on three years of admission trends. The Markdown version was nine screens of bullets; she read two. Re-prompted as HTML (trend lines as SVG charts, one color per campus, a findings table on top, details collapsed below), the same report took four minutes to absorb, and she forwarded the published link to her board that evening. Nobody on the board would have opened a .md attachment. Everybody clicks a link.

An honest caveat

HTML output uses more tokens than Markdown, and for a three-line answer it is pure overhead. The trade is worth it precisely when the output is long, visual, shared, or revisited. As your tasks grow, that becomes most of the outputs that matter. For quick back-and-forth in chat, plain responses remain the right default. Match the format to the reading, not to fashion.

One more cost that bites on mobile data: a heavy interactive artifact (external fonts, large embedded images, big libraries) can balloon to several megabytes, which is a real problem for a reader opening it on a phone on a slow connection. When bandwidth matters, say so in the brief: "lightweight, single file, no external fonts or libraries, keep it under 200 KB." The agent will inline what it needs and skip what it does not.

9. You don't write HTML; you prompt for it

Getting HTML out of an agent takes no special syntax. In Claude.ai, say "create an HTML artifact." In the terminal tools you will meet in Part 4, say "write this as an HTML file." That is genuinely the whole trigger.

What separates a mediocre HTML output from an excellent one is not the trigger but the brief, and the brief is just your Part 2 skills pointed in the other direction. The four elements of a good HTML request:

1. The reader. "For my board, reading once on phones" produces different design than "for me, as a working reference I'll revisit."
2. The components. Name what you want: a diagram of X, a table of Y, annotated snippets of Z, a gotchas section at the bottom. Agents are excellent at rendering components and mediocre at guessing which ones you wanted.
3. The interaction, if any. Sliders for what? A copy button that exports what, in what format?
4. The reading mode. "Optimize for reading once" versus "optimize as a reference" versus "make it presentable to a client" each pull the design a different direction.

Compare:

Weak:   Make an HTML report about my sales data.

Strong: Read the attached sales CSV. Produce one HTML file for
        my two co-founders, reading once on laptops: a headline
        findings strip on top (3 numbers, large), one SVG chart
        of monthly revenue by product, a table of the 5 fastest
        growers, and a short "what I'd do next" section. No
        scrolling past 3 screens.

The strong version is nothing but reader + components + reading mode. It is a Markdown-shaped brief whose deliverable happens to be HTML.

Judging what comes back. The grading discipline transfers directly. A useful rubric for any HTML artifact, out of 10 each: Is every fact from my source represented? Can I find the most important thing in 10 seconds? Does it read on a phone? Would I forward this link? Anything under 9, name the gap and regenerate. Iterating an artifact is cheap; the agent edits it in place.

10. The five HTML patterns

Five recurring shapes cover most of what the Claude Code team, and soon you, use HTML output for. Each pattern below names the shape and gives a prompt skeleton where you can use one today.

Pattern 1: Plans and explorations. Instead of one linear Markdown plan, ask for an options-comparison page first, then a deep page on the winner. You approve direction visually before any execution.

I'm deciding how to structure [thing]. Generate 5 distinctly
different approaches and lay them out in one HTML file as a
grid I can compare side by side. Label each card with the
trade-off it makes. Don't recommend yet. Let me look first.

Pattern 2: Explainers and reports. The principal's admissions report above. Anything synthesized from sources you will not read raw: data files, long documents, a folder of meeting notes.

Read [source]. Produce a one-page HTML explainer: an SVG
diagram of how [system/process] works, the 4 key facts
annotated, and a "gotchas" section at the bottom. Optimize
for someone reading it exactly once.

Pattern 3: Code review and understanding. Code changes, annotations, and flowcharts render beautifully in HTML and miserably in Markdown. This pattern matures in the Agentic Coding Crash Course; just know it exists.

Pattern 4: Design prototypes. HTML is an expressive sketching medium even when the final product is not a web page. Ask for a prototype with sliders and knobs for the parameters you cannot put into words, plus a copy-parameters button.

I'm choosing the look for [thing] and I can't describe what I
want in words. Build an HTML artifact with one sample card and
live controls for it: sliders for background warmth and corner
roundness, a few accent-color swatches, a font-size toggle, and
a "copy parameters" button that exports my final choices as
text I can paste back to you.

Pattern 5: Throwaway editors. The most underrated pattern: a single-purpose, disposable interface for the exact data in front of you. Thirty items to prioritize? Ask for draggable cards in Now / Next / Later columns with a copy as Markdown button. Use it for ten minutes, paste the export back, never open it again. The HTML editor is the throwaway; the Markdown it exports is the thing you keep. That is the agent → agent rule in action: the interface discarded, the text preserved. The export button is what makes the pattern work; it closes the loop back to text.

Notice the through-line: in every pattern, Markdown (or your data) goes in, HTML comes out, and anything that needs to continue the conversation comes back as text. The asymmetry from Concept 2, now as a working rhythm.

11. When the destination is a feed, not a browser

One place needs a footnote to the rule, and for this book's audience it is a common one: posting to WhatsApp, LinkedIn, or Facebook. "HTML out" works because the human opens your page in a browser. A social feed does not open your HTML; it renders its own interface and pours your content into its box. So here the question shifts from who reads this last? to what does the destination actually render?

All three render almost no markup at all:

• WhatsApp shows plain text with a thin styling layer (*bold*, _italic_). It ignores HTML and Markdown headings entirely. Output plain text, phone-shaped: short lines, maybe an emoji as a visual anchor, a bare URL if you are linking out.
• LinkedIn and Facebook render their own feed formatting, not yours; the post body is essentially plain text (LinkedIn does not even honor Markdown bold, so people fake it with Unicode bold characters). Output plain text tuned to the platform: LinkedIn rewards a strong first line before the "…see more" fold; Facebook rewards brevity.

Pasting raw HTML as a post body is the one move that is always wrong; it lands as a wall of angle brackets.

But HTML does not disappear here. It moves to two side channels, and this is where the Part 3 skill still pays off:

• The link preview card. When you post a URL, the platform scrapes that page's Open Graph tags (og:title, og:description, og:image) and builds the preview card, usually the most-seen part of the whole post. So if you are sharing a page you made, the HTML matters enormously, just indirectly. Brief it in: "include proper Open Graph meta tags and a representative og:image so the link preview looks designed, not blank."
• The image. Feeds favor images, and the easiest way to design one (a quote card, a stat card, an infographic) is to have the agent build a single styled HTML card and then render it to a PNG and post the image. The HTML briefing skill transfers wholesale; you just add a "render this to a 2× PNG" final step.

So the full picture for social is a small split, and it mirrors the course's own asymmetry: text for what the feed renders, HTML for what it scrapes or screenshots.

Destination	Output	Why
WhatsApp message	Plain text, phone-shaped	No markup renders; only text and auto-generated link previews
LinkedIn / Facebook post body	Plain text, platform-tuned	The feed renders its own formatting, not yours
A page you link from a post	HTML with proper OG tags + og:image	The platform scrapes Open Graph to build the preview card
An image for the post (quote/stat card, infographic)	HTML → rendered to PNG	Feeds favor images; HTML is the easiest way to design one

12. Publishing: from artifact to link

Producing an HTML file and publishing it are two different steps. The two-minute proof used the easiest rung; here is the whole ladder, easiest first, most durable last. Pick the lowest rung that meets the need.

Claude.ai's built-in publish: easiest, zero setup. When the agent makes an HTML artifact in Claude.ai, the artifact panel has a share/publish control. One click turns it into a public URL that anyone can open: no account on their end, no hosting, no file to manage. Drop the link in WhatsApp or email and you are done. Two things to know: the link is public, so anyone who has it can open it (do not publish anything private), and you can unpublish later from the same menu. Use this rung for reports, spec briefs, one-page explainers: anything you want seen, not owned. The tradeoff: the page lives on Anthropic's infrastructure and the URL is theirs, so it is not the home for something you want on your own domain long-term. (This rung only exists on Claude.ai. The file-writing tools in Part 4 hand you a real file on disk instead, which leads to the rungs below.)

GitHub Gist: easy, and you own the source. Paste the HTML into a GitHub Gist and open it through a renderer such as htmlpreview.github.io or raw.githack.com (a raw Gist link serves as plain text, not a rendered page, which is the one gotcha). You get a real URL backed by a file you control and can version; edits are just a re-save. Best for a single self-contained file you want to keep and revise without standing up a whole site.

GitHub Pages: durable, free, your own URL. For something that should stay published, commit the HTML to a repository and enable GitHub Pages on it. You get a stable username.github.io/repo URL, free hosting at any scale you will hit, version history for free, and the option to attach a custom domain. More setup than the rungs above (a repo, a settings toggle, a minute for the first build), but it is the right home for a landing page, a brochure, or any artifact with a real, returning audience.

Netlify: durable, with the least friction of the "real hosting" options. Netlify sits between the ease of Claude.ai's publish and the ownership of GitHub Pages. Make a free account (an email address is enough), and its Drop flow lets you drag an HTML file or a folder onto the page and get a live URL in seconds: no repo, no build config, no Git. If you shipped a project in AI Prompting in 2026, this is the same move you used there. Connect a GitHub repo instead and it redeploys automatically on every commit, and a custom domain is a few clicks. For a non-developer who wants a real, durable URL without touching Git, this is usually the gentlest path.

A quick way to choose:

You want…	Use
A link to share right now, nothing to maintain	Claude.ai publish
To own the source file and version it, minimal setup	GitHub Gist
A durable page on your own URL/domain, you are comfortable in Git	GitHub Pages
A durable page with the least friction, drag-and-drop, no Git	Netlify (Drop)
The HTML to live inside this book	A file in the static/ folder

One reminder that applies to every rung: publishing gives you a link, and on a social feed that link's preview comes from the page's Open Graph tags (Concept 11). If the published page will be shared on WhatsApp, LinkedIn, or Facebook, brief the agent to include og:title, og:description, and an og:image so the card looks designed.

---

Part 4: One exercise, three motions

Concepts are tool-independent; muscle memory is not. This part takes one exercise and runs it three ways, because the book uses five tools for agentic work, and they reduce to three motions: chat (Claude.ai, with ChatGPT or Gemini as stand-ins), terminal (Claude Code, OpenCode), and desktop (Cowork, OpenWork). You only have the first today, and that is fine. Do the chat motion now; skim the other two as previews of the same work in more powerful settings, and return to run them after the Agentic Coding and Cowork & OpenWork crash courses.

The exercise. Start from messy notes (any real notes you have: a project, an event, a study plan). Produce two artifacts:

1. spec.md: a clean Markdown specification (Concept 7 skeleton), validated and graded to 9+.
2. report.html: a one-page HTML brief of the spec for someone else (visual summary, key table, one SVG diagram).

Precise Markdown for the machine, rich HTML for the human: the same pair on every surface. Only the mechanics around it change, and the prompt barely changes at all.

13. The three motions

Motion 1: chat. This is the main method; everything happens in one conversation in Claude.ai (or ChatGPT / Gemini, saying "Canvas" instead of "artifact").

Step 1: [paste messy notes] Restructure these into a Markdown
        specification with Goal, Context, Requirements, Hard
        constraints, Out of scope, and Expected output. Put it
        in a Markdown artifact.

Step 2: Review your own spec: list ambiguities, grade it /10 on
        clarity, completeness, checkability. Fix what scored
        below 9. (Repeat until it plateaus.)

Step 3: Now create a second artifact: a single HTML page
        presenting this spec to [your real audience]. Visual
        hierarchy, requirements as a styled table, one SVG
        diagram of the overall flow, readable on a phone.

Step 4: Publish the HTML artifact (Concept 12) and open the link
        on your phone. If you wouldn't forward it, name why and
        iterate.

Why chat is the main method: artifacts render instantly beside the conversation, edits happen in place, and publishing is one click. For a single document pair, nothing beats it. Where it strains: it sees only what you paste or attach. The moment your "messy notes" are eleven files across three folders, you want a tool that can go get the context. That is exactly what the next two motions add.

Motion 2: terminal (preview). Claude Code and OpenCode run in a terminal: put your notes in a folder, open a terminal there, type claude (or opencode), and ask:

Read every file in this folder. Produce spec.md following the
[Goal/Context/Requirements/Hard constraints/Out of scope/
Expected output] skeleton, grading and iterating it to 9+
yourself before showing me. Then produce report.html: a one-page
visual brief with an SVG flow diagram. Tell me when both files
exist and what you'd flag for my review.

Two things changed versus chat: the agent gathered its own context (every file in the folder, not just what you remembered to paste), and the outputs are real files on disk, ready for version control or uploading anywhere. The prompt itself is the same spec-and-grade motion you already know, byte for byte the same on both tools.

Motion 3: desktop (preview). Cowork and OpenWork are the no-terminal version: point the app at your notes folder and ask in plain language, with one addition that becomes non-negotiable the moment an agent can touch your files:

Look through this folder. Propose a plan first (which files
you'll read, what spec.md and report.html will contain) and
do not write anything until I approve.

Plan, review, approve, then execute: the permission discipline from AI Prompting in 2026, now in muscle memory. The app finds the files, and the report lands on your disk ready to share, no terminal in sight.

Choosing a motion, compressed:

Situation	Motion → tool
One document pair, context fits in a paste/attachment, link in under a minute	Chat → Claude.ai (artifacts + publish)
Context lives across many files, a repo, or version history	Terminal → Claude Code / OpenCode
Context lives in your everyday folders; you want plan-first approvals, no terminal	Desktop → Cowork / OpenWork

Within the terminal and desktop motions there is one more axis: Claude Code and Cowork are the polished, batteries-included options; OpenCode and OpenWork are their open-source peers, model-flexible and lock-in-free, which is why they recur throughout this book. The motion, and your prompt, is the same either way.

And the format decision, compressed to its final form:

You are…	Use
Telling an agent what to do	Markdown
Saving context for a future session or another agent	Markdown
Producing output another agent will read and process	Markdown
Reading a long plan, report, or analysis	HTML
Sharing output as a link someone opens in a browser	HTML
Posting into a feed (WhatsApp, LinkedIn, Facebook)	Plain text for the body; HTML only for the linked page (OG tags) or a screenshotted image
Choosing values that are painful to put into words	HTML (with a copy-back button)

---

A short recap before you try the prompts

None of this is for memorizing; it is for coming back to. Bookmark the page, skim the list, and carry only the one sentence at the bottom in your head.

• Concept 1. Agents parse structure, not vibes. Anything that must not go wrong gets its own heading or bullet.
• Concept 2. The asymmetry that organizes everything: Markdown in, HTML out. Behind it, the one question: who reads this last?
• Concept 3. Headings declare hierarchy; make them claims, not labels.
• Concept 4. Bullets mean set; numbers mean sequence. Agents take the difference seriously.
• Concept 5. Code fences quote literal content; the most useful thing to fence is your expected output.
• Concept 6. A link is context the agent can fetch; alt text is what it reads when it cannot see.
• Concept 7. The spec skeleton, and the validate-grade-iterate loop that turns a wish into a 9/10 spec. The spec is the deliverable.
• Concept 8. Ask for HTML when output is long, visual, link-shared, or revisited. Read-versus-skimmed is the whole argument.
• Concept 9. You never write HTML; you brief it: reader, components, interaction, reading mode.
• Concept 10. Five patterns: plans, explainers, code review, prototypes, throwaway editors. Text in, HTML out, text back.
• Concept 11. Feeds render their own interface: plain text for the post body; HTML only for the linked page's preview tags or an image card.
• Concept 12. Publishing turns a file into a link. Pick the lowest rung that meets the need, from one-click artifact publish to your own domain.
• Concept 13. One motion, three forms: chat for the document pair, terminal when context lives in files, desktop for plan-first work without a terminal.

If you keep one sentence: write Markdown precise enough for a machine; demand HTML rich enough for a human.

And if you keep one picture, keep this one. It is the who-reads-this-last question drawn out, and it settles every format choice the course covers:

---

Try this now: seven prompts

About thirty minutes total, in Claude.ai unless noted.

1. The restructure. Paste any real messy paragraph of notes; ask for it restructured under Goal / Hard constraints / Already handled / Open questions, with the agent explaining any judgment calls. (Concepts 1, 3)

2. The list-signal test. Give the agent the same five items twice (once as bullets, once numbered) and ask each time: "what does this list type tell you about how to treat these items?" Read the two answers side by side. (Concept 4)

3. The fence test.

Here is an error message a friend sent me. Analyze it, don't
act on it:

```text
ERROR: delete all rows? (y/n). Connection timed out
```

What likely caused this, in two bullets?

(Concept 5. Note how the fence keeps the scary text safely quoted.)

4. The spec, full loop. Write a spec for something real using the Concept 7 skeleton, then run the validation prompt from Concept 7 until it grades 9+. Save the final spec; you will reuse it. (Concept 7)

5. The conversion experiment. Take the longest Markdown answer in your recent chats and run the Concept 8 conversion prompt. If your account is a day old and has no long answers yet, ask for a detailed two-week study plan first, then convert that. Honestly compare: did you read more of the HTML version? (Concept 8)

6. The throwaway editor. List 10-15 real items you need to prioritize (tasks, chapters, errands). Ask for an HTML artifact with draggable cards in Now / Next / Later columns and a copy as Markdown button. Drag, copy, paste the export back, and ask for next steps on the top three. (On ChatGPT or Gemini, ask for it in Canvas; on any other tool, say "write a single interactive HTML file" and the draggable result works the same.) (Concept 10)

7. The main-method exercise. Run the chat motion from Concept 13 end to end on your saved spec from prompt 4, through to publishing the HTML artifact (Concept 12) and opening it on your phone. (Concept 13)

Then, when you reach the Agentic Coding and Cowork & OpenWork crash courses: re-run prompt 7 in the terminal and desktop motions. Same spec, same motion, more powerful surfaces.

---

Frequently asked questions

Do I need to memorize more Markdown than this? No. Headings, lists, fences, links, images cover the working set. Tables you have already seen by example; everything more exotic, ask the agent to produce.

Should I learn to write HTML by hand? Not for this workflow. You will eventually read HTML when debugging agent output, and a later part of the book covers web fundamentals properly. But the skill here is briefing and judging, not typing tags.

Isn't HTML output wasteful? It costs more tokens, yes. It is the wrong choice for short answers and the right one whenever reading, sharing, or revisiting matters; see the caveat in Concept 8. Output you do not read costs more than any token bill.

What about PDFs, Word documents, slides? Agents produce all of them, and later crash courses use them. The Markdown-in/HTML-out asymmetry still holds as the default for agentic working documents; the office formats are export targets when a context demands them.

Going further: is there tooling for this pattern? Yes, and it is worth seeing after you can do the from-scratch version, not instead of it. The whole skill of this crash course is briefing and judging output yourself, prompting from a blank slate; reach for templates only once that muscle exists, or they will do your thinking for you. With that caveat: an open-source project called HTML Anything productizes exactly the Markdown-in/HTML-out asymmetry from Concept 2. It runs locally, reuses a coding-agent CLI you already have signed in (Claude Code, OpenCode, Gemini, and others; no separate API key), and turns notes, Markdown, or a CSV into a ship-ready single HTML file across ready-made surfaces: decks, posters, data reports, social cards. Its own rationale cites the same Anthropic source this crash course does, useful confirmation that the asymmetry is becoming a shared convention, not one team's habit. Treat it as a power-tool to graduate into, and keep grading what it produces against the Concept 9 rubric; a template does not exempt the output from review.

Where does this lead? Specs in Markdown are the seed of spec-driven development (Part 1 of the book). HTML outputs are the seed of the verification habits in the Agentic Coding Crash Course. And the cross-surface fluency, the same motion in chat, terminal, and desktop, is what the Problem-Solving Crash Course assumes on page one.

You can now say precisely what you mean, and demand output worth reading. The appendix puts the whole motion in one place if you want to see it end to end. The next question is what to point that precision at, and that is where How to Think in the AI Era and the Problem-Solving Crash Course pick up.

---

Appendix: One spec, the HTML it became

The two-minute proof at the top conjured a page from one casual paragraph. This appendix is the grown-up version of the same motion: the real spec from Concept 1, and the actual page it produced. Read the spec. Do not read the HTML line by line; the point of this section is that long HTML is for the browser, not the eye. The contrast between the two blocks below is the lesson.

The input: a Markdown spec

# Al-Noor Tuition Academy Landing Page Spec

## Goal

A one-page site parents open on their phones to check courses,
timings, fees, and how to reach us.

## Requirements

- Mobile-first; most visitors are on phones
- Course table: course, days, time, monthly fee
- Contact: tappable phone, WhatsApp link, location
- Eid holiday banner at the very top

## Hard constraints

- Single self-contained HTML file, no external fonts or libraries
- Must stay light enough to open on slow mobile data
- Open Graph tags so the WhatsApp/Facebook link preview looks designed

## Out of scope

- Online payments
- Student login

The output: the HTML it produced

This file is about 6 KB, loads with zero network requests after the page itself, reads cleanly on a phone, and carries the Open Graph tags that shape its link preview when shared. Every one of those properties was a line in the spec above; the spec is why the output is good, not luck. (One honest gap: a preview image needs og:image pointing at a hosted picture, which a single self-contained file does not have until you publish it somewhere. Add the tag once the page has a home.)

The block below is long on purpose, and you are meant to scroll past it. That scroll is itself the lesson: it is the same reason you would not read a long file in a chat window. The reading happens in the browser, not here.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Al-Noor Tuition Academy</title>

    <!-- Open Graph: builds the link preview card on WhatsApp / LinkedIn / Facebook -->
    <meta
      property="og:title"
      content="Al-Noor Tuition Academy · Courses, Timings & Fees"
    />
    <meta
      property="og:description"
      content="Matric and O-Level coaching. See current courses, class timings, monthly fees, and how to reach us."
    />
    <meta property="og:type" content="website" />

    <style>
      :root {
        --ink: #27313b;
        --muted: #5c6b78;
        --paper: #fbf7f1;
        --card: #ffffff;
        --line: #e7ded2;
        --accent: #c1633a;
        --accent-soft: #f4e4d8;
      }
      * {
        box-sizing: border-box;
      }
      body {
        margin: 0;
        background: var(--paper);
        color: var(--ink);
        font-family:
          -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        line-height: 1.5;
        -webkit-text-size-adjust: 100%;
      }
      .wrap {
        max-width: 680px;
        margin: 0 auto;
        padding: 0 18px 48px;
      }
      .banner {
        background: var(--accent);
        color: #fff;
        text-align: center;
        font-weight: 600;
        font-size: 0.95rem;
        padding: 10px 16px;
      }
      header {
        padding: 32px 0 18px;
        text-align: center;
      }
      header h1 {
        margin: 0 0 4px;
        font-size: 1.7rem;
        letter-spacing: -0.01em;
      }
      header p {
        margin: 0;
        color: var(--muted);
        font-size: 1rem;
      }
      h2 {
        font-size: 1.05rem;
        text-transform: uppercase;
        letter-spacing: 0.06em;
        color: var(--accent);
        margin: 34px 0 12px;
      }
      table {
        width: 100%;
        border-collapse: collapse;
        background: var(--card);
        border: 1px solid var(--line);
        border-radius: 12px;
        overflow: hidden;
      }
      th,
      td {
        text-align: left;
        padding: 12px 14px;
        font-size: 0.95rem;
      }
      thead th {
        background: var(--accent-soft);
        color: var(--ink);
        font-size: 0.8rem;
        text-transform: uppercase;
        letter-spacing: 0.05em;
      }
      tbody tr + tr td {
        border-top: 1px solid var(--line);
      }
      td.fee {
        font-weight: 600;
        white-space: nowrap;
      }
      .contact {
        display: grid;
        gap: 10px;
        margin-top: 6px;
      }
      .contact a {
        display: flex;
        align-items: center;
        gap: 12px;
        text-decoration: none;
        background: var(--card);
        border: 1px solid var(--line);
        border-radius: 12px;
        padding: 14px 16px;
        color: var(--ink);
        font-weight: 500;
      }
      .contact a:active {
        background: var(--accent-soft);
      }
      .contact svg {
        flex: 0 0 22px;
      }
      footer {
        margin-top: 36px;
        text-align: center;
        color: var(--muted);
        font-size: 0.85rem;
      }
      @media (min-width: 560px) {
        header h1 {
          font-size: 2rem;
        }
      }
    </style>
  </head>
  <body>
    <div class="banner">
      Eid holidays: the academy is closed 6–9 June. Classes resume 10 June.
    </div>

    <div class="wrap">
      <header>
        <h1>Al-Noor Tuition Academy</h1>
        <p>Matric &amp; O-Level coaching · Gulberg, Lahore</p>
      </header>

      <h2>Courses &amp; Timings</h2>
      <table>
        <thead>
          <tr>
            <th>Course</th>
            <th>Days</th>
            <th>Time</th>
            <th>Fee / month</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Matric Mathematics</td>
            <td>Mon–Wed</td>
            <td>4:00–5:30 pm</td>
            <td class="fee">PKR 3,500</td>
          </tr>
          <tr>
            <td>Matric Physics</td>
            <td>Tue–Thu</td>
            <td>5:30–7:00 pm</td>
            <td class="fee">PKR 3,500</td>
          </tr>
          <tr>
            <td>O-Level Chemistry</td>
            <td>Mon–Wed</td>
            <td>6:00–7:30 pm</td>
            <td class="fee">PKR 4,000</td>
          </tr>
          <tr>
            <td>O-Level English</td>
            <td>Fri–Sat</td>
            <td>10:00–11:30 am</td>
            <td class="fee">PKR 4,000</td>
          </tr>
        </tbody>
      </table>

      <h2>Reach Us</h2>
      <div class="contact">
        <a href="tel:+923001234567">
          <svg
            viewBox="0 0 24 24"
            fill="none"
            stroke="#c1633a"
            stroke-width="2"
            stroke-linecap="round"
          >
            <path
              d="M22 16.9v3a2 2 0 0 1-2.2 2 19.8 19.8 0 0 1-8.6-3.1 19.5 19.5 0 0 1-6-6 19.8 19.8 0 0 1-3.1-8.6A2 2 0 0 1 4.1 2h3a2 2 0 0 1 2 1.7c.1.9.4 1.8.7 2.7a2 2 0 0 1-.5 2.1L8.1 9.9a16 16 0 0 0 6 6l1.4-1.2a2 2 0 0 1 2.1-.5c.9.3 1.8.6 2.7.7a2 2 0 0 1 1.7 2z"
            />
          </svg>
          Call: 0300 123 4567
        </a>
        <a href="https://wa.me/923001234567">
          <svg viewBox="0 0 24 24" fill="#c1633a">
            <path
              d="M12 2a10 10 0 0 0-8.6 15l-1.3 4.7 4.8-1.3A10 10 0 1 0 12 2zm0 18a8 8 0 0 1-4.1-1.1l-.3-.2-2.8.7.8-2.8-.2-.3A8 8 0 1 1 12 20zm4.5-5.9c-.2-.1-1.4-.7-1.6-.8s-.4-.1-.6.1-.6.8-.8 1-.3.2-.5.1a6.5 6.5 0 0 1-3.2-2.8c-.2-.4.2-.4.6-1.2a.5.5 0 0 0 0-.5l-.8-1.9c-.2-.5-.4-.4-.6-.4h-.5a1 1 0 0 0-.7.3 3 3 0 0 0-.9 2.2c0 1.3 1 2.6 1.1 2.8s1.9 2.9 4.6 4a5 5 0 0 0 2.3.5c.7-.1 1.4-.6 1.6-1.1s.2-1 .1-1.1z"
            />
          </svg>
          WhatsApp: 0300 123 4567
        </a>
        <a href="https://maps.google.com/?q=Gulberg+Lahore">
          <svg
            viewBox="0 0 24 24"
            fill="none"
            stroke="#c1633a"
            stroke-width="2"
            stroke-linecap="round"
          >
            <path d="M21 10c0 6-9 12-9 12s-9-6-9-12a9 9 0 0 1 18 0z" />
            <circle cx="12" cy="10" r="3" />
          </svg>
          Main Boulevard, Gulberg (view on map)
        </a>
      </div>

      <footer>Open for admissions · New batches every month</footer>
    </div>
  </body>
</html>

Now do the three things the course taught

1. Open it. The fastest way, no computer needed: paste the whole HTML block into Claude.ai and say "turn this exact HTML into an artifact; change nothing," then publish it and open the link on your phone. (On a computer, you can instead save the block as tuition.html and double-click it.) Notice you read it; you did not skim it. That is Concept 8.
2. Change it by prompting, not typing. Tell your agent: "Add a fifth course row for FSc Biology, Sat–Sun 2:00–3:30 pm, PKR 4,500, and make the holiday banner dismissible." You never touched a tag. That is Concept 9.
3. Publish it. Push it through any rung of the publishing ladder (Concept 12), then share the link in WhatsApp and watch the preview card render. That is Concepts 11 and 12 closing the loop.

That is the entire crash course in one artifact: a precise Markdown spec went in, readable HTML came out, you edited it by prompting, and you shipped it.

---

Flashcards Study Aid

---

Test Your Understanding

Checking access...