Skip to content

Commit 1009e79

Browse files
lgrammelnicoalbanese
lgrammel
and
nicoalbanese
authored
chore(ai): bootstrap SKILL.md (#11949)
## Background [Agent skills](https://agentskills.io/specification) are a standard for defining files that help coding agents perform tasks. An AI SDK skill can help improve the usage of the AI SDK by such agents. ## Summary Add basic skill to `packages/ai` folder. ## Future Work * add content to skill * add references with edge cases and errors * publish skill (automated pipeline) ## Related Issues Related to #11175 --------- Co-authored-by: nicoalbanese <[email protected]>
1 parent 3237118 commit 1009e79

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

‎packages/ai/skill/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: ai-sdk
3+
description: Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, or tools, (2) Want to build AI agents, chatbots, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, etc.), streaming, tool calling, or structured output.
4+
metadata:
5+
author: Vercel Inc.
6+
version: '1.0'
7+
---
8+
9+
## AI SDK Usage
10+
11+
When you need up-to-date information about the AI SDK, search the bundled documentation and source code in `node_modules/ai/`:
12+
13+
1. **Documentation**: `grep "your query" node_modules/ai/docs/`
14+
2. **Source code**: `grep "your query" node_modules/ai/src/`
15+
16+
To find specific files:
17+
18+
- `glob "node_modules/ai/docs/**/*.mdx"` for documentation files
19+
- `glob "node_modules/ai/src/**/*.ts"` for source files
20+
21+
Use these resources for current API details, usage patterns, and examples.
22+
23+
For common errors and troubleshooting, see [Common Errors Reference](references/common-errors.md).
24+
25+
## Provider-Specific Information
26+
27+
For questions about specific providers (OpenAI, Anthropic, Google, etc.), search their dedicated packages:
28+
29+
1. **Provider documentation**: `grep "your query" node_modules/@ai-sdk/<provider>/docs/`
30+
2. **Provider source code**: `grep "your query" node_modules/@ai-sdk/<provider>/src/`
31+
32+
To find provider files:
33+
34+
- `glob "node_modules/@ai-sdk/<provider>/docs/**/*.mdx"` for provider documentation
35+
- `glob "node_modules/@ai-sdk/<provider>/src/**/*.ts"` for provider source files
36+
37+
This is especially important for `providerOptions`, which are provider-specific settings passed to model calls. Each provider has unique options documented in their package.

‎packages/ai/skill/references/common-errors.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Common Errors
3+
description: Reference for common AI SDK errors and how to resolve them.
4+
---
5+
6+
# Common Errors
7+
8+
## `maxTokens` → `maxOutputTokens`
9+
10+
```typescript
11+
// ❌ Incorrect
12+
const result = await generateText({
13+
model: 'anthropic/claude-opus-4.5',
14+
maxTokens: 512,
15+
prompt: 'Write a short story',
16+
});
17+
18+
// ✅ Correct
19+
const result = await generateText({
20+
model: 'anthropic/claude-opus-4.5',
21+
maxOutputTokens: 512,
22+
prompt: 'Write a short story',
23+
});
24+
```
25+
26+
## `maxSteps` → `stopWhen: stepCountIs(n)`
27+
28+
```typescript
29+
// ❌ Incorrect
30+
const result = await generateText({
31+
model: 'anthropic/claude-opus-4.5',
32+
tools: { weather },
33+
maxSteps: 5,
34+
prompt: 'What is the weather in NYC?',
35+
});
36+
37+
// ✅ Correct
38+
import { generateText, stepCountIs } from 'ai';
39+
40+
const result = await generateText({
41+
model: 'anthropic/claude-opus-4.5',
42+
tools: { weather },
43+
stopWhen: stepCountIs(5),
44+
prompt: 'What is the weather in NYC?',
45+
});
46+
```
47+
48+
## `parameters` → `inputSchema` (in tool definition)
49+
50+
```typescript
51+
// ❌ Incorrect
52+
const weatherTool = tool({
53+
description: 'Get weather for a location',
54+
parameters: z.object({
55+
location: z.string(),
56+
}),
57+
execute: async ({ location }) => ({ location, temp: 72 }),
58+
});
59+
60+
// ✅ Correct
61+
const weatherTool = tool({
62+
description: 'Get weather for a location',
63+
inputSchema: z.object({
64+
location: z.string(),
65+
}),
66+
execute: async ({ location }) => ({ location, temp: 72 }),
67+
});
68+
```
69+
70+
## `generateObject` → `generateText` with `output`
71+
72+
`generateObject` is deprecated. Use `generateText` with the `output` option instead.
73+
74+
```typescript
75+
// ❌ Deprecated
76+
import { generateObject } from 'ai';
77+
78+
const result = await generateObject({
79+
model: 'anthropic/claude-opus-4.5',
80+
schema: z.object({
81+
recipe: z.object({
82+
name: z.string(),
83+
ingredients: z.array(z.string()),
84+
}),
85+
}),
86+
prompt: 'Generate a recipe for chocolate cake',
87+
});
88+
89+
// ✅ Correct
90+
import { generateText, Output } from 'ai';
91+
92+
const result = await generateText({
93+
model: 'anthropic/claude-opus-4.5',
94+
output: Output.object({
95+
schema: z.object({
96+
recipe: z.object({
97+
name: z.string(),
98+
ingredients: z.array(z.string()),
99+
}),
100+
}),
101+
}),
102+
prompt: 'Generate a recipe for chocolate cake',
103+
});
104+
105+
console.log(result.output); // typed object
106+
```
107+
108+
## Manual JSON parsing → `generateText` with `output`
109+
110+
```typescript
111+
// ❌ Incorrect
112+
const result = await generateText({
113+
model: 'anthropic/claude-opus-4.5',
114+
prompt: `Extract the user info as JSON: { "name": string, "age": number }
115+
116+
Input: John is 25 years old`,
117+
});
118+
const parsed = JSON.parse(result.text);
119+
120+
// ✅ Correct
121+
import { generateText, Output } from 'ai';
122+
123+
const result = await generateText({
124+
model: 'anthropic/claude-opus-4.5',
125+
output: Output.object({
126+
schema: z.object({
127+
name: z.string(),
128+
age: z.number(),
129+
}),
130+
}),
131+
prompt: 'Extract the user info: John is 25 years old',
132+
});
133+
134+
console.log(result.output); // { name: 'John', age: 25 }
135+
```
136+
137+
## Other `output` options
138+
139+
```typescript
140+
// Output.array - for generating arrays of items
141+
const result = await generateText({
142+
model: 'anthropic/claude-opus-4.5',
143+
output: Output.array({
144+
element: z.object({
145+
city: z.string(),
146+
country: z.string(),
147+
}),
148+
}),
149+
prompt: 'List 5 capital cities',
150+
});
151+
152+
// Output.choice - for selecting from predefined options
153+
const result = await generateText({
154+
model: 'anthropic/claude-opus-4.5',
155+
output: Output.choice({
156+
options: ['positive', 'negative', 'neutral'] as const,
157+
}),
158+
prompt: 'Classify the sentiment: I love this product!',
159+
});
160+
161+
// Output.json - for untyped JSON output
162+
const result = await generateText({
163+
model: 'anthropic/claude-opus-4.5',
164+
output: Output.json(),
165+
prompt: 'Return some JSON data',
166+
});
167+
```

0 commit comments

Comments
 (0)