The assistant

The editor has an assistant: an AI that helps you write and improve an instruction. Open it with the Assistant button at the right of the toolbar. You need to be signed in.

Ask by typing

Say what you want in plain words — “add rules about refunds”, “make the introduction shorter”, “what is wrong with this instruction?”. The assistant reads the instruction, answers, and makes the changes you asked for.

You can also ask from the text itself. Select some words and the menu beside them has an Assistant part: a few ready requests (“Make it clearer”, “Make it a rule”) and a field for your own. A rule's or a section's menu has Ask the assistant about this…, and each problem in the Problems list has a button that asks the assistant to fix that line. Each of these opens the panel with your request in it, about what you selected.

Ask by talking

Press Talk and allow the microphone. Speak as you would to a colleague; the assistant answers aloud and makes the changes while you talk. Mute closes the microphone, End ends the conversation. Hold the Talk button to keep the microphone open only while you hold it. A conversation ends by itself after 30 minutes; you can start another.

Its changes are suggestions

  • By default the assistant suggests. Each change shows in the text, marked as the assistant's, and nothing is final until you accept it. Accept all and Reject all are in the panel.
  • If you can publish the instruction, you can switch to Edit: the assistant then writes into your draft. A copy of the draft is kept first, and Undo the assistant's last turn puts it back.
  • The assistant never publishes, shares or deletes anything. When you are ready, you press Publish.

What your plan includes

Every plan includes the assistant. Community includes a one-time allowance for each person; paid plans include an allowance that renews each month and is shared by the workspace. Typing uses very little of it; talking uses it by the minute. The panel shows how much is left, and says when it is used up. See Plans.

What is sent, and what is kept

  • To answer, your messages and the text of the instruction you have open are sent to OpenAI, which processes them in the United States. In a spoken conversation your voice goes to OpenAI too, straight from your browser.
  • OpenAI does not use this to train its models. It may keep it for up to 30 days to watch for abuse.
  • instruction.md keeps no conversation and no audio. We record only that the assistant was used, when, and how much, to count your allowance. The conversation in the panel is stored in your browser; New conversation clears it.
  • Your account is never named to OpenAI.

Privacy has the whole picture: what we keep, what stays in your browser, and how to delete it.

Turning it off for a workspace

A workspace's admins can turn the assistant off in Settings ▸ Security. Nobody can then use it on that workspace's instructions.

Looking things up

instruction.md can connect the assistant to knowledge sources, such as product and policy facts. When your request depends on a fact the assistant does not have, it looks it up there first, and says so when it could not. This works when you type and when you talk. What a source returns is sent to OpenAI with the rest of the turn.

Start from a description

On the Instructions page, describe the agent you need in a sentence and choose Write it. A new instruction opens and the assistant writes it while you watch, from its title to its rules. It is a draft: read it, change what you like, and publish when it is right.

Your own AI can work here too

If you already use an AI app, it can work on your instructions with your own subscription instead: connect it to instruction.md.

In Claude and ChatGPT, ask for what you want (“write an instruction for our support agent”, “tighten the rules of my refunds instruction”). Where the app shows connected apps' views, the instruction appears in the conversation: its draft as the site draws it, each change the AI suggests with Accept and Reject, any problems found, and a few ready requests. It follows the draft as the AI works, and Open in the editor takes you to the full editor. You can also type in the text yourself (Edit), add and answer comments, and Publish: it asks what changed, shows what will happen, and releases only when you confirm. The AI never publishes for you.

In a browser whose AI can use a page's tools (Chrome's, today), it can work in the editor directly, as you, with what you are allowed to do:

  • read the open instruction, check it for problems, and suggest changes or, where you are a maintainer, edit the draft;
  • list, accept and reject suggestions; read, write and resolve comments;
  • list your instructions and folders; open, create, rename, copy and move them;
  • read an earlier version, and put one back in the draft;
  • see who an instruction is shared with, its read links, and your workspace's people and settings;
  • run the editor's own commands.

Anything that leaves the draft is put to you in the editor first, and happens only if you agree: publishing a version or restoring an earlier one, sharing with someone or changing who can read it, making or revoking a read link, moving an instruction or a folder to the trash, archiving. None of this uses your assistant allowance.