feat(sdk,cli): namespace agent skills with trigger- and add cost-savings (#3970)
## Summary Three improvements to the SDK-bundled agent skills (follow-up to the skills installer): - **`trigger-` namespace.** The installed skills (`authoring-tasks`, `getting-started`, …) had generic names that collide with unrelated skills in a shared agent skills directory. They're now prefixed — `trigger-authoring-tasks`, `trigger-getting-started`, etc. — matching the convention the public skills repo already uses. - **New `trigger-cost-savings` skill.** An MCP-driven cost audit: right-sizes machines, flags missing `maxDuration`, spots sequential triggers that could batch, and reviews schedule frequency, using `list_runs` / `get_run_details` for live analysis. - **Bundle the full docs.** `@trigger.dev/sdk` now bundles the entire "Documentation" section of the docs (157 pages) instead of a curated 55-page subset, so an agent has the complete, version-pinned reference in `node_modules`. ## How the bundling works `scripts/bundleSdkDocs.ts` now reads `docs/docs.json`, walks the "Documentation" dropdown, and copies every page under it into the SDK. The set tracks the docs navigation automatically — add a page to the nav and it ships, no skill edits needed. The API reference and Guides & examples dropdowns are intentionally excluded. A skill's `sources:` frontmatter is now informational only. The dropped idea of a dedicated `trigger-config` skill is replaced by references to the bundled build-extension docs (`config/extensions/*`) from the `trigger-authoring-tasks` config section and the chat-agent skills.
This commit is contained in:
Eric Allam
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
+7
-6
@@ -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
|
||||
|
||||
|
||||
+3
-3
@@ -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).
|
||||
+3
-3
@@ -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).
|
||||
+4
-4
@@ -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).
|
||||
@@ -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).
|
||||
+5
-5
@@ -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:
|
||||
|
||||
+4
-4
@@ -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).
|
||||
@@ -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;
|
||||
|
||||
+6
-4
@@ -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/`.
|
||||
+4
-4
@@ -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,
|
||||
@@ -200,7 +200,7 @@ export default defineConfig({
|
||||
});
|
||||
```
|
||||
|
||||
`build.external` controls which packages stay out of the bundle. Build extensions (`additionalFiles`, `prismaExtension`, `puppeteer`, `ffmpeg`, `aptGet`, etc.) come from `@trigger.dev/build`. `telemetry` configures instrumentations and exporters.
|
||||
`build.external` controls which packages stay out of the bundle. Build extensions (`additionalFiles`, `prismaExtension`, `puppeteer`, `playwright`, `ffmpeg`, `pythonExtension`, `aptGet`, `syncEnvVars`, etc.) come from `@trigger.dev/build`. `telemetry` configures instrumentations and exporters. Each extension has its own setup doc, all bundled under `@trigger.dev/sdk/docs/config/extensions/` (start with `overview.mdx`); read the one you need before wiring it up rather than guessing the API.
|
||||
|
||||
### Logging
|
||||
|
||||
@@ -240,8 +240,8 @@ export default defineConfig({
|
||||
|
||||
Sibling skills:
|
||||
|
||||
- **realtime-and-frontend** for subscribing to runs and triggering from the frontend with React hooks.
|
||||
- **authoring-chat-agent** and **chat-agent-advanced** for building AI chat agents.
|
||||
- **trigger-realtime-and-frontend** for subscribing to runs and triggering from the frontend with React hooks.
|
||||
- **trigger-authoring-chat-agent** and **trigger-chat-agent-advanced** for building AI chat agents.
|
||||
|
||||
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/`. Start with:
|
||||
|
||||
+7
-5
@@ -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
|
||||
sources:
|
||||
@@ -354,13 +354,15 @@ TS helpers `SSEStreamSubscription` and `controlSubtype(headers)` (documented in
|
||||
|
||||
## References
|
||||
|
||||
- `authoring-chat-agent` skill - the everyday `chat.agent({...})` definition, lifecycle hooks, and
|
||||
- `trigger-authoring-chat-agent` skill - the everyday `chat.agent({...})` definition, lifecycle hooks, and
|
||||
the `useTriggerChatTransport` happy path. Start there before reaching for this skill.
|
||||
- `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/` (including `patterns/`). For HITL, sessions, and sub-agents start with `sessions.mdx`, `server-chat.mdx`, `client-protocol.mdx`, `patterns/human-in-the-loop.mdx`, `patterns/sub-agents.mdx`.
|
||||
|
||||
For `trigger.config.ts` and build extensions a chat-agent task may need (Prisma, Playwright, Python, etc.), read the bundled config docs under `@trigger.dev/sdk/docs/config/` (`config/extensions/` for the per-extension setup).
|
||||
|
||||
## 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/`.
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
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
|
||||
sources:
|
||||
- docs/how-to-reduce-your-spend.mdx
|
||||
- docs/machines.mdx
|
||||
- docs/runs/max-duration.mdx
|
||||
- docs/queue-concurrency.mdx
|
||||
- docs/idempotency.mdx
|
||||
- docs/triggering.mdx
|
||||
- docs/errors-retrying.mdx
|
||||
- docs/limits.mdx
|
||||
---
|
||||
|
||||
# Trigger.dev Cost Savings Analysis
|
||||
|
||||
Analyze task runs and configurations to find cost reduction opportunities. This skill pairs static source analysis with live run analysis via the Trigger.dev MCP server.
|
||||
|
||||
## Before you start: read the canonical guidance
|
||||
|
||||
The authoritative, version-pinned cost guidance ships beside this skill. Read it first so your recommendations match the installed SDK version:
|
||||
|
||||
- `@trigger.dev/sdk/docs/how-to-reduce-your-spend.mdx` — the canonical "reduce your spend" guide (machine sizing, idempotency de-dup, parallelism, retries, `maxDuration`, checkpointed waits, debounce).
|
||||
- Supporting references: `@trigger.dev/sdk/docs/machines.mdx`, `runs/max-duration.mdx`, `queue-concurrency.mdx`, `idempotency.mdx`, `triggering.mdx` (debounce + batch), `errors-retrying.mdx` (`AbortTaskRunError`).
|
||||
|
||||
## Prerequisites: MCP tools
|
||||
|
||||
Live run analysis needs the **Trigger.dev MCP server**. Verify these tools are available:
|
||||
|
||||
- `list_runs` — list runs with filters (status, task, time period, machine size)
|
||||
- `get_run_details` — get run logs, duration, and status
|
||||
- `get_current_worker` — get registered tasks and their configurations
|
||||
|
||||
If they're not available, tell the user to install the MCP server:
|
||||
|
||||
```bash
|
||||
npx trigger.dev@latest install-mcp
|
||||
```
|
||||
|
||||
Without the MCP tools you can still do the static source analysis below; do not fabricate run data.
|
||||
|
||||
## Analysis workflow
|
||||
|
||||
### Step 1: Static analysis (source code)
|
||||
|
||||
Scan task files for:
|
||||
|
||||
1. **Oversized machines** — tasks on `large-1x`/`large-2x` without clear need.
|
||||
2. **Missing `maxDuration`** — no execution-time limit (runaway-cost risk).
|
||||
3. **Excessive retries** — `maxAttempts` > 5 without `AbortTaskRunError` for known-permanent failures.
|
||||
4. **Missing debounce** — high-frequency triggers without debounce.
|
||||
5. **Missing idempotency** — payment/critical tasks without idempotency keys.
|
||||
6. **Polling instead of waits** — `setTimeout`/`setInterval`/sleep loops instead of `wait.for()`.
|
||||
7. **Short waits** — `wait.for()` under 5 seconds (not checkpointed, wastes compute).
|
||||
8. **Sequential instead of batch** — multiple `triggerAndWait()` calls that could be `batchTriggerAndWait()`.
|
||||
9. **Over-scheduled crons** — schedules firing more often than needed.
|
||||
|
||||
### Step 2: Run analysis (requires MCP tools)
|
||||
|
||||
- **2a. Expensive tasks** — `list_runs` over `period: "30d"`/`"7d"`; find high total compute (duration × count), high failure rates, and large machines with short durations (over-provisioned).
|
||||
- **2b. Failure patterns** — `list_runs` with `status: "FAILED"`/`"CRASHED"`; separate transient (retryable) from permanent; suggest `AbortTaskRunError` for the latter; estimate wasted retry compute.
|
||||
- **2c. Machine utilization** — `get_run_details` on sample runs; if a `large-2x` task consistently runs in under a second, or is I/O-bound (API/DB), it's over-provisioned.
|
||||
- **2d. Schedule frequency** — `get_current_worker` to list cron patterns; flag schedules that are too frequent for their purpose.
|
||||
|
||||
### Step 3: Generate recommendations
|
||||
|
||||
Present a prioritized report with estimated impact:
|
||||
|
||||
```markdown
|
||||
## Cost Optimization Report
|
||||
|
||||
### High impact
|
||||
1. **Right-size `process-images`** — currently `large-2x`, average run 2s. `small-2x` could cut this task's cost by ~16x.
|
||||
`machine: { preset: "small-2x" }` // was "large-2x"
|
||||
|
||||
### Medium impact
|
||||
2. **Debounce `sync-user-data`** — 847 runs/day, often bursty.
|
||||
`debounce: { key: \`user-${userId}\`, delay: "5s" }`
|
||||
|
||||
### Low impact / best practice
|
||||
3. **Add `maxDuration` to `generate-report`** — no timeout configured.
|
||||
`maxDuration: 300` // 5 minutes
|
||||
```
|
||||
|
||||
## Machine preset costs (relative)
|
||||
|
||||
Larger machines cost proportionally more per second of compute:
|
||||
|
||||
| Preset | vCPU | RAM | Relative cost |
|
||||
|--------|------|-----|---------------|
|
||||
| micro | 0.25 | 0.25 GB | 0.25x |
|
||||
| small-1x | 0.5 | 0.5 GB | 1x (baseline) |
|
||||
| small-2x | 1 | 1 GB | 2x |
|
||||
| medium-1x | 1 | 2 GB | 2x |
|
||||
| medium-2x | 2 | 4 GB | 4x |
|
||||
| large-1x | 4 | 8 GB | 8x |
|
||||
| large-2x | 8 | 16 GB | 16x |
|
||||
|
||||
## Key principles
|
||||
|
||||
- **Waits > 5 seconds are free** — checkpointed, no compute charge.
|
||||
- **Start small, scale up** — the default `small-1x` is right for most tasks.
|
||||
- **I/O-bound tasks don't need big machines** — API calls and DB queries wait on the network.
|
||||
- **Debounce saves the most on high-frequency tasks** — it consolidates bursts into single runs.
|
||||
- **Idempotency prevents duplicate billed work** — especially for expensive operations.
|
||||
- **`AbortTaskRunError` stops wasteful retries** — don't pay to retry permanent failures.
|
||||
|
||||
## 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 cost documentation ships alongside it under `@trigger.dev/sdk/docs/`.
|
||||
+4
-4
@@ -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
|
||||
sources:
|
||||
@@ -262,8 +262,8 @@ for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
|
||||
## References
|
||||
|
||||
Sibling skills:
|
||||
- `authoring-tasks` for the task side: `streams.define()`, `metadata.set()`, and `wait.createToken`.
|
||||
- `authoring-chat-agent` and `chat-agent-advanced` for chat agents, which build on these realtime streams.
|
||||
- `trigger-authoring-tasks` for the task side: `streams.define()`, `metadata.set()`, and `wait.createToken`.
|
||||
- `trigger-authoring-chat-agent` and `trigger-chat-agent-advanced` for chat agents, which build on these realtime streams.
|
||||
|
||||
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/`. Start with:
|
||||
- `@trigger.dev/sdk/docs/realtime/react-hooks/subscribe.mdx`
|
||||
+64
-57
@@ -1,67 +1,52 @@
|
||||
import * as fs from "node:fs/promises";
|
||||
import * as path from "node:path";
|
||||
|
||||
// Snapshots the curated docs that the bundled agent skills cite into the SDK package, so
|
||||
// AI coding agents can read the version-pinned reference directly from node_modules
|
||||
// (zero drift). Run as part of `@trigger.dev/sdk`'s build, from the package dir.
|
||||
// Snapshots the user-facing docs into the SDK package, so AI coding agents can read the
|
||||
// version-pinned reference directly from node_modules (zero drift). Run as part of
|
||||
// `@trigger.dev/sdk`'s build, from the package dir.
|
||||
//
|
||||
// The "manifest" is the union of every `sources:` entry across the SDK's bundled skills
|
||||
// (skills/*/SKILL.md). The skill declares what it needs; the build copies exactly that.
|
||||
// Add a `sources:` line to a skill and its doc ships automatically — nothing else to edit.
|
||||
// The manifest is the entire "Documentation" dropdown in `docs/docs.json` (the
|
||||
// "Resources for Trigger.dev" tab) — every page under it is bundled. Add a page to that
|
||||
// nav and it ships automatically; nothing else to edit. The API reference and
|
||||
// Guides & examples dropdowns are intentionally not bundled. Skills reference into this
|
||||
// set by path; their `sources:` frontmatter is informational and no longer drives bundling.
|
||||
//
|
||||
// Layout: a source `docs/tasks/overview.mdx` (relative to the repo root) is copied to
|
||||
// Layout: nav page `tasks/overview` is copied from `docs/tasks/overview.mdx` to
|
||||
// `<sdk>/docs/tasks/overview.mdx`, so a skill at `<sdk>/skills/<name>/SKILL.md` reaches it
|
||||
// at `../../docs/tasks/overview.mdx` and an agent reaches it at `@trigger.dev/sdk/docs/...`.
|
||||
|
||||
const packageDir = process.cwd(); // packages/trigger-sdk when run from the SDK build
|
||||
const repoRoot = path.resolve(packageDir, "..", "..");
|
||||
const skillsDir = path.join(packageDir, "skills");
|
||||
const docsRoot = path.join(repoRoot, "docs");
|
||||
const outDir = path.join(packageDir, "docs");
|
||||
|
||||
/** Pull the `sources:` list out of a SKILL.md YAML frontmatter block (simple line scan, no YAML dep). */
|
||||
async function readSkillSources(skillMdPath: string): Promise<string[]> {
|
||||
const txt = await fs.readFile(skillMdPath, "utf8");
|
||||
const fm = txt.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
||||
if (!fm) return [];
|
||||
const DROPDOWN = "Documentation";
|
||||
|
||||
const lines = fm[1].split(/\r?\n/);
|
||||
const sources: string[] = [];
|
||||
let inSources = false;
|
||||
|
||||
for (const line of lines) {
|
||||
if (/^sources:\s*$/.test(line)) {
|
||||
inSources = true;
|
||||
continue;
|
||||
}
|
||||
if (inSources) {
|
||||
const item = line.match(/^\s*-\s*(.+?)\s*$/);
|
||||
if (item) {
|
||||
sources.push(item[1]);
|
||||
continue;
|
||||
}
|
||||
// A non-list, non-blank line ends the block (next top-level key).
|
||||
if (line.trim() !== "") break;
|
||||
/** Recursively collect every page path under a docs.json nav node (groups -> pages, nested). */
|
||||
function collectPages(node: unknown): string[] {
|
||||
const out: string[] = [];
|
||||
if (node && typeof node === "object") {
|
||||
const n = node as { groups?: unknown[]; pages?: unknown[] };
|
||||
for (const g of n.groups ?? []) out.push(...collectPages(g));
|
||||
for (const p of n.pages ?? []) {
|
||||
if (typeof p === "string") out.push(p);
|
||||
else out.push(...collectPages(p));
|
||||
}
|
||||
}
|
||||
|
||||
return sources;
|
||||
return out;
|
||||
}
|
||||
|
||||
async function collectManifest(): Promise<string[]> {
|
||||
const entries = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
|
||||
const all = new Set<string>();
|
||||
const docsJson = JSON.parse(await fs.readFile(path.join(docsRoot, "docs.json"), "utf8"));
|
||||
const dropdowns: Array<{ dropdown?: string }> = docsJson?.navigation?.dropdowns ?? [];
|
||||
const documentation = dropdowns.find((d) => d.dropdown === DROPDOWN);
|
||||
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const skillMd = path.join(skillsDir, entry.name, "SKILL.md");
|
||||
const sources = await readSkillSources(skillMd).catch(() => []);
|
||||
for (const s of sources) {
|
||||
// Only bundle docs paths; ignore anything that isn't a docs/*.mdx source.
|
||||
if (s.startsWith("docs/") && s.endsWith(".mdx")) all.add(s);
|
||||
}
|
||||
if (!documentation) {
|
||||
throw new Error(`[bundleSdkDocs] "${DROPDOWN}" dropdown not found in docs/docs.json`);
|
||||
}
|
||||
|
||||
return [...all].sort();
|
||||
// Page paths are root-relative without extension (e.g. "tasks/overview"); map to docs/*.mdx.
|
||||
return [...new Set(collectPages(documentation))];
|
||||
}
|
||||
|
||||
async function bundleSdkDocs() {
|
||||
@@ -69,8 +54,7 @@ async function bundleSdkDocs() {
|
||||
// image), the repo-level docs/ tree is a separate workspace package that isn't part of that
|
||||
// build's dependency graph, so it isn't present. The SDK isn't being published there, so
|
||||
// there's nothing to bundle: skip rather than fail. Publishing always runs from the full
|
||||
// monorepo where docs/ exists, so the missing-docs guard below still protects releases.
|
||||
const docsRoot = path.join(repoRoot, "docs");
|
||||
// monorepo where docs/ exists, so the guards below still protect releases.
|
||||
try {
|
||||
await fs.access(docsRoot);
|
||||
} catch {
|
||||
@@ -81,41 +65,64 @@ async function bundleSdkDocs() {
|
||||
const manifest = await collectManifest();
|
||||
|
||||
if (manifest.length === 0) {
|
||||
// Fail the build rather than silently ship the SDK with stale or missing docs.
|
||||
throw new Error("[bundleSdkDocs] no doc sources found in skills/*/SKILL.md");
|
||||
// The nav structure changed shape; refuse to ship the SDK with no docs.
|
||||
throw new Error(`[bundleSdkDocs] no pages found under the "${DROPDOWN}" dropdown`);
|
||||
}
|
||||
|
||||
// Rebuild from scratch so removed sources don't linger in the package.
|
||||
// Rebuild from scratch so removed pages don't linger in the package.
|
||||
await fs.rm(outDir, { recursive: true, force: true });
|
||||
|
||||
const missing: string[] = [];
|
||||
let copied = 0;
|
||||
|
||||
for (const rel of manifest) {
|
||||
const src = path.join(repoRoot, rel);
|
||||
// Defensive: nav paths come from our own docs.json and are URL-style, but a
|
||||
// fat-fingered `../`, a backslash, or an absolute path shouldn't be able to copy a
|
||||
// file from outside docs/ into the package. Reject backslashes (Windows separator)
|
||||
// and both POSIX and Windows absolute forms, then the normalized `..` traversal.
|
||||
const safeRel = path.posix.normalize(rel);
|
||||
if (
|
||||
rel.includes("\\") ||
|
||||
path.posix.isAbsolute(rel) ||
|
||||
path.win32.isAbsolute(rel) ||
|
||||
safeRel.startsWith("..")
|
||||
) {
|
||||
throw new Error(`[bundleSdkDocs] invalid nav path "${rel}" under "${DROPDOWN}"`);
|
||||
}
|
||||
|
||||
const src = path.join(docsRoot, `${safeRel}.mdx`);
|
||||
try {
|
||||
await fs.access(src);
|
||||
} catch {
|
||||
// A nav entry pointing at a nonexistent page is a docs-nav issue, not a bundler one.
|
||||
// Warn and skip rather than fail the SDK build.
|
||||
missing.push(rel);
|
||||
continue;
|
||||
}
|
||||
// Strip the leading "docs/" so files land at <sdk>/docs/<subpath>.
|
||||
const dest = path.join(outDir, rel.slice("docs/".length));
|
||||
const dest = path.join(outDir, `${safeRel}.mdx`);
|
||||
await fs.mkdir(path.dirname(dest), { recursive: true });
|
||||
await fs.copyFile(src, dest);
|
||||
copied++;
|
||||
}
|
||||
|
||||
if (missing.length > 0) {
|
||||
console.error(
|
||||
`[bundleSdkDocs] ${missing.length} doc source(s) cited by a skill do not exist:\n` +
|
||||
missing.map((m) => ` - ${m}`).join("\n") +
|
||||
`\nFix the skill's sources: list or add the doc.`
|
||||
console.warn(
|
||||
`[bundleSdkDocs] ${missing.length} "${DROPDOWN}" nav page(s) have no .mdx and were skipped:\n` +
|
||||
missing.map((m) => ` - ${m}`).join("\n")
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`[bundleSdkDocs] bundled ${copied} docs into ${path.relative(repoRoot, outDir)}`);
|
||||
if (copied === 0) {
|
||||
// Every nav page was missing on disk; refuse to ship the SDK with an empty docs bundle.
|
||||
throw new Error(`[bundleSdkDocs] 0 docs copied from the "${DROPDOWN}" nav; refusing empty docs bundle`);
|
||||
}
|
||||
|
||||
console.log(
|
||||
`[bundleSdkDocs] bundled ${copied} docs from the "${DROPDOWN}" nav into ${path.relative(
|
||||
repoRoot,
|
||||
outDir
|
||||
)}`
|
||||
);
|
||||
}
|
||||
|
||||
bundleSdkDocs().catch((e) => {
|
||||
|
||||
Reference in New Issue
Block a user