feat(sdk,cli): namespace agent skills with trigger- and add cost-savings

ericallam · ericallam · commit 603d5e421ea8 · 2026-06-16T18:45:27.000+01:00
The installed skills now use a `trigger-` prefix (`trigger-authoring-tasks`,
`trigger-getting-started`, and so on) so they do not collide with non-Trigger
skills in a shared agent skills directory, matching the public skills repo.

Adds `trigger-cost-savings`: an MCP-driven audit that right-sizes machines, flags
missing `maxDuration`, and spots sequential triggers that could batch.

`@trigger.dev/sdk` now bundles the entire Documentation section of the docs
(not just a curated subset), so an agent has the full version-pinned reference in
node_modules. The build derives the set from the docs navigation, so it stays in
sync automatically.
diff --git a/.changeset/trigger-skill-namespace-and-docs.md b/.changeset/trigger-skill-namespace-and-docs.md
@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+"trigger.dev": patch
+---
+
+The agent skills installed by `trigger skills` are now namespaced with a `trigger-` prefix (e.g. `trigger-authoring-tasks`, `trigger-getting-started`) so they don't collide with unrelated skills in your coding agent's skills directory. Adds a `trigger-cost-savings` skill for auditing and reducing compute spend (right-sizing machines, `maxDuration`, batching, debounce), and `@trigger.dev/sdk` now bundles the full Trigger.dev documentation so your agent can read the complete, version-pinned reference directly from node_modules.
diff --git a/docs/mcp-agent-rules.mdx b/docs/mcp-agent-rules.mdx
@@ -21,7 +21,7 @@ npx trigger.dev@latest skills
 
 `npx trigger.dev@latest install-rules` still works as an alias, and `trigger dev` offers to install the skills on first run.
 
-The old task and realtime guidance now lives in the `authoring-tasks` and `realtime-and-frontend` skills, alongside two new skills for building `chat.agent` AI agents. See [Skills](/skills) for the full list and supported assistants.
+The old task and realtime guidance now lives in the `trigger-authoring-tasks` and `trigger-realtime-and-frontend` skills, alongside two new skills for building `chat.agent` AI agents. See [Skills](/skills) for the full list and supported assistants.
 
 ## Next steps
 
diff --git a/docs/skills.mdx b/docs/skills.mdx
@@ -42,12 +42,13 @@ npx trigger.dev@latest skills --target claude-code --target cursor -y
 
 | Skill                  | Use for                                                        | Covers                                                                       |
 | ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `authoring-tasks`      | Writing background and scheduled tasks                         | `task`/`schemaTask`, retries, queues, waits, idempotency, metadata, triggering, cron, `trigger.config.ts` |
-| `realtime-and-frontend`| Live run updates and triggering from the browser               | `runs.subscribeToRun`, `@trigger.dev/react-hooks`, public access tokens, streams |
-| `authoring-chat-agent` | Building durable AI chat agents                                | `chat.agent` run loop, `toStreamTextOptions`, server actions, `useChat` transport, tools, lifecycle hooks |
-| `chat-agent-advanced`  | Advanced chat.agent patterns                                   | sessions, human-in-the-loop, sub-agents, compaction, fast starts, resilience, version upgrades |
+| `trigger-authoring-tasks`      | Writing background and scheduled tasks                         | `task`/`schemaTask`, retries, queues, waits, idempotency, metadata, triggering, cron, `trigger.config.ts` |
+| `trigger-realtime-and-frontend`| Live run updates and triggering from the browser               | `runs.subscribeToRun`, `@trigger.dev/react-hooks`, public access tokens, streams |
+| `trigger-authoring-chat-agent` | Building durable AI chat agents                                | `chat.agent` run loop, `toStreamTextOptions`, server actions, `useChat` transport, tools, lifecycle hooks |
+| `trigger-chat-agent-advanced`  | Advanced chat.agent patterns                                   | sessions, human-in-the-loop, sub-agents, compaction, fast starts, resilience, version upgrades |
+| `trigger-cost-savings`         | Auditing and reducing compute spend                            | right-sizing machines, `maxDuration`, batch vs sequential, debounce, schedule frequency, MCP run analysis |
 
-Not sure which to install? Pick `authoring-tasks`; it covers the most common patterns for writing Trigger.dev tasks.
+Not sure which to install? Pick `trigger-authoring-tasks`; it covers the most common patterns for writing Trigger.dev tasks.
 
 ## Supported AI assistants
 
diff --git a/packages/cli-v3/skills/trigger-authoring-chat-agent/SKILL.md b/packages/cli-v3/skills/trigger-authoring-chat-agent/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: authoring-chat-agent
+name: trigger-authoring-chat-agent
 description: >
   Author and run a durable AI chat agent with chat.agent from @trigger.dev/sdk/ai: the per-turn
   run loop, why you MUST spread ...chat.toStreamTextOptions() first, returning a StreamTextResult
@@ -16,7 +16,7 @@ library: trigger.dev
 
 The full, version-pinned reference ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
 
-- **Skill:** `node_modules/@trigger.dev/sdk/skills/authoring-chat-agent/SKILL.md` — the per-turn run loop, `chat.toStreamTextOptions()`, the two server actions, typed tools/data parts, and the React transport.
+- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-authoring-chat-agent/SKILL.md` — the per-turn run loop, `chat.toStreamTextOptions()`, the two server actions, typed tools/data parts, and the React transport.
 - **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/ai-chat/`; the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for an API, e.g. `grep -rl "toStreamTextOptions" node_modules/@trigger.dev/sdk/docs/`.
 
 If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
@@ -57,4 +57,4 @@ If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install i
 
 ## References
 
-Sibling skills: **chat-agent-advanced** (Sessions primitive, custom transports, sub-agents, HITL, fast starts, resilience, testing, upgrades), **authoring-tasks** and **realtime-and-frontend** (the task + frontend foundations chat builds on).
+Sibling skills: **trigger-chat-agent-advanced** (Sessions primitive, custom transports, sub-agents, HITL, fast starts, resilience, testing, upgrades), **trigger-authoring-tasks** and **trigger-realtime-and-frontend** (the task + frontend foundations chat builds on).
diff --git a/packages/cli-v3/skills/trigger-authoring-tasks/SKILL.md b/packages/cli-v3/skills/trigger-authoring-tasks/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: authoring-tasks
+name: trigger-authoring-tasks
 description: >
   Covers writing backend Trigger.dev tasks with @trigger.dev/sdk: defining task() and
   schemaTask(), the run function and its ctx, retries, waits, queues and concurrency,
@@ -15,7 +15,7 @@ library: trigger.dev
 
 The full, version-pinned reference for authoring tasks ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
 
-- **Skill:** `node_modules/@trigger.dev/sdk/skills/authoring-tasks/SKILL.md` — the complete guide (setup, `schemaTask`, retries, triggering + the Result shape, idempotency, waits, metadata, scheduled tasks, queues/concurrency, `trigger.config.ts`).
+- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-authoring-tasks/SKILL.md` — the complete guide (setup, `schemaTask`, retries, triggering + the Result shape, idempotency, waits, metadata, scheduled tasks, queues/concurrency, `trigger.config.ts`).
 - **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/`; the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for an API, e.g. `grep -rl "schemaTask" node_modules/@trigger.dev/sdk/docs/`.
 
 If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
@@ -54,4 +54,4 @@ Always import from `@trigger.dev/sdk` — never `@trigger.dev/sdk/v3` (deprecate
 
 ## References
 
-Sibling skills: **realtime-and-frontend** (subscribe to runs, trigger from the frontend), **authoring-chat-agent** and **chat-agent-advanced** (AI chat agents).
+Sibling skills: **trigger-realtime-and-frontend** (subscribe to runs, trigger from the frontend), **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** (AI chat agents).
diff --git a/packages/cli-v3/skills/trigger-chat-agent-advanced/SKILL.md b/packages/cli-v3/skills/trigger-chat-agent-advanced/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: chat-agent-advanced
+name: trigger-chat-agent-advanced
 description: >
   Advanced and operational chat.agent capabilities for Trigger.dev, loaded on demand. Load this when
   working on the raw Sessions primitive (sessions / SessionHandle), a custom chat transport or the
@@ -8,7 +8,7 @@ description: >
   Start via @trigger.dev/sdk/chat-server), context resilience (compaction, recovery boot, OOM, large
   payloads), chat.local run-scoped state, offline testing with mockChatAgent, or prerelease/version
   upgrades. For the everyday chat.agent({...}) definition and the useTriggerChatTransport happy path,
-  use the authoring-chat-agent skill instead.
+  use the trigger-authoring-chat-agent skill instead.
 type: core
 library: trigger.dev
 ---
@@ -17,7 +17,7 @@ library: trigger.dev
 
 The full, version-pinned reference ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
 
-- **Skill:** `node_modules/@trigger.dev/sdk/skills/chat-agent-advanced/SKILL.md` — Sessions primitive, custom transports/wire protocol, sub-agents, HITL, steering, actions, background injection, fast starts, resilience (compaction/recovery/OOM/large payloads), `chat.local`, testing, upgrades.
+- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-chat-agent-advanced/SKILL.md` — Sessions primitive, custom transports/wire protocol, sub-agents, HITL, steering, actions, background injection, fast starts, resilience (compaction/recovery/OOM/large payloads), `chat.local`, testing, upgrades.
 - **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/ai-chat/` (including `patterns/` for HITL, sub-agents, sessions); the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for an API, e.g. `grep -rl "mockChatAgent" node_modules/@trigger.dev/sdk/docs/`.
 
 If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
@@ -67,4 +67,4 @@ If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install i
 
 ## References
 
-Sibling skills: **authoring-chat-agent** (the everyday `chat.agent({...})` happy path), **authoring-tasks** and **realtime-and-frontend** (task + frontend foundations).
+Sibling skills: **trigger-authoring-chat-agent** (the everyday `chat.agent({...})` happy path), **trigger-authoring-tasks** and **trigger-realtime-and-frontend** (task + frontend foundations).
diff --git a/packages/cli-v3/skills/trigger-cost-savings/SKILL.md b/packages/cli-v3/skills/trigger-cost-savings/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: trigger-cost-savings
+description: >
+  Analyze Trigger.dev tasks, schedules, and runs for cost optimization opportunities. Use when
+  asked to reduce spend, optimize costs, audit usage, right-size machines, or review task
+  efficiency. Combines static source analysis with live run analysis via the Trigger.dev MCP
+  tools (list_runs, get_run_details, get_current_worker).
+type: core
+library: trigger.dev
+---
+
+# Trigger.dev Cost Savings Analysis
+
+The full, version-pinned cost-audit workflow ships **inside your installed `@trigger.dev/sdk`**. Read it before giving recommendations so they match the SDK version in this project:
+
+- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-cost-savings/SKILL.md` — the static-analysis checklist, the MCP run-analysis steps (`list_runs`, `get_run_details`, `get_current_worker`), the report format, and the machine-preset cost table.
+- **Docs:** the canonical guidance is bundled at `node_modules/@trigger.dev/sdk/docs/how-to-reduce-your-spend.mdx`, with supporting pages under `node_modules/@trigger.dev/sdk/docs/` (`machines.mdx`, `runs/max-duration.mdx`, `queue-concurrency.mdx`, `idempotency.mdx`, `triggering.mdx`, `errors-retrying.mdx`).
+
+If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
+
+Live run analysis needs the Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`). Without it, do the static source analysis only — never fabricate run data.
+
+## Key principles
+
+- **Waits > 5 seconds are free** — checkpointed, no compute charge.
+- **Start small, scale up** — the default `small-1x` is right for most tasks; right-size down tasks stuck on `large-*` with short durations.
+- **I/O-bound tasks don't need big machines** — API calls and DB queries wait on the network.
+- **Add `maxDuration`** — cap runaway compute.
+- **Debounce high-frequency triggers** — consolidate bursts into single runs.
+- **Idempotency keys prevent duplicate billed work.**
+- **`AbortTaskRunError` stops wasteful retries** — don't pay to retry permanent failures.
+
+## References
+
+Sibling skills: **trigger-authoring-tasks** (the task options these levers tune: `machine`, `maxDuration`, `retry`, `queue`, idempotency), **trigger-realtime-and-frontend**, **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** (AI agents).
diff --git a/packages/cli-v3/skills/trigger-getting-started/SKILL.md b/packages/cli-v3/skills/trigger-getting-started/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: getting-started
+name: trigger-getting-started
 description: >
   Bootstrap Trigger.dev into an existing project from scratch: authenticate the
   CLI, install @trigger.dev/sdk and @trigger.dev/build, write trigger.config.ts
@@ -8,7 +8,7 @@ description: >
   server. Load this when a project has no trigger.config.ts yet and the user
   asks to "add Trigger.dev", "set up Trigger.dev", "initialize Trigger.dev", or
   get a first task running, including in a monorepo. Once the project is set up
-  and you are writing task code, switch to the authoring-tasks skill.
+  and you are writing task code, switch to the trigger-authoring-tasks skill.
 type: core
 library: trigger.dev
 library_version: "{{TRIGGER_SDK_VERSION}}"
@@ -198,10 +198,10 @@ See the manual setup docs for full Turborepo examples before scaffolding either.
 
 Sibling skills:
 
-- **authoring-tasks** for writing the tasks themselves once setup is done: retries, waits,
+- **trigger-authoring-tasks** for writing the tasks themselves once setup is done: retries, waits,
   queues, scheduled tasks, triggering, and the full `trigger.config.ts`.
-- **realtime-and-frontend** for showing live run status in a frontend.
-- **authoring-chat-agent** and **chat-agent-advanced** for building AI chat agents.
+- **trigger-realtime-and-frontend** for showing live run status in a frontend.
+- **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** for building AI chat agents.
 
 Docs:
 
diff --git a/packages/cli-v3/skills/trigger-realtime-and-frontend/SKILL.md b/packages/cli-v3/skills/trigger-realtime-and-frontend/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: realtime-and-frontend
+name: trigger-realtime-and-frontend
 description: >
   Trigger.dev client/frontend surface: subscribe to runs in realtime
   (runs.subscribeToRun and the @trigger.dev/react-hooks hook useRealtimeRun),
@@ -10,7 +10,7 @@ description: >
   Load when wiring a frontend (React/Next.js/Remix) or backend-for-frontend to
   show live run progress, status badges, token streams, trigger buttons, or
   wait-token approval UIs. NOT for writing the backend task itself (streams.define
-  / metadata.set is authoring-tasks territory); this is the consumer side.
+  / metadata.set is trigger-authoring-tasks territory); this is the consumer side.
 type: core
 library: trigger.dev
 ---
@@ -19,7 +19,7 @@ library: trigger.dev
 
 The full, version-pinned reference ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
 
-- **Skill:** `node_modules/@trigger.dev/sdk/skills/realtime-and-frontend/SKILL.md` — run subscriptions, `@trigger.dev/react-hooks`, streams, frontend triggering, and scoped tokens.
+- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-realtime-and-frontend/SKILL.md` — run subscriptions, `@trigger.dev/react-hooks`, streams, frontend triggering, and scoped tokens.
 - **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/realtime/`; the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for a hook, e.g. `grep -rl "useRealtimeRun" node_modules/@trigger.dev/sdk/docs/`.
 
 If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
@@ -55,4 +55,4 @@ If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install i
 
 ## References
 
-Sibling skills: **authoring-tasks** (the task side: `streams.define()`, `metadata.set()`, `wait.createToken`), **authoring-chat-agent** and **chat-agent-advanced** (chat agents build on these realtime streams).
+Sibling skills: **trigger-authoring-tasks** (the task side: `streams.define()`, `metadata.set()`, `wait.createToken`), **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** (chat agents build on these realtime streams).
diff --git a/packages/cli-v3/src/commands/init.ts b/packages/cli-v3/src/commands/init.ts
@@ -237,9 +237,9 @@ async function _initCommand(dir: string, options: InitCommandOptions) {
       if (!isCancel(setupChoice) && setupChoice === "ai") {
         outro(
           installedSkills && installedMcp
-            ? "Your AI tooling is ready. Ask your assistant to set up Trigger.dev; it can use the getting-started skill and the MCP server to add the SDK, config, and your first task."
+            ? "Your AI tooling is ready. Ask your assistant to set up Trigger.dev; it can use the trigger-getting-started skill and the MCP server to add the SDK, config, and your first task."
             : installedSkills
-              ? "Your AI tooling is ready. Ask your assistant to set up Trigger.dev and it will use the getting-started skill to add the SDK, config, and your first task."
+              ? "Your AI tooling is ready. Ask your assistant to set up Trigger.dev and it will use the trigger-getting-started skill to add the SDK, config, and your first task."
               : "The MCP server is installed. Ask your assistant to set up Trigger.dev using the MCP server."
         );
         return;
diff --git a/packages/trigger-sdk/skills/trigger-authoring-chat-agent/SKILL.md b/packages/trigger-sdk/skills/trigger-authoring-chat-agent/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: authoring-chat-agent
+name: trigger-authoring-chat-agent
 description: >
   Author and run a durable AI chat agent with chat.agent from @trigger.dev/sdk/ai: the per-turn
   run loop, why you MUST spread ...chat.toStreamTextOptions() first, returning a StreamTextResult
@@ -282,13 +282,15 @@ There is no API route in this model. The transport replaces the route round-trip
 
 ## References
 
-- `chat-agent-advanced` skill - lifecycle hooks in depth, sessions, raw-task primitives
+- `trigger-chat-agent-advanced` skill - lifecycle hooks in depth, sessions, raw-task primitives
   (`chat.createSession`, `chat.customAgent`, `chat.stream`), compaction, HITL approvals, recovery.
-- `realtime-and-frontend` skill - Realtime hooks and frontend streaming beyond the chat transport.
-- `authoring-tasks` skill - base `task()` semantics, `ctx`, and standard lifecycle hooks.
+- `trigger-realtime-and-frontend` skill - Realtime hooks and frontend streaming beyond the chat transport.
+- `trigger-authoring-tasks` skill - base `task()` semantics, `ctx`, and standard lifecycle hooks.
 
 Reference docs ship beside this skill in the same package, read them locally (no network), pinned to your installed version. The `sources:` frontmatter above lists every doc this skill draws from, all under `@trigger.dev/sdk/docs/ai-chat/`. Start with `quick-start.mdx`, `backend.mdx`, `tools.mdx`, `types.mdx`, `frontend.mdx`.
 
+A `chat.agent` is a Trigger.dev task, so it builds and deploys like any other. For `trigger.config.ts` and build extensions (Prisma, Playwright, Python, FFmpeg, etc. — e.g. when a tool needs them), read the bundled config docs under `@trigger.dev/sdk/docs/config/` (extensions are in `config/extensions/`, starting with `overview.mdx`).
+
 ## Version
 
 This skill is bundled inside `@trigger.dev/sdk` and read directly from `node_modules`, so it always matches your installed SDK version (see the adjacent `package.json`). The full documentation for these APIs ships alongside it under `@trigger.dev/sdk/docs/`.
diff --git a/packages/trigger-sdk/skills/trigger-authoring-tasks/SKILL.md b/packages/trigger-sdk/skills/trigger-authoring-tasks/SKILL.md
diff --git a/packages/trigger-sdk/skills/trigger-chat-agent-advanced/SKILL.md b/packages/trigger-sdk/skills/trigger-chat-agent-advanced/SKILL.md
diff --git a/packages/trigger-sdk/skills/trigger-cost-savings/SKILL.md b/packages/trigger-sdk/skills/trigger-cost-savings/SKILL.md
diff --git a/packages/trigger-sdk/skills/trigger-realtime-and-frontend/SKILL.md b/packages/trigger-sdk/skills/trigger-realtime-and-frontend/SKILL.md
diff --git a/scripts/bundleSdkDocs.ts b/scripts/bundleSdkDocs.ts
