# Prompt References

> Loading a saved prompt into a trigger, a ticket or a message used to be a copy: the text was pasted into the field and nothing tied it back to the library any more.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-09-09
- Web page: https://agentsroom.dev/docs/prompt-references

## What it does

Loading a saved prompt into a trigger, a ticket or a message used to be a copy:
the text was pasted into the field and nothing tied it back to the library any
more. Edit the prompt afterwards and the nightly agent that copied it three
weeks ago keeps running the old wording, silently. A **reference** fixes that:
the field receives a small token instead of the text, and the prompt is looked
up and substituted when the run actually starts. One place to edit, every caller
follows.

## Where to find it

Wherever you pick a saved prompt into a long-lived field: the trigger editor,
a backlog ticket, an agent's brief. The picker shows **How to insert** with two
choices, **Text** and **Reference**, and the field carries the hint **Reference
a saved prompt:** with **Its text replaces the token when the run starts.**

## How to use it

1. Open the field and pick a prompt from the library.
2. Choose the insertion mode:
   - **Text** ("Copy the prompt body into the field"): the historic behaviour, a
     standalone copy. Still the right choice when you want to start from the
     prompt and tweak it for this one case.
   - **Reference** ("Insert a token replaced by the prompt text when the run
     starts"): the field gets `{{prompt:<handle>}}` and the picker confirms
     **Reference inserted**.
3. Save. Nothing else changes: the trigger, the ticket or the brief looks the
   same, it is just shorter.
4. Edit the prompt in the library whenever you like. The next run picks the new
   text up on its own.

A referenced prompt may itself reference others, so a shared "project
conventions" block can sit at the bottom of several briefs without being pasted
anywhere.

## Settings

None.

## Agent tools (MCP)

- `prompts_list`: returns each prompt's **handle**, which is what a reference
  resolves on, so an agent can write a reference instead of a frozen copy.
- `prompts_get`: the full body behind a handle.
- `triggers_save`, `backlog_create`, `backlog_update`: the fields a reference is
  usually written into.

## Providers

All providers, no difference. Resolution happens before the CLI is launched, so
the agent receives ordinary text whatever the CLI is.

## Mobile

Present, with the same words: the phone's picker offers **Text** and
**Reference** and writes the same token, and a run started from the phone
resolves it exactly as the desktop does.

## Limits

- A handle is an **address**, not a label: it is set when the prompt is created
  and never recomputed when the prompt is renamed, so renaming never breaks the
  callers.
- A reference that points at nothing **fails the launch**, naming the missing
  handle ("Prompt not found: ... The run was not started."). This is deliberate:
  a brief silently amputated of half its instructions does damage for days.
- References nest three levels deep at most, and a loop is refused rather than
  followed.
- If a project prompt and a global prompt share a handle, the **project** one
  wins and the picker says so.
- A prompt with no handle yet cannot be referenced; the picker says so instead
  of inserting a broken token.
- The composer's inline autocomplete always inserts the **text**: typing a
  trigger key mid-sentence is a writing gesture, not a wiring one.

## Common questions

- **What is the difference with linked prompts?** Linked prompts append other
  prompts when you copy or send this one, and the result is a copy. A reference
  stays a pointer until the run starts. See [Linked Prompts](https://agentsroom.dev/docs/linked-prompts.md).
- **I renamed my prompt, did I break my triggers?** No. The handle does not
  follow the title.
- **What happens if I delete a referenced prompt?** The next run of whatever
  referenced it stops and tells you which handle is missing.
- **Can I still paste the text?** Yes, pick **Text** in the picker.

## Related

- [Prompt Library](https://agentsroom.dev/docs/prompt-library.md): where the prompts and their handles live.
- [Linked Prompts](https://agentsroom.dev/docs/linked-prompts.md): composing a prompt out of other prompts, by copy.
- [Scheduled Tasks](https://agentsroom.dev/docs/scheduled-tasks.md): the long-lived field references were built for.
- [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): tickets can carry a reference too.