playbooks

home / skills / petekp / claude-code-setup / ai-sdk

ai-sdk skill

/skills/ai-sdk

This skill answers questions about the AI SDK and helps build AI-powered features by guiding integration, debugging, and provider usage.

This is most likely a fork of the use-ai-sdk skill from vercel
npx playbooks add skill petekp/claude-code-setup --skill ai-sdk

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
4.6 KB
---
name: ai-sdk
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, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".'
---

## Prerequisites

Before searching docs, check if `node_modules/ai/docs/` exists. If not, install **only** the `ai` package using the project's package manager (e.g., `pnpm add ai`).

Do not install other packages at this stage. Provider packages (e.g., `@ai-sdk/openai`) and client packages (e.g., `@ai-sdk/react`) should be installed later when needed based on user requirements.

## Critical: Do Not Trust Internal Knowledge

Everything you know about the AI SDK is outdated or wrong. Your training data contains obsolete APIs, deprecated patterns, and incorrect usage.

**When working with the AI SDK:**

1. Ensure `ai` package is installed (see Prerequisites)
2. Search `node_modules/ai/docs/` and `node_modules/ai/src/` for current APIs
3. If not found locally, search ai-sdk.dev documentation (instructions below)
4. Never rely on memory - always verify against source code or docs
5. **`useChat` has changed significantly** - check [Common Errors](references/common-errors.md) before writing client code
6. When deciding which model and provider to use (e.g. OpenAI, Anthropic, Gemini), use the Vercel AI Gateway provider unless the user specifies otherwise. See [AI Gateway Reference](references/ai-gateway.md) for usage details.
7. **Always fetch current model IDs** - Never use model IDs from memory. Before writing code that uses a model, run `curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("provider/")) | .id] | reverse | .[]'` (replacing `provider` with the relevant provider like `anthropic`, `openai`, or `google`) to get the full list with newest models first. Use the model with the highest version number (e.g., `claude-sonnet-4-5` over `claude-sonnet-4` over `claude-3-5-sonnet`).
8. Run typecheck after changes to ensure code is correct
9. **Be minimal** - Only specify options that differ from defaults. When unsure of defaults, check docs or source rather than guessing or over-specifying.

If you cannot find documentation to support your answer, state that explicitly.

## Finding Documentation

### [email protected]+

Search bundled docs and source in `node_modules/ai/`:

- **Docs**: `grep "query" node_modules/ai/docs/`
- **Source**: `grep "query" node_modules/ai/src/`

Provider packages include docs at `node_modules/@ai-sdk/<provider>/docs/`.

### Earlier versions

1. Search: `https://ai-sdk.dev/api/search-docs?q=your_query`
2. Fetch `.md` URLs from results (e.g., `https://ai-sdk.dev/docs/agents/building-agents.md`)

## When Typecheck Fails

**Before searching source code**, grep [Common Errors](references/common-errors.md) for the failing property or function name. Many type errors are caused by deprecated APIs documented there.

If not found in common-errors.md:

1. Search `node_modules/ai/src/` and `node_modules/ai/docs/`
2. Search ai-sdk.dev (for earlier versions or if not found locally)

## Building and Consuming Agents

### Creating Agents

Always use the `ToolLoopAgent` pattern. Search `node_modules/ai/docs/` for current agent creation APIs.

**File conventions**: See [type-safe-agents.md](references/type-safe-agents.md) for where to save agents and tools.

**Type Safety**: When consuming agents with `useChat`, always use `InferAgentUIMessage<typeof agent>` for type-safe tool results. See [reference](references/type-safe-agents.md).

### Consuming Agents (Framework-Specific)

Before implementing agent consumption:

1. Check `package.json` to detect the project's framework/stack
2. Search documentation for the framework's quickstart guide
3. Follow the framework-specific patterns for streaming, API routes, and client integration

## References

- [Common Errors](references/common-errors.md) - Renamed parameters reference (parameters → inputSchema, etc.)
- [AI Gateway](references/ai-gateway.md) - Gateway setup and usage
- [Type-Safe Agents with useChat](references/type-safe-agents.md) - End-to-end type safety with InferAgentUIMessage
- [DevTools](references/devtools.md) - Set up local debugging and observability (development only)

Overview

This skill helps developers answer questions about the AI SDK and build AI-powered features using its functions and provider integrations. It focuses on usage patterns for generateText, streamText, ToolLoopAgent, tools, and provider-specific options. The goal is to accelerate building agents, chatbots, and structured-output workflows with practical guidance.

How this skill works

I inspect the AI SDK documentation and source layout to locate relevant API details and examples. For recent SDK versions ([email protected]+), I direct you to the bundled docs and source in node_modules and explain how to grep or glob for specific files. For other versions I point to the public docs search and direct .md endpoints for authoritative content. I also highlight where provider-specific options live so you can tune model calls.

When to use it

  • You need to implement text generation or streaming responses (generateText, streamText).
  • You are building or debugging an agent or ToolLoopAgent workflow.
  • You must integrate or troubleshoot provider-specific options (OpenAI, Anthropic, Google, etc.).
  • You want examples of tool calling, structured output, or multi-step agent orchestration.
  • You need quick pointers to SDK docs and source in your project for up-to-date behavior.

Best practices

  • Update to the latest ai package when possible to match docs and examples.
  • Search bundled package docs and source for precise, versioned API behavior rather than relying on third-party summaries.
  • Review provider-specific packages for providerOptions and example usage before changing model parameters.
  • Prefer streaming APIs for low-latency user experiences and use structured output tooling for reliable parsing.
  • Write small reproductions when debugging agent behavior to isolate tool calls and state transitions.

Example use cases

  • Implement a chatbot using generateText for responses and streamText for progressive display.
  • Create a ToolLoopAgent that calls external tools and records tool outputs for follow-up reasoning.
  • Tune providerOptions for latency vs. cost trade-offs when switching between OpenAI and Anthropic backends.
  • Build structured JSON output from model responses and validate with the SDK’s parsing utilities.
  • Search the installed node_modules docs to find exact function signatures and example snippets for your SDK version.

FAQ

How do I find provider-specific options for a model call?

Look in the corresponding provider package docs and source (node_modules/@ai-sdk/<provider>/docs and /src) for providerOptions and examples.

What if the docs in my project don’t match online docs?

Prefer the bundled docs and source in your installed version; if needed, update the ai package to align behavior with the latest documentation.