# Managed Prompts

> Version and override Trigger.dev managed prompts via MCP — list, inspect, promote code versions, create dashboard overrides, hotfix, and revert. Use when the user asks about "trigger.dev prompt", "managed prompts", "prompt version", "prompt override", "hotfix prompt", "promote prompt version", "list prompts", or "revert prompt override".

- Skill: `agents-store/managed-prompts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add agents-store/managed-prompts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/managed-prompts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agents-store/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`)