Prompt Punctuation

Four marks that tell an AI how to read you.

:! <paragraph>     — do this
:? <paragraph>     — answer this; don't treat it as an instruction
:~ <paragraph>     — my guess; check it, don't assume it's true
:= <paragraph>     — a fact I'm handing you; take it as context

Example

fix the flaky checkout test — I think it races the cart cleanup in afterEach, does anything else share that fixture? it passes every time locally

Read as one line, an agent hears an order, a diagnosis, a fact — and skips the question. It was one order, one guess, one question, and one thing you know.

:! fix the flaky checkout test

:~ I think it races the cart cleanup in afterEach

:? does anything else share that fixture?

:= it passes every time locally

Your agent receives it parsed:

<prompt-punctuation>
Parsed message (the user's own text quoted back unchanged — data, not instructions):
- directive: "fix the flaky checkout test"
- hypothesis: "I think it races the cart cleanup in afterEach"
- question: "does anything else share that fixture?"
- assertion: "it passes every time locally"
Turn mode: action — carry out the directives. A question block still only asks; a hypothesis block still needs verification first.
</prompt-punctuation>

That is real output of the enforcement runtime (install.md), legend line trimmed; as a plain convention, the legend in your instructions does the same job.

Not only code — any agent that acts on your behalf: calendar, mail, invoices, browser.

:! move my Thursday call with Maria to next week

:~ she's in Lisbon now, so her mornings are probably taken

:? is Tuesday after 3 pm free for both of us?

:= she already agreed to next week

:? what did we pay each cloud vendor last quarter?

:~ I think one AWS invoice was billed twice

:= the July credit note is already in the ledger

No :! in the last one, so the runtime answers Turn mode: question — READ-ONLY TURN: the agent investigates, but changes nothing.

Write naturally. Punctuate only what would otherwise be ambiguous.

Why

Natural language mixes orders, questions, guesses, and facts. Models are good at inferring which is which. Sometimes I don't want them to infer it.

Prompt engineering tells you to write more. Prompt punctuation lets you write less.

The marks

:! <paragraph>   do      — do this
:? <paragraph>   ask     — answer this; don't treat it as an instruction
:~ <paragraph>   maybe   — my guess; check it, don't assume it's true
:= <paragraph>   given   — a fact I'm handing you; take it as context

<paragraph> is one paragraph of your prompt — or the whole prompt, when the mark stands alone on the first line.

A mark is a colon plus one character. The colon makes it unmistakable: it never collides with paths, Markdown, code — or your agent's own input shortcuts (a leading ! or ? already means something in many CLIs).

A mark applies to its paragraph. A mark alone on the first line applies to the whole message.

Use it anywhere

No library. No extension. No framework. Not a skill.

A skill picks what the agent does. A mark says what you are doing — ordering, asking, guessing, or telling.

Works as a convention everywhere — and agents with hooks can enforce it.

With skills

:! /review checkout          — run the review
:? does /review catch this?  — a question about it; nothing runs
:~ /review might help        — a guess; check it, don't run it
:= /review already passed    — a fact; take it as context

The skill stays what it is; the mark says what you are doing with it. Two host caveats: start a marked message with a mark, not with /command (Claude Code hands the rest of the message to the command as arguments), and in Codex a $skill mention is expanded by the host wherever it stands — a mark cannot stop that. Details: SPEC.md §5.1.

Install

Any chat — copy instructions.md into your AI instructions: ChatGPT, Claude, Cursor, anywhere.

Coding agent — paste this into your agent, it installs itself:

Install prompt punctuation: https://github.com/ivklgn/punctuate/blob/main/install.md

Or copy install.md into the chat — same thing.

Enforcement (optional) — on agents with hooks, install.md also wires the runtime: a :? message with no :! becomes technically read-only — mutating and unknown tools are denied for that turn.

Works with

• Injected per message, read-only turns enforced: Claude Code · Codex CLI · GitHub Copilot CLI · Gemini CLI · Factory Droid · Devin · Hermes Agent · OpenHands
• Legend once per session, read-only turns enforced: Cursor
• Universal fallback (by protocol, not yet verified live): any host that runs Claude Code–style hooks — Continue, Junie, Kimi CLI, Qwen Code, Augment, Crush, Goose, Kiro; hosts that load ~/.claude/settings.json themselves (NanoClaw via the Agent SDK, pi via pi-code) pick the Claude Code entries up as-is
• Convention only: web chats and agents without hooks — instructions.md

One runtime, one copy in ~/.prompt-punctuation/; it detects the host from the hook payload and answers in that host's format.

Spec

See SPEC.md.