Managed Prompts

Managed Prompts

Trigger.dev ships a Managed Prompts system: prompts are declared in code, shipped with the worker version, and can receive dashboard overrides that take effect without a redeploy. Seven MCP tools expose the full lifecycle.

Note: the /docs/prompts page was not published as of 2026-04-24. This skill documents the feature from the MCP tool schemas (introspected directly from the running MCP server). When the official SDK docs publish, update references/managed-prompts-reference.md with the code side.

Model

Each managed prompt has:

• slug — stable identifier (customer-reply, summarizer-v2).
• Versions — monotonically increasing integers. Each version carries:
  • source: "code" (committed with a worker deploy) or "dashboard" (created via the UI or an override tool)
  • model: the model string
  • content: the prompt text
  • labels: zero or more of current, override, latest

Resolution Rules

At runtime the prompt resolver picks the content in this order:

1. Active dashboard override (a version whose labels include "override"), if present.
2. Otherwise, the current code version (labels include "current").

• remove_prompt_override(slug) — delete the active override, revert to the code current.
• reactivate_prompt_override(slug, version) — bring back a historical dashboard version as the active override. Only works on source: "dashboard" versions.
• promote_prompt_version(slug, version) — re-point the current label to a different source: "code" version. Does not touch overrides; if an override is active it still wins at runtime.

MCP Tools

All 7 tools take the standard scope arguments (environment, projectRef, configPath, branch).

list_prompts

list_prompts({ environment: "prod" })
→ [{ slug, currentVersion, overrideActive, versionCount }, …]

First call in any prompt workflow.

get_prompt_versions

get_prompt_versions({ slug: "customer-reply", environment: "prod" })
→ [
  { version: 4, labels: ["current", "latest"], source: "code",      model: "gpt-4o-mini", content: "…" },
  { version: 5, labels: ["override"],          source: "dashboard", model: "gpt-4o",      content: "…" }
]

Inspect which version is active, whether an override is in play, and what historical dashboard versions exist.

promote_prompt_version

promote_prompt_version({ slug: "customer-reply", version: 4, environment: "prod" })

Makes version=4 the current code version. Requires source: "code" — dashboard-sourced versions go through the override tools.

create_prompt_override

create_prompt_override({
  slug:          "customer-reply",
  textContent:   "You are a support agent. Be concise and cite the ticket number…",
  model:         "gpt-4o",            // optional — overrides task default
  commitMessage: "Hotfix tone issue, ticket OPS-1234",
  environment:   "prod"
})

Creates a new dashboard-sourced version, marks it as the active override. Next runs pick it up immediately.

update_prompt_override

update_prompt_override({
  slug:          "customer-reply",
  textContent:   "Revised copy v2",
  model:         "gpt-4o",
  commitMessage: "Follow-up tweak"
})

Mutates the currently active override (creates a new dashboard version). Fails if no override is active — use create_prompt_override first.

remove_prompt_override

remove_prompt_override({ slug: "customer-reply", environment: "prod" })

Drops the override. Runtime resolution falls back to the current code version.

reactivate_prompt_override

reactivate_prompt_override({ slug: "customer-reply", version: 5, environment: "prod" })

Re-enables a prior dashboard-sourced version as the active override. Useful for rolling back a bad override tweak without re-typing the content.

Common Workflows

Inspect what's running in prod

1. list_prompts(environment="prod")
2. get_prompt_versions(slug="<slug>", environment="prod")

Hotfix a live prompt

1. list_prompts(environment="prod")                                                    → find slug
2. get_prompt_versions(slug, environment="prod")                                       → confirm no override active
3. create_prompt_override(slug, textContent="…revised copy…",
                          commitMessage="Hotfix for incident 2026-04-24")              → override active
4. (iterate) update_prompt_override(slug, textContent="…",
                                    commitMessage="Tighten instructions")
5. Verify on subsequent runs (list_runs, get_span_details for the LLM span)
6. Once the code fix lands and is promoted:
   remove_prompt_override(slug, environment="prod")                                    → revert to code

Roll back a bad override

1. get_prompt_versions(slug, environment="prod")                                       → find last good dashboard version
2. reactivate_prompt_override(slug, version=<older>, environment="prod")

Promote a code version after a deploy

1. deploy(environment="prod")                                                          → ships new worker
2. list_prompts(environment="prod")
3. get_prompt_versions(slug, environment="prod")                                       → find newly-added code version
4. promote_prompt_version(slug, version=<new>, environment="prod")                     → set new `current`

A dashboard override, if active, still wins at runtime after promote_prompt_version. Call remove_prompt_override to let the new code version take effect.

Safety Notes

• Prompt overrides are scoped to an environment + branch. Always double-check the environment argument before calling a write tool — a prod override can't be undone on dev.
• commitMessage is optional on create_prompt_override but required discipline — the dashboard version list is your audit trail.
• update_prompt_override fails loudly if no override is active; treat that as a signal to use create_prompt_override instead.
• Use --readonly on the MCP install to block prompt write tools in agent-only setups (along with deploy, trigger_task, cancel_run).
• When iterating heavily via code, prefer promote_prompt_version over overrides — it keeps source-of-truth in git.

SDK Usage

The SDK surface for declaring managed prompts in code is not yet publicly documented (the /docs/prompts page is 404 as of 2026-04-24). When Trigger.dev publishes the reference, update references/managed-prompts-reference.md with the @trigger.dev/sdk side (prompt() / definePrompt() helper, task integration, tool metadata for AI SDKs, etc.). Until then, this skill anchors on the MCP tool schemas — those are the authoritative source for agents.

Deeper Reference

• @references/managed-prompts-reference.md — full parameter schemas, input/output examples, worked walkthroughs
• Sibling skills: mcp-patterns (Managed Prompts section in the tool catalogue), observability (inspect LLM cost/tokens per prompt via llm_metrics)