لم تُترجم هذه الصفحة بعد.

The assistant

The editor has an assistant: an AI that helps you write and improve an instruction. This page shows how to ask it by typing or by talking, what it may change, what it costs, and what is sent where.

The assistant panel, with its changes waiting as suggestions.

Before you start

  • Account: you need to be signed in. Without an account the panel shows Sign in to use the assistant.
  • Role: anyone who can open an instruction can ask about it. What the assistant may change depends on your role (see What your role lets it do).
  • Plan: every plan includes some use of the assistant (see What your plan includes).
  • Your organization: its owners and admins can turn the assistant off. Then nobody in it can use it.

Open the assistant

Press Assistant at the right of the bar above the text, or press Ctrl+Shift+Space (⌘⇧Space on a Mac). The panel opens beside the text, with a box at its foot.

The first time, the panel says what the assistant is and that your messages go to OpenAI. Press the ✕ beside the note (Got it) to hide it.

If the button is missing

The Assistant button isn't shown, or the panel can't take a message, when:

  • the service you use instruction.md on has no assistant. Then the button isn't there at all;

  • the instruction is sealed. A sealed instruction is encrypted on its people's devices, and the assistant runs on instruction.md's servers, so it can't read it. Sealed workspaces are in beta, not yet independently reviewed;

  • you are reading a preview, not editing;

  • the panel says The assistant is turned off for this organization. Ask an owner or admin of your organization;

  • the panel says The assistant isn't available here. It can't be used here at the moment. Try again later.

Ask by typing

Type what you want in plain words in the box, then press Send or Enter. Shift+Enter starts a new line. For example:

  • "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. While it works, the panel says what it is doing, such as Reading the instruction… or Writing a change…. Press Stop to stop it.

Each change it makes shows as a card in the conversation. Press Show on a card to see the change in the text.

Start from a suggestion

When the conversation is empty, the panel offers a few requests to start with. They depend on the instruction:

When You see
The instruction is empty Describe your agent and I'll draft it
Some words are selected Tighten, Turn into rules and Add an example
The editor found problems Fix 2 problems (with the real count)
No version is published yet Review it before you publish
You can only read it Explain this instruction

Ask about part of the text

You can also ask from the text itself. Each of these opens the panel with your request in it:

  • Selected words. Select some words. The menu beside them has an Assistant part with ready requests, such as Make it clearer and Make it a rule, and Ask the assistant… for your own request.
  • A rule, a guardrail, an example or a section. Its menu has Ask the assistant about this rule… (or this guardrail, example or section).
  • A problem. Each problem in Problems has ✦ Ask the assistant to fix it.
  • The command palette. Type your request in the command palette (Ctrl+K, or ⌘K on a Mac) and choose ✦ Ask the assistant: "…".
Asking the assistant about selected words.

The assistant also knows the instruction.md language. It looks things up in the instruction.md documentation when it needs to (Looking in the specification…).

Ask by talking

You can talk to the assistant as you would to a colleague. It answers aloud and makes the changes while you talk.

  1. Start a conversation

    Press Talk beside Send. The first time, your browser asks to use the microphone: allow it. The panel shows Connecting…, then Listening….

  2. Speak

    Say what you want. While the assistant answers, the panel shows Assistant speaking. While it changes the text, it shows Working…. What you both say is added to the conversation, marked Spoken.

  3. Mute or end it

    The microphone button mutes and unmutes you. End ends the conversation.

The Talk controls during a conversation.

To talk only while you hold a button, hold Talk instead of pressing it. You can also hold Space while the box is empty. The microphone is open only while you hold. Press once to keep it open.

You can keep typing in the box during a conversation. You can also start or end one from the command palette with Talk to the assistant.

A conversation ends on its own:

  • after 30 minutes. Start another to carry on: it picks up from where you were;
  • when you open another instruction or leave the page;
  • when the allowance is used up.

Talking needs a microphone and a browser that can hold a voice call; most current browsers can. Talk isn't shown when your browser can't, or when too little of the allowance is left for a call.

What your role lets it do

The assistant works with your role on the instruction. It can never do more than you can.

Your role The box says What the assistant does
Reader Explains only It answers questions. It changes nothing.
Contributor Suggests changes Its changes are suggestions. A maintainer accepts or rejects them.
Maintainer or Admin Suggest or Edit You choose: suggestions, or changes made in the draft.

People and roles explains each role.

Its changes are suggestions

By default the assistant suggests. Each change shows in the text as a suggestion, marked as the assistant's. Nothing is final until it is accepted.

  • Accept all accepts every suggestion of that turn. Only someone who can accept suggestions sees it: a Maintainer or an Admin.
  • Reject all rejects every suggestion of that turn.
  • You can also accept or reject one suggestion at a time in the text, as with anyone's suggestions.

A contributor's assistant suggestions wait for a maintainer, like the contributor's own. Suggest changes and review them shows how they are reviewed.

Let it edit the draft

If you are a Maintainer or an Admin, switch the box from Suggest to Edit. The assistant then writes into the draft directly. Before a turn changes the draft, the editor keeps a copy of it in History, named Before the assistant's edit.

After a turn with changes, Undo the assistant's last turn puts the draft back as it was before that turn. To go back further, open History.

It never publishes

The assistant never publishes, shares or deletes anything. When you ask it to publish, it gets the draft ready: it says what the next version would be and opens Publish for you. You press the button.

While the assistant works, the other people who have the instruction open see The assistant is working on this.

Start from a description

On the Instructions page, type a sentence in Describe the agent you need. For example: "a support agent for a bike shop that never promises refunds". Press 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.

Writing an instruction from a description.

Start from a template, a prompt or a file shows the other ways to begin.

What your plan includes

Every plan includes the assistant. Its use is counted in credits:

Plans Community 1,000 · Pro 1,500 · Team 2,500 · Enterprise unlimited

  • On Community, the credits are your own, given once. When they are used up, the panel says You've used the assistant included with Community. Upgrade to keep using it.
  • On a paid plan, the credits are your organization's and renew each month. On a plan paid by the seat, they grow with the number of members, and everyone shares them.

Typing uses very little. Talking uses credits by the minute, much faster than typing.

The panel shows how much is left. On Community you always see the bar, such as 63% of your free allowance left. On a paid plan it appears when less than a fifth is left. A plan with no limit shows no bar. When the month's credits are used up, the panel says This month's assistant allowance is used. It renews on …. See plans compares the plans.

instruction.md also sets a limit for all its users together each day. When it is reached, the panel says The assistant is resting for today. Try again tomorrow.

Plans and billing has the rest of what each plan includes.

What is sent, and what is kept

What the assistant sends, and what is kept where.
  • What is sent. To answer, your messages and the text of the instruction you have open are sent to OpenAI. So is anything the assistant looks up for you. In a spoken conversation your voice goes to OpenAI too, straight from your browser.
  • Where. OpenAI processes it in the United States.
  • What OpenAI does with it. It answers. It does not use it to train its models. It may keep it for up to 30 days to watch for abuse.
  • Who it says you are. Your name and email are never sent to OpenAI. It gets a coded identifier that only tells one person's requests from another's.
  • What instruction.md keeps. No conversation and no audio. We record only that the assistant was used, when, and how much, to count your allowance.
  • What stays in your browser. The conversation in the panel is stored in this browser, one for each instruction. New conversation clears it.
  • On agents' cards. When the assistant explains a question or a request from one of your agents, that explanation is kept on the card. The next person who opens the card reads it without using their allowance (see Answer your agents).

Don't put anything you would not want processed outside your country in a message, or in an instruction you ask the assistant to work on. That includes other people's personal details, passwords and keys.

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

Turn it off for your organization

The assistant is on or off for a whole organization. It is never off for only one workspace.

  1. Open the security settings

    Open Settings ▸ Security. You need to be an owner or admin of the organization.

  2. Switch it off

    Under Assistant, switch off The assistant in the editor. The editor says The assistant is off for this organization.

From then on, nobody can use the assistant on the organization's instructions. Their panel says The assistant is turned off for this organization. Switch it on again the same way. Security settings lists the organization's other switches.

Looking things up

The assistant can be connected to knowledge sources, such as facts about a product or a company's policies. The people who run the service set them up. When your request depends on a fact the assistant doesn't 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.

instruction.md's own service has no knowledge sources connected at the moment.

Your own AI can work here too

If you already pay for an AI app, such as Claude or ChatGPT, it can work on your instructions with your own subscription instead. Your browser's built-in AI can work in the editor too. None of this uses your assistant allowance. Use your own AI to write shows how.

If it doesn't work

What you see What to do
You're signed out. Sign in again to use the assistant. Press Sign in, then send your message again.
The assistant is busy. Try again in a moment. Too many requests came at once. Press Try again after a few seconds.
This conversation has grown too long. Start a new one to carry on. Press New conversation. The instruction is not affected.
The microphone is blocked. Allow it for this site in your browser's settings, then press Talk again. Allow the microphone for instruction.md in your browser's site settings.
No microphone could be used. Connect one, then press Talk again. Connect a microphone, or choose another one in your computer's sound settings.
The conversation couldn't be set up from this network. Try again, or try another network. Some company networks block voice calls. Try another network, or type instead.
The assistant is in as many conversations as it can hold right now: try again in a few minutes. All voice calls are taken. Try again in a few minutes, or type instead.
This browser can't hold a voice conversation. Open the editor in an up-to-date browser, or type instead.
The checkpoint from before that turn isn't kept on this device. History has the others. Open History and restore an earlier checkpoint from there.

Still stuck? See Troubleshooting, or ask us.

Questions

Does the assistant publish my changes?

No. It can get a version ready and open Publish, but only you can press it. It never shares or deletes anything either.

Can the assistant see my other instructions?

It reads the instruction you have open, and what you select in it. It can also look up the names it may mention, such as people, tools and skills.

Does using the assistant cost extra?

No. Every plan includes some use of it, counted in credits. When they are used up, the assistant stops until they renew, or until you upgrade on Community. See What your plan includes.

Is my conversation stored?

Only in your browser. instruction.md keeps no conversation and no audio, only how much you used. See What is sent, and what is kept.

Can I use the assistant on a sealed instruction?

No. A sealed instruction is encrypted on its people's devices, and the assistant runs on instruction.md's servers. It can't read the text, so the button isn't shown. Sealed workspaces are in beta, not yet independently reviewed.

Last checked against the product:

Was this page helpful? Report a problem