Cette page n’est pas encore traduite.

Mention people, tools and other instructions

This page is for anyone who writes instructions. You will learn to mention a person, a tool or another part of your instruction so the agent knows exactly which one you mean, and to use parameters: values that can change from one agent to the next.

A mention is more than a name. "Ask the finance lead" leaves the agent to guess who that is. A mention points at one person, one tool or one block, and the agent receives both the name and what it points at.

Parameters, from typing $ to a new default.

Before you start

  • Who can do this: a Maintainer changes the text directly. A Contributor's changes become suggestions that a Maintainer accepts. A Reader can't change anything, so Preview shows no controls.
  • What you need: an instruction open in the editor. You can write mentions without an account, but the lists then hold only what the instruction already names. Signed in, they also hold your organization's people, agents and integrations.

What each key offers

Type one of these keys in your text, after a space or at the start of a line. A list opens at the caret. Keep typing to narrow it, use ↑ and ↓ to move, and press Enter or Tab to take a row.

Key What it lists What you get
@ People and agents: your organization's members, the people of its directories, its agents, and anyone the instruction already names A mention of that person or agent
& Capabilities: MCP servers, tools, skills and APIs your organization has added, and those the instruction declares. An MCP server is a service that gives an agent tools A mention of that capability
# The rules and blocks of this instruction that have a name. Other instructions aren't listed here A mention of that rule or block
$ The instruction's parameters, and Declare … for a name it doesn't have yet A parameter, written as ${name}

"#" and "$" open their list once you type a letter after them, so a heading ("# ") and money ("$5") stay plain text. The list doesn't open inside code, inside a link's address, or inside a mention you already wrote.

There are other ways to open the same lists:

  • Select some words and choose Person or agent, Instruction, block or tag, Parameter or Capability — an MCP server, a skill in the menu that appears. The words you selected become the search.
  • The command palette has Insert a reference to a person or an agent, Insert a reference to a capability — an MCP server, a skill, Insert a reference to an instruction or a block and Insert a parameter. These open the list even when it would stay closed, so "#" and "$" show everything before you type a letter.

When a list opened this way has nothing to show, the editor says Nothing to point at here yet. While you type, an empty list stays closed.

Mention someone or something

  1. Type the key

    In Content, type @ where the person's name goes. The list opens with people and agents, each with their job title, team or role.

  2. Narrow the list

    Type the first letters of the name. People and things that start with what you typed come first.

  3. Take a row

    Press Enter, or click the row. The mention takes the place of what you typed. In Preview it shows as a chip: a small rounded label, with the person's picture where your organization has one.

When you mention an MCP server, a skill or a tool from your organization's integrations for the first time, the editor also adds its declaration, a short block under the paragraph. That block tells the agent where the capability is. Leave it in place: other mentions of the same thing point at it.

Here is an instruction that names the finance lead once at the top, mentions them in a rule, and uses one parameter:

Refunds
---
spec: "1"
title: Refunds
parameters:
  refund_limit:
    type: number
    default: 200
    description: The largest refund the agent gives on its own, in euros
---
# Refunds

You handle refund requests for Acme's support team.

::person{id=finance-lead title="Finance lead"}

MUST: refund up to ${refund_limit} euros without asking anyone.
MUST: send a larger refund to :person[Finance lead]{ref=#finance-lead} and tell the customer who decides.
BECAUSE: the finance lead approves every refund above the limit.

The agent receives the parameter's value and each mention as its name followed by what it points at:

What the agent receives
# Refunds

You handle refund requests for Acme's support team.

### person: Finance lead

MUST: refund up to 200 euros without asking anyone.

MUST: send a larger refund to Finance lead (person; #finance-lead) and tell the customer who decides.
BECAUSE: the finance lead approves every refund above the limit.

Change or remove a mention in Preview

In Preview, the chip of a person, a role, an agent, a tool, a skill or an MCP server is a control. Click it, tap it, or move to it with Tab and press Enter or Space. Its picker opens right under the line, and the text below moves down to make room. This works the same on a phone.

Changing a mention in Preview, here or everywhere.
  1. Open the chip's picker

    Click the chip. The picker is named for what the chip is, such as Change the tool or Change the person. For a person, it shows who they are at the top: picture, name, job title and team.

  2. Pick the new one

    Type in Search to find another person, tool or skill of the same kind. The one the chip names now says In use here. A person's chip can also become a role or an agent. When nothing matches, the picker says Nothing like that here yet.

  3. Say where it changes

    If the instruction mentions the same thing more than once, the editor asks: "“Finance lead” is mentioned 2 times. Change it to “…”:". Choose This mention to change only this chip, or Everywhere to change all of them. Back returns to the list.

A message at the bottom of the screen confirms the change, such as "Tool changed to search_orders" or "Tool changed to search_orders everywhere". In suggestion mode it starts with "Suggested:". One press of ⌘Z (Ctrl+Z on Windows) undoes the whole change.

At the foot of the picker:

  • Show in Markdown puts the caret on the mention in Content.
  • Remove turns the chip back into plain words. The message says "Tool removed — its words stay": the name stays in your sentence, but it no longer points at anything.

Escape closes the picker and puts the focus back on the chip. Clicking anywhere else closes it too.

Someone who left

The "@" list never offers people who have left your organization. A mention you wrote before they left stays in the text. In Preview its chip has a dashed border, the name is struck through and it says · left. Its picker says No longer at Acme (your organization's name). Pick someone else to take their place, with Everywhere if they are mentioned more than once.

A person whose account is set up but who hasn't signed in yet shows Not signed in yet.

Approved integrations and blocked tools

Plans On Pro, Team, and Enterprise

Your organization's admins decide which integrations its instructions may use, and can block single tools. The editor shows you what they decided while you write:

  • A blocked tool is listed last, greyed out, with Blocked in this workspace. You can't pick it. If the text already mentions it, the problems list says: "The tool “…” is blocked in your organization, so the agent won't use it. Pick another tool, or ask an admin to allow it."
  • An integration that isn't approved gets this problem: "“…” isn't one of your organization's approved integrations, so the agent won't use it."

The agent follows the same rules, so the editor warns you rather than letting you write something the agent will ignore.

Plans On Team and Enterprise

When your organization keeps its instructions to approved integrations only, the "&" list holds only those integrations. The "@" list still holds your organization's people and agents.

An instruction can also narrow its own list of integrations. Then the messages say "this instruction's own settings" instead of "your organization". See Check your instruction before you publish for every message and its fix, and Add the tools your agents may use for how admins approve and block.

Use parameters

A parameter is a named value in your text, such as a limit, a tone or a team name. You write it once as ${name}. Each agent can get its own value, and the parameter's default is used when nobody gives one. Parameters are declared in Details, the part at the top of the instruction that says what it is.

Add a parameter

  1. Type $ and a name

    In Content, type $ and a name that starts with a letter, such as $refund_limit.

  2. Declare it

    If the instruction doesn't have that parameter yet, the list offers Declare refund_limit…, with "parameter · add it in Details". Take it. The editor writes ${refund_limit} in your text, adds the parameter to Details as text, and says Declared ${refund_limit}.

  3. Give it a type and a default

    Open Details and set what kind of value it is and what it starts as. The parameter's description is the plain name the editor shows for it in Preview.

A parameter can be one of these types:

Type in Details What it holds
string Any text. This is what Declare writes
number A number, like 7 or 2.5
integer A whole number, like 7
boolean Yes or no
enum One of a fixed list of values, given as values
list Several values
url A web address
duration A length of time

A parameter can also be marked required, and can carry an example. For a fixed list of values, Details looks like this:

Details
parameters:
  tone:
    type: enum
    values: [friendly, formal]
    default: friendly
    description: How the agent sounds

Try a value in Preview

In Preview, a parameter shows its value, or ${name} when it has none. Click it to open its picker under the line.

Trying a parameter's value in Preview.
  • The picker says what the agent gets there now: "The agent gets 200 · its default".
  • Pick one of its values, or type one in the field and choose Try. A value that doesn't fit says what it takes, such as "A whole number, like 7".
  • Trying a value changes Preview only, everywhere the parameter is used. Your text stays as written: the picker says "tried here — the text stays as written".
  • Make “250” the default writes the value you tried into Details as the new default.
  • Back to its default (or Clear what's tried when it has none) undoes the try.
  • Use another parameter here lists the instruction's other parameters. Pick one to use it in this place instead. The message says "This place now uses “…”".

Show in Markdown and Close are at the foot. Escape closes the picker too.

A name that isn't declared

If you type ${name} for a parameter that Details doesn't list, the agent receives ${name} exactly as written. The problems list says: "The value “name” is used but never set up, so the agent sees it as written." Fix it in one of these ways:

  • Click the parameter in Preview and choose Add it as a parameter.
  • Choose the fix Set up “name” in the problems list.

When a value is missing

When an agent receives the instruction, each parameter gets its value in this order:

  1. The value given for that agent, when there is one. A value that doesn't fit the type stops delivery with a problem.
  2. Otherwise, the default from Details.
  3. Otherwise, if the parameter is marked required, the agent can't receive the instruction until someone gives a value.
  4. Otherwise, the agent sees ${name} as written.

Give every parameter a default unless each agent really must get its own value.

Where the lists come from

The lists are made from what your organization already has. Nothing in them is invented.

  • People: your organization's members, with their role. When your organization connects a people directory, its people are listed too, with their job title, team and directory. See Bring in your company's people.
  • Agents: the agents your organization has set up, with what each one may do (reads, writes, releases).
  • MCP servers, tools, skills and APIs: the integrations your organization's admins have added, with each server's tools. See Add the tools your agents may use.
  • Skills: the skills the instruction.md server itself offers.
  • This instruction: the people, capabilities, rules and blocks it already declares or names.

Without an account, only the last group is listed.

Check it worked

  • In Preview, every mention shows as a chip, and every parameter shows its value.
  • The status bar says Ready to publish — no problems, or lists what to check. No message says a mention "points at something that isn't in this instruction".

Undo or stop

  • Press ⌘Z (Ctrl+Z on Windows) right after a change. A change made with Everywhere is undone in one step.
  • To stop the lists opening as you type, turn off Suggest as you type in Hints or in the View menu. The command palette and the selection menu still open them.

If it doesn't work

What you see What to do
Typing @ opens nothing Check that Suggest as you type is on. The list doesn't open inside code or a link's address. Type a space before the key
Nothing to point at here yet Sign in to list your organization's people and integrations. "#" lists only rules and blocks that have a name
A tool is greyed out with Blocked in this workspace An admin blocked it. Pick another tool, or ask an admin to allow it
"A mention points at something that isn't in this instruction." The block it pointed at was deleted or renamed. Click the chip and pick it again, or choose Remove
Clicking a chip does nothing You are a Reader of this instruction, or the text is read-only for now
"The value “…” is used but never set up, so the agent sees it as written." Choose Set up “…”, or click the parameter in Preview and choose Add it as a parameter

For other problems, see Troubleshooting.

Questions

What do @, &, # and $ do while I type?

They open a list at the caret: @ for people and agents, & for MCP servers, tools, skills and APIs, # for this instruction's named rules and blocks, and $ for parameters. Taking a row writes a mention that points at exactly that one. See What each key offers.

Does mentioning a tool give the agent access to it?

No. A mention tells the agent which tool you mean. What the agent can actually use is set where it runs and by your organization's integrations. See What an instruction can say.

Can I change the same person everywhere at once?

Yes. Click any of their chips in Preview, pick the new person, and choose Everywhere. One press of ⌘Z undoes it. See Change or remove a mention in Preview.

What happens to a mention when someone leaves?

The mention stays, and its chip is struck through with · left. The "@" list no longer offers them. Pick someone else from the chip's picker. See Someone who left.

Does trying a parameter value change my instruction?

No. Trying a value changes Preview only. Choose Make “…” the default to write it into Details. See Try a value in Preview.

For developers: Typed references and Parameters describe the syntax and how each form is delivered.

Last checked against the product:

Was this page helpful? Report a problem