Skip to content

Commit b96a0b7

Browse files
D-K-PD-K-P
authored
Docs: Clarify AI tool compatibility and expand context snippet (#3000)
This pull request overhauls the "Building with AI" documentation section. It includes a comprehensive restructuring of the main building-with-ai page with new setup guides and troubleshooting sections, reorganizes the navigation hierarchy to elevate mcp-agent-rules as a top-level page, and updates multiple documentation pages to clarify the relationships between three AI tools: Skills, Agent Rules, and MCP Server. Changes also include formatting improvements, such as replacing italicized text with inline code formatting, and consistent additions of explanatory Note blocks and CardGroup components across related pages.
1 parent 3bb9aac commit b96a0b7

File tree

6 files changed

+334
-53
lines changed

6 files changed

+334
-53
lines changed

‎docs/building-with-ai.mdx‎

Lines changed: 263 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,272 @@ sidebarTitle: "Overview"
44
description: "Tools and resources for building Trigger.dev projects with AI coding assistants."
55
---
66

7-
We provide tools to help you build Trigger.dev projects with AI coding assistants. We recommend using them for the best developer experience.
7+
## Quick setup
88

9-
<CardGroup cols={1}>
10-
<Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
11-
Give your AI assistant direct access to Trigger.dev tools - search docs, trigger tasks, deploy projects, and monitor runs.
9+
We provide multiple tools to help AI coding assistants write correct Trigger.dev code. Use one or all of them for the best developer experience.
10+
11+
12+
<Steps>
13+
14+
<Step title="Install the MCP Server">
15+
Give your AI assistant direct access to Trigger.dev tools — search docs, trigger tasks, deploy projects, and monitor runs. Works with Claude Code, Cursor, Windsurf, VS Code (Copilot), and Zed.
16+
17+
```bash
18+
npx trigger.dev@latest install-mcp
19+
```
20+
21+
[Learn more →](/mcp-introduction)
22+
</Step>
23+
24+
<Step title="Install Skills">
25+
Portable instruction sets that teach any AI coding assistant Trigger.dev best practices. Works with Claude Code, Cursor, Windsurf, VS Code (Copilot), and any tool that supports the [Agent Skills standard](https://agentskills.io).
26+
27+
```bash
28+
npx skills add triggerdotdev/skills
29+
```
30+
31+
[Learn more →](/skills)
32+
</Step>
33+
34+
<Step title="Install Agent Rules">
35+
Comprehensive rule sets installed directly into your AI client's config files. Works with Cursor, Claude Code, VS Code (Copilot), Windsurf, Gemini CLI, Cline, and more. Claude Code also gets a dedicated subagent for hands-on help.
36+
37+
```bash
38+
npx trigger.dev@latest install-rules
39+
```
40+
41+
[Learn more →](/mcp-agent-rules)
42+
</Step>
43+
44+
</Steps>
45+
46+
## Skills vs Agent Rules vs MCP
47+
48+
Not sure which tool to use? Here's how they compare:
49+
50+
| | **Skills** | **Agent Rules** | **MCP Server** |
51+
|:--|:-----------|:----------------|:---------------|
52+
| **What it does** | Drops skill files into your project | Installs rule sets into client config | Runs a live server your AI connects to |
53+
| **Installs to** | `.claude/skills/`, `.cursor/skills/`, etc. | `.cursor/rules/`, `CLAUDE.md`, `AGENTS.md`, etc. | `mcp.json`, `~/.claude.json`, etc. |
54+
| **Updates** | Re-run `npx skills add` | Re-run `npx trigger.dev@latest install-rules` or auto-prompted on `trigger dev` | Always latest (uses `@latest`) |
55+
| **Best for** | Teaching patterns and best practices | Comprehensive code generation guidance | Live project interaction (deploy, trigger, monitor) |
56+
| **Works offline** | Yes | Yes | No (calls Trigger.dev API) |
57+
58+
**Our recommendation:** Install all three. Skills and Agent Rules teach your AI *how* to write code. The MCP Server lets it *do things* in your project.
59+
60+
## Project-level context snippet
61+
62+
If you prefer a lightweight/passive approach, paste the snippet below into a context file at the root of your project. Different AI tools read different files:
63+
64+
| File | Read by |
65+
|:-----|:--------|
66+
| `CLAUDE.md` | Claude Code |
67+
| `AGENTS.md` | OpenAI Codex, Jules, OpenCode |
68+
| `.cursor/rules/*.md` | Cursor |
69+
| `.github/copilot-instructions.md` | GitHub Copilot |
70+
| `CONVENTIONS.md` | Windsurf, Cline, and others |
71+
72+
Create the file that matches your AI tool (or multiple files if your team uses different tools) and paste the snippet below. This gives the AI essential Trigger.dev context without installing anything.
73+
74+
<Accordion title="Copy the snippet">
75+
76+
````markdown
77+
# Trigger.dev rules
78+
79+
## Imports
80+
81+
Always import from `@trigger.dev/sdk` — never from `@trigger.dev/sdk/v3` or use the deprecated `client.defineJob` pattern.
82+
83+
## Task pattern
84+
85+
Every task must be exported. Use `task()` from `@trigger.dev/sdk`:
86+
87+
```ts
88+
import { task } from "@trigger.dev/sdk";
89+
90+
export const myTask = task({
91+
id: "my-task",
92+
retry: {
93+
maxAttempts: 3,
94+
factor: 1.8,
95+
minTimeoutInMs: 500,
96+
maxTimeoutInMs: 30_000,
97+
},
98+
run: async (payload: { url: string }) => {
99+
// No timeouts — runs can take as long as needed
100+
return { success: true };
101+
},
102+
});
103+
```
104+
105+
## Triggering tasks
106+
107+
From your backend (Next.js route, Express handler, etc.):
108+
109+
```ts
110+
import type { myTask } from "./trigger/my-task";
111+
import { tasks } from "@trigger.dev/sdk";
112+
113+
// Fire and forget
114+
const handle = await tasks.trigger<typeof myTask>("my-task", { url: "https://example.com" });
115+
116+
// Batch trigger (up to 1,000 items)
117+
const batchHandle = await tasks.batchTrigger<typeof myTask>("my-task", [
118+
{ payload: { url: "https://example.com/1" } },
119+
{ payload: { url: "https://example.com/2" } },
120+
]);
121+
```
122+
123+
### From inside other tasks
124+
125+
```ts
126+
export const parentTask = task({
127+
id: "parent-task",
128+
run: async (payload) => {
129+
// Fire and forget
130+
await childTask.trigger({ data: "value" });
131+
132+
// Wait for result — returns a Result object, NOT the output directly
133+
const result = await childTask.triggerAndWait({ data: "value" });
134+
if (result.ok) {
135+
console.log(result.output); // The actual return value
136+
} else {
137+
console.error(result.error);
138+
}
12139

13-
```bash
14-
npx trigger.dev@latest install-mcp
15-
```
140+
// Or use .unwrap() to get output directly (throws on failure)
141+
const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
142+
},
143+
});
144+
```
145+
146+
> Never wrap `triggerAndWait` or `batchTriggerAndWait` in `Promise.all` — this is not supported.
147+
148+
## Error handling
149+
150+
```ts
151+
import { task, retry, AbortTaskRunError } from "@trigger.dev/sdk";
152+
153+
export const resilientTask = task({
154+
id: "resilient-task",
155+
retry: { maxAttempts: 5 },
156+
run: async (payload) => {
157+
// Permanent error — skip retrying
158+
if (!payload.isValid) {
159+
throw new AbortTaskRunError("Invalid payload, will not retry");
160+
}
161+
162+
// Retry a specific block (not the whole task)
163+
const data = await retry.onThrow(
164+
async () => await fetchExternalApi(payload),
165+
{ maxAttempts: 3 }
166+
);
167+
168+
return data;
169+
},
170+
});
171+
```
172+
173+
## Schema validation
174+
175+
Use `schemaTask` with Zod for payload validation:
176+
177+
```ts
178+
import { schemaTask } from "@trigger.dev/sdk";
179+
import { z } from "zod";
180+
181+
export const processVideo = schemaTask({
182+
id: "process-video",
183+
schema: z.object({ videoUrl: z.string().url() }),
184+
run: async (payload) => {
185+
// payload is typed and validated
186+
},
187+
});
188+
```
189+
190+
## Waits
191+
192+
Use `wait.for` for delays, `wait.until` for dates, and `wait.forToken` for external callbacks:
193+
194+
```ts
195+
import { wait } from "@trigger.dev/sdk";
196+
await wait.for({ seconds: 30 });
197+
await wait.until({ date: new Date("2025-01-01") });
198+
```
199+
200+
## Configuration
201+
202+
`trigger.config.ts` lives at the project root:
203+
204+
```ts
205+
import { defineConfig } from "@trigger.dev/sdk/build";
206+
207+
export default defineConfig({
208+
project: "<your-project-ref>",
209+
dirs: ["./trigger"],
210+
});
211+
```
212+
213+
## Common mistakes
214+
215+
1. **Forgetting to export tasks** — every task must be a named export
216+
2. **Importing from `@trigger.dev/sdk/v3`** — this is the old v3 path; always use `@trigger.dev/sdk`
217+
3. **Using `client.defineJob()`** — this is the deprecated v2 API
218+
4. **Calling `task.trigger()` directly** — use `tasks.trigger<typeof myTask>("task-id", payload)` from your backend
219+
5. **Using `triggerAndWait` result as output** — it returns a `Result` object; check `result.ok` then access `result.output`, or use `.unwrap()`
220+
6. **Wrapping waits/triggerAndWait in `Promise.all`** — not supported in Trigger.dev tasks
221+
7. **Adding timeouts to tasks** — tasks have no built-in timeout; use `maxDuration` in config if needed
222+
````
223+
224+
</Accordion>
225+
226+
## llms.txt
227+
228+
We also publish machine-readable documentation for LLM consumption:
229+
230+
- [trigger.dev/docs/llms.txt](https://trigger.dev/docs/llms.txt) — concise overview
231+
- [trigger.dev/docs/llms-full.txt](https://trigger.dev/docs/llms-full.txt) — full documentation
232+
233+
These follow the [llms.txt standard](https://llmstxt.org) and can be fed directly into any LLM context window.
234+
235+
236+
## Troubleshooting
237+
238+
<AccordionGroup>
239+
240+
<Accordion title="AI keeps generating old v2/v3 code">
241+
Install [Agent Rules](/mcp-agent-rules) or [Skills](/skills) — they override the outdated patterns in the AI's training data. The [context snippet](#project-level-context-snippet) above is a quick alternative.
242+
</Accordion>
243+
244+
<Accordion title="MCP server won't connect">
245+
1. Make sure you've restarted your AI client after adding the config
246+
2. Run `npx trigger.dev@latest install-mcp` again — it will detect and fix common issues
247+
3. Check that `npx trigger.dev@latest mcp` runs without errors in your terminal
248+
4. See the [MCP introduction](/mcp-introduction) for client-specific config details
249+
</Accordion>
250+
251+
<Accordion title="Which tool should I install?">
252+
All three if possible. If you can only pick one:
253+
- **Agent Rules** if you want the broadest code generation improvement
254+
- **Skills** if you use multiple AI tools and want a single install
255+
- **MCP Server** if you need to trigger tasks, deploy, and search docs from your AI
256+
</Accordion>
257+
258+
</AccordionGroup>
259+
260+
## Next steps
261+
262+
<CardGroup cols={2}>
263+
<Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
264+
Install and configure the MCP Server for live project interaction.
16265
</Card>
17266
<Card title="Skills" icon="wand-magic-sparkles" href="/skills">
18-
Portable instruction sets that teach any AI coding assistant Trigger.dev best practices for writing tasks, configs, and more.
19-
20-
```bash
21-
npx skills add triggerdotdev/skills
22-
```
267+
Portable instruction sets for any AI coding assistant.
268+
</Card>
269+
<Card title="Agent Rules" icon="scroll" href="/mcp-agent-rules">
270+
Comprehensive rule sets installed into your AI client.
271+
</Card>
272+
<Card title="Writing tasks" icon="code" href="/tasks/overview">
273+
Learn the task patterns your AI assistant will follow.
23274
</Card>
24275
</CardGroup>

‎docs/docs.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,10 @@
4949
"building-with-ai",
5050
{
5151
"group": "MCP Server",
52-
"pages": ["mcp-introduction", "mcp-tools", "mcp-agent-rules"]
52+
"pages": ["mcp-introduction", "mcp-tools"]
5353
},
54-
"skills"
54+
"skills",
55+
"mcp-agent-rules"
5556
]
5657
},
5758
{

‎docs/mcp-agent-rules.mdx‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
---
22
title: "Agent rules"
33
sidebarTitle: "Agent rules"
4-
description: "Learn how to use the Trigger.dev agent rules with the MCP server"
4+
description: "Install Trigger.dev agent rules to guide AI assistants toward correct, up-to-date code patterns."
55
---
66

77
## What are Trigger.dev agent rules?
88

99
Trigger.dev agent rules are comprehensive instruction sets that guide AI assistants to write optimal Trigger.dev code. These rules ensure your AI assistant understands best practices, current APIs, and recommended patterns when working with Trigger.dev projects.
1010

11+
<Note>
12+
Agent Rules are one of three AI tools we provide. You can also install [Skills](/skills) for portable cross-editor instruction sets or the [MCP Server](/mcp-introduction) for live project interaction. See the [comparison table](/building-with-ai#skills-vs-agent-rules-vs-mcp) for details.
13+
</Note>
14+
1115
## Installation
1216

1317
Install the agent rules with the following command:
@@ -112,6 +116,17 @@ npx trigger.dev@latest install-rules
112116

113117
## Next steps
114118

115-
- [Install the MCP server](/mcp-introduction) for complete Trigger.dev integration
116-
- [Explore MCP tools](/mcp-tools) for project management and task execution
117-
119+
<CardGroup cols={2}>
120+
<Card title="Skills" icon="wand-magic-sparkles" href="/skills">
121+
Portable instruction sets that work across all AI coding assistants.
122+
</Card>
123+
<Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
124+
Give your AI assistant direct access to Trigger.dev tools and APIs.
125+
</Card>
126+
<Card title="Complete AI setup" icon="layer-group" href="/building-with-ai">
127+
See all AI tools and how they compare.
128+
</Card>
129+
<Card title="Writing tasks" icon="code" href="/tasks/overview">
130+
Learn the task patterns that agent rules teach your AI assistant.
131+
</Card>
132+
</CardGroup>

‎docs/mcp-introduction.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,4 +361,14 @@ Once installed, you can start using the MCP server by asking your AI assistant q
361361

362362
## Next Steps
363363

364-
- [Explore available MCP tools](/mcp-tools)
364+
<CardGroup cols={2}>
365+
<Card title="MCP Tools" icon="wrench" href="/mcp-tools">
366+
Explore all available MCP tools for managing your projects.
367+
</Card>
368+
<Card title="Skills" icon="wand-magic-sparkles" href="/skills">
369+
Portable instruction sets that teach AI assistants Trigger.dev patterns.
370+
</Card>
371+
<Card title="Agent Rules" icon="scroll" href="/mcp-agent-rules">
372+
Install comprehensive rule sets directly into your AI client.
373+
</Card>
374+
</CardGroup>

0 commit comments

Comments
 (0)