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

.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.

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
 

docs/skills.mdx

@@ -28,7 +28,7 @@ The CLI detects your installed AI tools, lets you pick which skills to install,
 
 When you run `trigger dev` for the first time, the CLI offers to install the skills for you.
 
-The installed skills are lightweight. Most point to the full, version-pinned reference that ships inside `@trigger.dev/sdk`, which your assistant reads straight from `node_modules`. The API guidance it follows always matches the `@trigger.dev/sdk` version installed in your project, with no extra step on your part. The `getting-started` skill is self-contained, since it runs before the SDK is installed.
+The installed skills are lightweight. Most point to the full, version-pinned reference that ships inside `@trigger.dev/sdk`, which your assistant reads straight from `node_modules`. The API guidance it follows always matches the `@trigger.dev/sdk` version installed in your project, with no extra step on your part. The `trigger-getting-started` skill is self-contained, since it runs before the SDK is installed.
 
 ### Non-interactive install
 
@@ -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
 

packages/cli-v3/skills/authoring-chat-agent/SKILL.md → 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).

packages/cli-v3/skills/authoring-tasks/SKILL.md → 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).

packages/cli-v3/skills/chat-agent-advanced/SKILL.md → 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).

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).

packages/cli-v3/skills/getting-started/SKILL.md → 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:
 

packages/cli-v3/skills/realtime-and-frontend/SKILL.md → 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).

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;