@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/skills.mdx

@@ -0,0 +1,85 @@
+---
+title: "Skills"
+description: "Install Trigger.dev agent skills to teach any AI coding assistant how to write tasks, realtime frontends, and chat.agent AI agents."
+sidebarTitle: "Skills"
+---
+
+## What are agent skills?
+
+Skills are portable instruction sets that teach AI coding assistants how to use Trigger.dev effectively. Unlike vendor-specific config files (`.cursor/rules`, `CLAUDE.md`), skills use an open standard that works across all major AI assistants, so Cursor users and Claude Code users get the same knowledge from a single install.
+
+Each skill is a directory containing a `SKILL.md` file: YAML frontmatter (name, description) plus markdown instructions with patterns, examples, and common mistakes that AI assistants discover on demand and follow.
+
+<Note>
+  Skills pair with the [MCP Server](/mcp-introduction), which gives your assistant live access to
+  your project (deploy, trigger, monitor). Skills teach it how to write the code; the MCP server
+  lets it act on your project. See [how they fit together](/building-with-ai#skills-and-the-mcp-server).
+</Note>
+
+## Installation
+
+Run the installer with the CLI:
+
+```bash
+npx trigger.dev@latest skills
+```
+
+The CLI detects your installed AI tools, lets you pick which skills to install, and writes each one into that tool's native skills directory (`.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/`). It also adds a one-line pointer to your primary instructions file (`CLAUDE.md`, `.cursor/rules`, etc.) so your assistant always knows the skills are there and loads the right one on demand.
+
+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 `trigger-getting-started` skill is self-contained, since it runs before the SDK is installed.
+
+### Non-interactive install
+
+Pass `--target` to choose tools and `-y` to install every skill without prompting (useful in scripts and CI):
+
+```bash
+npx trigger.dev@latest skills --target claude-code --target cursor -y
+```
+
+## Available skills
+
+| Skill                  | Use for                                                        | Covers                                                                       |
+| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `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 `trigger-authoring-tasks`; it covers the most common patterns for writing Trigger.dev tasks.
+
+## Supported AI assistants
+
+Skills use the open [Agent Skills standard](https://agentskills.io). The CLI installs natively into the tools that support a skills directory today:
+
+| Assistant | Installs to |
+| --- | --- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `.claude/skills/` |
+| [Cursor](https://cursor.com) | `.cursor/skills/` |
+| [GitHub Copilot (VS Code)](https://github.com/features/copilot) | `.github/skills/` |
+| [Codex CLI](https://github.com/openai/codex), Jules, OpenCode | `.agents/skills/` |
+
+Using a tool that does not support skills yet? Select "Unsupported target" in the installer for manual setup instructions.
+
+## Keeping skills updated
+
+The API guidance updates on its own: it lives in `@trigger.dev/sdk` and is read from `node_modules`, so upgrading the SDK in your project upgrades the guidance with it. Re-run `npx trigger.dev@latest skills` (or accept the prompt that `trigger dev` shows when a newer version is available) only to add skills or refresh the installed pointer files. Re-running overwrites them in place without creating duplicates.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
+    Give your AI assistant direct access to Trigger.dev tools and APIs.
+  </Card>
+  <Card title="Building with AI" icon="layer-group" href="/building-with-ai">
+    See how skills and the MCP server compare, plus a copy-paste context snippet.
+  </Card>
+  <Card title="Writing tasks" icon="code" href="/tasks/overview">
+    Learn the task patterns that skills teach your AI assistant.
+  </Card>
+  <Card title="AI agents" icon="robot" href="/ai-chat/overview">
+    Build durable chat agents with chat.agent, the focus of two of the skills.
+  </Card>
+</CardGroup>

package/docs/tags.mdx

@@ -0,0 +1,120 @@
+---
+title: "Tags"
+description: "Tags allow you to easily filter runs in the dashboard and when using the SDK."
+---
+
+## What are tags?
+
+We support up to 10 tags per run. Each one must be a string between 1 and 128 characters long.
+
+We recommend prefixing your tags with their type and then an underscore or colon. For example, `user_123456` or `video:123`.
+
+<Info>
+  Many great APIs, like Stripe, already prefix their IDs with the type and an underscore. Like
+  `cus_123456` for a customer.
+</Info>
+
+We don't enforce prefixes but if you use them you'll find it easier to filter and it will be clearer what the tag represents.
+
+## How to add tags
+
+There are two ways to add tags to a run:
+
+1. When triggering the run.
+2. Inside the `run` function, using `tags.add()`.
+
+### 1. Adding tags when triggering the run
+
+You can add tags when triggering a run using the `tags` option. All the different [trigger](/triggering) methods support this.
+
+<CodeGroup>
+
+```ts trigger
+const handle = await myTask.trigger(
+  { message: "hello world" },
+  { tags: ["user_123456", "org_abcdefg"] }
+);
+```
+
+```ts batchTrigger
+const batch = await myTask.batchTrigger([
+  {
+    payload: { message: "foo" },
+    options: { tags: "product_123456" },
+  },
+  {
+    payload: { message: "bar" },
+    options: { tags: ["user_123456", "product_3456789"] },
+  },
+]);
+```
+
+</CodeGroup>
+
+This will create a run with the tags `user_123456` and `org_abcdefg`. They look like this in the runs table:
+
+![How tags appear in the dashboard](/images/tags-org-user.png)
+
+### 2. Adding tags inside the `run` function
+
+Use the `tags.add()` function to add tags to a run from inside the `run` function. This will add the tag `product_1234567` to the run:
+
+```ts
+import { task, tags } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: { message: string }, { ctx }) => {
+    // Get the tags from when the run was triggered using the context
+    // This is not updated if you add tags during the run
+    logger.log("Tags from the run context", { tags: ctx.run.tags });
+
+    // Add tags during the run (a single string or array of strings)
+    await tags.add("product_1234567");
+  },
+});
+```
+
+Reminder: you can only have up to 10 tags per run. If you call `tags.add()` and the total number of tags will be more than 10 we log an error and ignore the new tags. That includes tags from triggering and from inside the run function.
+
+### Propagating tags to child runs
+
+Tags do not propagate to child runs automatically. By default runs have no tags and you have to set them explicitly.
+
+It's easy to propagate tags if you want:
+
+```ts
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: Payload, { ctx }) => {
+    // Pass the tags from ctx into the child run
+    const { id } = await otherTask.trigger(
+      { message: "triggered from myTask" },
+      { tags: ctx.run.tags }
+    );
+  },
+});
+```
+
+## Filtering runs by tags
+
+You can filter runs by tags in the dashboard and in the SDK.
+
+### In the dashboard
+
+On the Runs page open the filter menu, choose "Tags" and then start typing in the name of the tag you want to filter by. You can select it and it will restrict the results to only runs with that tag. You can add multiple tags to filter by more than one.
+
+![Filter by tags](/images/tags-filtering.png)
+
+### Using `runs.list()`
+
+You can provide filters to the `runs.list` SDK function, including an array of tags.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+// Loop through all runs with the tag "user_123456" that have completed
+for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })) {
+  console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
+}
+```