Skills

Runstack ships with agent skills — packaged instructions in .agents/skills/ that teach AI coding assistants how to use Runstack's tools, APIs, and patterns correctly. Skills solve a core problem: LLMs have stale training data about APIs. A skill overrides that stale knowledge with authoritative, up-to-date instructions.

Available Skills

ai-sdk

Path: .agents/skills/ai-sdk/SKILL.md

Teaches agents how to build AI-powered features using the Vercel AI SDK and the runstack-tools npm package.

Covers:

• generateText, streamText, ToolLoopAgent, embeddings, tool calling
• React hooks (useChat, useCompletion)
• Provider setup (OpenAI, Anthropic, Google via AI Gateway)
• Type-safe agent patterns with InferAgentUIMessage
• Common migration errors (renamed parameters, deprecated APIs)

Included references:

• references/ai-gateway.md — Vercel AI Gateway provider setup
• references/common-errors.md — Renamed parameters and breaking changes
• references/type-safe-agents.md — End-to-end type safety with useChat
• references/devtools.md — Local debugging and observability

mcp-builder

Path: .agents/skills/mcp-builder/SKILL.md

Teaches agents how to create production-grade MCP servers that integrate with Runstack.

Covers:

• Designing tools for LLM consumption (naming, discoverability, context management)
• MCP protocol specification (transports, tool/resource/prompt definitions)
• Building servers in Python (FastMCP) and Node/TypeScript (MCP SDK)
• Evaluation and testing strategies

Included references:

• reference/mcp_best_practices.md — Design principles for MCP tools
• reference/node_mcp_server.md — TypeScript MCP server implementation
• reference/python_mcp_server.md — Python MCP server implementation
• reference/evaluation.md — Evaluation strategies
• scripts/ — Evaluation scripts and connection helpers

Using Skills

Claude Code

Skills in .agents/skills/ are automatically discovered. No configuration needed — just ask Claude to work with Runstack and the relevant skill is loaded:

You: "Build a chat endpoint using the AI SDK with Runstack tools"
Claude: [loads ai-sdk skill, reads references, builds correctly]

Cursor

Reference the skill file in your prompt or add it to .cursorrules:

@.agents/skills/ai-sdk/SKILL.md Build an agent that uses Runstack tools

Windsurf / Other Editors

Most AI-powered editors support referencing files as context. Point them at the SKILL.md:

Use the instructions in .agents/skills/ai-sdk/SKILL.md to build this feature

Custom Agents

Load the skill content as system instructions for your agent:

import { readFileSync } from 'fs';
import { generateText } from 'ai';
import { runstackTools } from 'runstack-tools';

const skill = readFileSync('.agents/skills/ai-sdk/SKILL.md', 'utf-8');

await generateText({
  model: yourModel,
  system: skill,
  prompt: userPrompt,
  tools: runstackTools(process.env.RUNSTACK_API_KEY!),
});

As MCP Tool Context

When building an MCP server that wraps or extends Runstack, load mcp-builder as context for your development workflow:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const runstack = new Client({ name: 'my-agent', version: '1.0.0' });

await runstack.connect(
  new StreamableHTTPClientTransport(
    new URL('https://app.runstack.engineer/mcp'),
    {
      requestInit: {
        headers: { Authorization: 'Bearer rsk_YOUR_API_KEY' },
      },
    },
  ),
);

How Skills Relate to Runstack Surfaces

Skills complement the three integration methods Runstack provides:

All three use the same 4 meta tools and the same agent workflow:

1. search_tools(pattern)            → discover the right tool
2. check_authentication(toolName)   → verify OAuth connection
3. initiate_connection(provider)    → get OAuth link if needed
4. execute_tool(toolName, args)     → run the tool

Skills teach agents to follow this workflow correctly, handle auth flows gracefully, and avoid common pitfalls like passing auth tokens manually or skipping the discovery step.

Creating Custom Skills

Add your own skills for project-specific patterns.

Directory Structure

.agents/skills/
  my-skill/
    SKILL.md           # Main skill definition (required)
    references/        # Supporting docs (optional)
      api-docs.md
      examples.md

SKILL.md Format

---
name: my-skill
description: >
  One-paragraph description of when this skill should be activated.
  Include trigger phrases so agents know when to load it.
---

## Instructions

Write as instructions to an AI agent — what to do, what to avoid,
where to find reference material.

## References

- [API Docs](references/api-docs.md)
- [Examples](references/examples.md)

Tips

• Be explicit about stale knowledge. If the agent's training data is likely wrong about your APIs, say so and point to authoritative sources.
• Include error handling guidance. Document common mistakes and their fixes.
• Keep references separate. Detailed docs go in references/ so the main SKILL.md stays focused.
• Use trigger keywords in the description. This helps agents decide when to load the skill automatically.