Esta página aún no está traducida.

Check your instruction before you publish

This page is for anyone who writes instructions. You will learn what the editor checks as you write, which findings stop you from publishing, and how to fix each one, often with one click.

The editor reads your instruction the way an agent's app will. It checks every change as you type, and says in plain words what an agent would get wrong.

Before you start

  • Who can do this: anyone who can open the instruction sees its problems. A Maintainer fixes them directly and publishes. A Contributor's fixes become suggestions.
  • What you need: an instruction open in the editor. Checking works without an account; publishing needs one.

Problems, things to check and hints

The editor sorts what it finds into three kinds:

Kind What it means Does it stop Publish?
Problem The instruction can't be read as you meant it, so publishing it would be refused Yes
Thing to check It can be published, but part of it won't reach the agent the way you expect No
Hint Advice that would make it clearer, such as turning a sentence into a rule No

The status bar says where you stand:

  • Ready to publish — no problems
  • Ready to publish · 2 things to check
  • 1 problem to fix before you publish

While there is a problem, Publish is greyed out and its tip says why, such as "1 problem to fix before you publish". If a problem turns up while the publish sheet is open, the sheet says "1 problem to fix first" with a Show button that takes you to it, and its own Publish button says Fix the problems first.

When suggestions are waiting, the editor checks the text it would publish without them, because suggestions aren't published until someone accepts them. The message then ends with "(without the suggestions)".

Find and fix a problem

  1. Open the list

    Click the problems count in the status bar. The list shows each problem first, then each thing to check, in plain words.

  2. Go to it

    Click a row to put the caret on its line. You can also press F8 for the next problem and Shift+F8 for the previous one.

  3. Fix it

    Many rows have a fix button, such as Make it a rule or Close it. Click it, and the editor changes the text for you and says "Fixed:" with what it did. One press of ⌘Z (Ctrl+Z on Windows) undoes a fix.

The problems list, with its one-click fixes.

Quick fix from the keyboard

With the caret on a line that has a problem, press ⌘. (Ctrl+. on Windows). A list opens with every fix for that line. On a line without one, the editor says "No problem on this line — F8 goes to the next one".

Hints

Advice is in Hints in the status bar. Each hint takes you to its line and can have a fix button too. When there is nothing to suggest, it says so.

Hints also has the switch Suggest as you type — rules, blocks, parameters, keys, which opens lists at the caret while you write.

Common problems in plain words

These are the messages you are most likely to see, and what to do about each.

What the editor says What to do
"This sentence reads like a rule but is written as ordinary text. Make it a rule so the agent receives it as one." A rule word such as must or never starts the line in lower case, before a colon. Choose Make it a rule
"This sentence could be a rule. Make it one so the agent receives it as a rule." (a hint) A sentence starts with "You must" or "The agent should". Choose Make it a rule to start it with the rule word in capitals
"Two things in this instruction have the same name. Rename one." Two rules or blocks share a name. Choose Rename it … to give the second one a new name
"The value “…” is used but never set up, so the agent sees it as written." Choose Set up “…”. See Mention people, tools and other instructions
"A code block is never closed, so everything after it is treated as code." Choose Close it
"A block is never closed, so everything after it belongs to it." Choose Close it
"A reason follows no rule, so it stays ordinary text. Put it right after the rule it explains." Move the line that starts with BECAUSE to right under its rule
"This rule already has a reason. Give it only one." Join the two reasons, or delete one
"A mention points at something that isn't in this instruction." Click the mention in Preview and pick it again, or remove it
"The tool “…” is blocked in your organization, so the agent won't use it. Pick another tool, or ask an admin to allow it." Pick another tool, or ask an admin
"“…” isn't one of your organization's approved integrations, so the agent won't use it." Use an approved integration, or ask an admin to add it
"The title in Details differs from the heading" The name is the first heading. Choose Use the heading, or Remove title: to drop the title from Details
"Part of this is written in an older format. Update it to the current one." Choose the fix to convert the whole instruction
"The instruction's details (its title, description and settings) can't be read." Open Details at the top and look for a missing colon or quote. ⌘Z undoes your last change
"Part of this instruction can't be read as written." Look at the line for a stray bracket or colon. Developer mode shows the exact message

When a fix button would show some code, it says Fix it instead. The Troubleshooting page lists more messages from across instruction.md.

A draft with three problems

This draft has one problem and two things to check:

Draft
# Refunds

You handle refund requests for Acme.

must: check the order number before you answer.

MUST[verify]: verify the customer's identity before you discuss an order.

NEVER[verify]: share one customer's details with another.

MUST: refund up to ${limit} euros without asking anyone.
  • The line that starts with "must:" is a thing to check. Make it a rule writes "MUST:".
  • Two rules are named "verify". This is a problem, so Publish stays greyed out. The fix Rename it verify-2 renames the second one; a clearer name such as "no-sharing" is better.
  • ${limit} is never set up, so the agent would read it as written. Set up “limit” adds it to Details. Then give it a type and a default.

Once fixed, the status bar says Ready to publish — no problems:

Fixed
---
spec: "1"
parameters:
  limit:
    type: number
    default: 200
    description: The largest refund the agent gives on its own
---
# Refunds

You handle refund requests for Acme.

MUST: check the order number before you answer.

MUST[verify]: verify the customer's identity before you discuss an order.

NEVER[no-sharing]: share one customer's details with another.

MUST: refund up to ${limit} euros without asking anyone.

Ask the assistant to fix it

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

When the editor's assistant is on for you, every problem in the list has a ✦ button, Ask the assistant to fix it. The quick-fix list has ✦ Ask the assistant to fix it too. The editor selects the problem's line and asks the assistant to fix it there. By default its changes arrive as suggestions you accept or reject. See The assistant.

What an agent will read

The agent receives the instruction without its Details, its notes and its comments. View ▸ Contents opens On this page, which lists the sections and counts the rules, guardrails and figures at its top.

With Developer mode on, the status bar also counts what the agent receives: the number of rules and "words to the agent". Click the count to see how many rules, guardrails, examples and figures there are, and go to the next of each.

The shape of a good instruction, shown while it is new.

A new instruction with a title and only a few words shows the shape of a good one at the end of Preview. It starts with "An agent will read · 3 words so far" and has four cards:

Card What it adds
What it's for A short paragraph the agent reads first: who it serves, and what good looks like
Rules MUST · SHOULD · NEVER — the lines it is held to. Or type /must at the start of a line
A guardrail The one boundary nothing in a conversation overrides. Or type /guardrail
An example A reply that shows the way. Rules land better with one. Or type /example

Click a card to add that part. Each card folds away once the instruction has that part. The cards appear only while the instruction has a title, no rules and fewer than 30 words. They go away once every card is done, or once the text reaches 150 words.

Developer mode

With Developer mode on, the list shows each problem's line number, the exact message and its code, and the fixes' own words. The status bar says, for example, "Valid · spec 1 — no problems", and shows the count of words to the agent. Turn it on from the command palette with Turn developer mode on, and off with Turn developer mode off.

Check it worked

  • The status bar says Ready to publish — no problems, or lists only things to check you have decided to keep.
  • Publish is no longer greyed out.
  • On this page counts the rules, guardrails and figures you expect the agent to read.

Undo or stop

  • Press ⌘Z (Ctrl+Z on Windows) to undo a fix. Each fix is one step.
  • Things to check and hints never stop you. You can publish with them.

If it doesn't work

What you see What to do
Publish is greyed out with "1 problem to fix before you publish" Click the count in the status bar and fix the problem it lists first
Publish is greyed out with no problems listed Point at Publish to read why. A Reader or a Contributor can't publish. "The draft is live v3 already — nothing to publish" means nothing changed since the last version. See Publish, schedule and write a version message
A problem has no fix button Go to its line and change it yourself, or use Ask the assistant to fix it
The status bar says Checking… for a long time Very large instructions take longer. Wait a moment, then reload the page if it doesn't change
The same problem comes back after a fix Another part of the text has the same mistake. Press F8 to go to the next one

Questions

Why is Publish greyed out?

The instruction has at least one problem, or you can't publish it. Click the problems count in the status bar to see what to fix first. Things to check and hints never stop you. See Problems, things to check and hints.

Can I publish with warnings?

Yes. Things to check and hints don't stop Publish. Read each one first: it usually means part of the instruction won't reach the agent the way you expect.

What does Make it a rule do?

It writes the rule word in capitals at the start of the line, such as MUST:, so the agent receives the line as a rule rather than as ordinary text. ⌘Z undoes it.

Which parts of my instruction does the agent not receive?

Details, the notes at the end and comments. Everything else is what the agent receives. See What an agent will read.

For developers: Diagnostics and fixes lists every code, its severity and the fix it offers.

Last checked against the product:

Was this page helpful? Report a problem