DEV Community: Magnus Rødseth

How Claude Skills Replaced Our Documentation

Magnus Rødseth — Thu, 05 Mar 2026 07:49:58 +0000

Why encoding codebase patterns as AI instructions works better than writing docs nobody reads.

Every developer knows the documentation paradox: you spend hours writing docs explaining how your codebase works, then your teammate (or your future self) ignores them and asks ChatGPT instead. The AI gives a plausible but wrong answer, because it doesn't know your specific patterns. So you debug for an hour, realize the AI hallucinated your auth flow, and write more documentation that nobody will read.

I broke out of this cycle by replacing most of my traditional documentation with Claude skills: structured instructions that teach AI how this specific codebase works.

The result: AI that follows my architecture instead of guessing. Consistent code across contributors. And documentation that's actually used, because the consumer is a machine that reads everything.

The Problem: AI Without Context

Modern AI coding assistants are remarkably capable at generic tasks. Ask Claude to "add a REST endpoint" and you'll get clean, working code. But it won't match YOUR patterns.

In my codebase, API routes use Elysia with specific validation patterns. Database queries go through Drizzle ORM with a particular transaction style. Background jobs use Inngest with step-level checkpointing. Auth checks follow a specific middleware pattern.

Without context, Claude produces code that works but doesn't belong. It may use Express conventions in an Elysia codebase. It writes raw SQL instead of using the ORM. It puts business logic in API routes instead of service functions.

The code passes type-checking but creates architectural drift. Over weeks, your codebase becomes a patchwork of conflicting patterns. Some human-written, some AI-generated, all slightly different.

What Claude Skills Are

A Claude skill is a markdown file in .claude/skills/ that encodes a specific pattern or workflow. When Claude encounters a relevant task, it reads the skill and follows the prescribed approach.

Here's a simplified example of a skill for adding API routes:

---
name: skill-name
description: A description of when to trigger this skill, e.g. whenever backend changes
---

# Adding API Routes (Elysia)

## Pattern

All API routes follow this structure:

1. Define route in `src/server/routes/`
2. Use Elysia's type-safe body validation
3. Check auth via `auth.api.getSession({ headers: request.headers })`
4. Return consistent response shapes: `{ data }` on success, throw on error
5. Register route in `src/server/api.ts`

## Example

typescript
// src/server/routes/bookmarks.ts
import { Elysia, t } from "elysia";
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { bookmarks } from "@/lib/db/schema";

export const bookmarkRoutes = new Elysia({ prefix: "/bookmarks" })
.get("/", async ({ request }) => {
const session = await auth.api.getSession({
headers: request.headers,
});
if (!session) throw new Error("Unauthorized");

const results = await db
  .select()
  .from(bookmarks)
  .where(eq(bookmarks.userId, session.user.id));

return { data: results };

});


## Anti-patterns

- Do NOT use Express-style `req, res` parameters
- Do NOT put database queries directly in route handlers for complex logic
- Do NOT skip auth checks on protected routes

This isn't documentation in the traditional sense. It's an instruction set optimized for an AI reader. Explicit patterns, concrete examples, clear anti-patterns.

Why This Works Better Than Documentation

1. The consumer actually reads it

Human developers skim docs, search for the snippet they need, copy-paste, and move on. Claude reads the entire skill every time. It doesn't skip sections. It doesn't assume it already knows. Every instruction is followed.

2. It enforces consistency

When three developers work on a codebase, you get three slightly different patterns. When those developers work with Claude skills, you get one pattern replicated exactly.

Ask Claude to "add user profiles with database table, API endpoint, and settings page." It reads the relevant skills for database schemas, API routes, and UI patterns, then produces code that matches every convention in your codebase.

3. It catches architectural drift

Without skills, Claude makes reasonable guesses. With skills, Claude follows explicit rules. The difference is subtle in any single interaction but compounds over weeks.

I've seen codebases where 6 months of AI-assisted development created a mess. Some files using one state management approach, others using a different one, auth patterns inconsistent across routes. Skills prevent this.

4. It encodes why, not just what

Good skills explain the reasoning:

## Why Inngest over BullMQ

We use Inngest for background jobs because:
- Step-level checkpointing (failed step retries from that step, not the beginning)
- No Redis dependency
- Built-in AgentKit for AI agent workflows
- Durable webhooks (Stripe events never lost)

Do NOT suggest switching to BullMQ, Temporal, or custom queue implementations.

This prevents Claude from "helpfully" suggesting alternatives that would break the architecture.

The Skills I Actually Use

After building and refining over months, here are the categories of skills that deliver the most value:

Stack-specific patterns. How to add API routes, database tables, React hooks, UI components. These are the most-used skills because they cover the daily work of adding features.

Integration guides. How Stripe webhooks flow through Inngest, how auth works across web and mobile, how the RAG pipeline connects document upload to AI chat. These encode the complex cross-cutting concerns that are hardest to get right.

Anti-pattern lists. What NOT to do. These are surprisingly effective because Claude's most common failure mode is producing code that works but violates architectural decisions.

Workflow skills. Higher-level skills for common multi-step tasks: "add a complete feature" (schema + API + hooks + UI), "set up a new integration," "create an email template." These orchestrate multiple lower-level patterns.

Model Context Protocol (MCP): The Other Half

Skills teach Claude HOW to write code. MCP (Model Context Protocol) servers teach Claude HOW to interact with external services.

Instead of manually creating a Neon database, copying the connection string, creating Stripe products, copying API keys, setting up Resend, configuring PostHog, I have MCP servers for each service. Claude calls them directly.

The setup flow:

I describe my project in a config file
Claude reads the config
Claude calls MCP servers to create databases, payment products, email domains, analytics projects
Environment variables are populated automatically

What used to take 60+ minutes of context-switching between dashboards now takes about 5 minutes of describing what I want.

The Agentic Mindset Shift

Working this way has fundamentally changed how I think about development.

Before: I write code. I occasionally ask AI for help. AI gives generic suggestions that I adapt.

After: I describe intent. AI implements using my exact patterns. I review and course-correct.

The mental model is managing a team of junior developers. They're fast, literal, and excellent at pattern-matching. But they need clear instructions (skills), access to tools (MCP), and quality assurance (review).

Some practical examples of how this plays out:

Adding a feature: I describe "add a favorites feature where users can bookmark items." Claude reads the database skill, creates a table. Reads the API skill, creates endpoints. Reads the hooks skill, creates React Query hooks. Reads the UI skill, creates components. All matching existing patterns.

Fixing a bug: I describe "session persists after logout on mobile." Claude examines the auth skill, traces the signOut flow, identifies the issue, fixes it.

Refactoring: I describe "the conversation list is slow with 100+ items." Claude reads the UI patterns skill, knows to add virtualization. Reads the API skill, adds pagination. Updates the React Query hook with proper caching.

In each case, the output is consistent with the rest of the codebase because the skills encode the patterns.

What Doesn't Work

To be honest about the limitations:

Skills aren't a substitute for thinking. Claude follows patterns well, but it doesn't make architectural decisions. You still need to decide WHAT to build. Skills help with HOW.

Skills need maintenance. When you change a pattern, you need to update the skill. I've been burned by outdated skills that encode old conventions.

Complex cross-cutting concerns are hard to skill-ify. A skill for "add an API route" is straightforward. A skill for "redesign the auth flow to support SAML" is too complex and context-dependent to encode.

You still need to read the output. Claude is a fast, very literal capable developer. It does exactly what you say, not what you mean. Reviewing AI-generated code is non-negotiable.

Getting Started

If you want to try this approach in your own codebase:

Start with your most common task. What do you build most often? API endpoints? React components? Database migrations? Write a skill for that first.
Include concrete examples. Abstract descriptions don't work well. Show the EXACT code pattern you want.
List anti-patterns. What does Claude get wrong when it doesn't have context? Encode those as explicit "do NOT" rules.
Keep skills focused. One skill per concern. Don't write a mega-skill that covers everything. Claude can read multiple skills per task.
Iterate. Your first skill will be mediocre. After using it 10 times and seeing where Claude deviates, you'll refine it into something solid.

The goal isn't to replace human judgment. It's to eliminate the gap between what AI could produce (given perfect context) and what it actually produces (guessing at your conventions). Skills close that gap.

Documentation exists for humans who might read it. Skills exist for AI that always reads them. In a world where AI writes an increasing share of production code, optimizing for the AI reader isn't just pragmatic. It's the highest-leverage investment you can make in your codebase's consistency.

Magnus Rødseth builds AI-native applications and is the creator of Eden Stack, a production-ready starter kit with 30+ Claude skills encoding production patterns for AI-native SaaS development.

Building an Agentic Chatbot with Durable Execution

Magnus Rødseth — Tue, 03 Mar 2026 07:18:33 +0000

How I built a production-ready AI assistant that decides when to search the web, process documents, and run multi-minute research tasks without losing progress if things go wrong.

Most "AI chatbot" tutorials stop at the same place: wrap an LLM, stream tokens, done. That's a prototype. Production is a different beast entirely.

Over the past three years building AI-native applications, I've shipped chatbots that need to do more than answer questions. They need to act: search the web for current information, process uploaded documents, run multi-step research that takes minutes, and deliver results even if the user closes the browser.

This article walks through the architecture I landed on after multiple production deployments. The key insight: agentic chat is a distributed systems problem, not just an AI problem.

The Architecture

Here's the simplified flow:

User message
  → Elysia API (auth + validation)
    → Vercel AI SDK (streaming + tool calling)
      → Claude decides: respond directly, or use a tool?
        → Tool: Web Search (Exa API, instant)
        → Tool: Document Lookup (pgvector RAG query)
        → Tool: Deep Research (Inngest background function, 1-5 min)
    → Stream response back to client

Three layers, each solving a different problem:

Streaming layer. Vercel AI SDK handles the chat protocol, token streaming, and tool call orchestration.
Tool layer. Claude decides when to invoke tools based on user intent.
Durability layer. Inngest ensures long-running tasks complete, even if the server restarts.

Tool Calling: Let the AI Decide

The most important shift from a "chatbot" to an "agent" is tool calling. Instead of hardcoding "if user says X, do Y," you give the model a set of tools and let it choose.

Here's the shape of a tool definition with the Vercel AI SDK:

const webSearchTool = tool({
  description: "Search the web for current information",
  parameters: z.object({
    query: z.string().describe("The search query"),
  }),
  execute: async ({ query }) => {
    const results = await exa.searchAndContents(query, {
      numResults: 5,
      text: true,
    });
    return results.map((r) => ({
      title: r.title,
      url: r.url,
      content: r.text,
    }));
  },
});

You register tools with the model, and Claude determines from the conversation whether to invoke them. Ask "what's the weather in Oslo?" and it calls web search. Ask "summarize the PDF I uploaded" and it queries the vector store. Ask something it already knows, and it just responds.

This is fundamentally different from building a routing layer yourself. The model handles intent classification as a side effect of generating a response.

The RAG Pipeline: Documents to Embeddings to Answers

Document processing follows a well-established pipeline, but the details matter more than most tutorials suggest.

Ingestion:

Upload (PDF/DOCX/image)
  → Unstructured.io (extraction + layout analysis)
    → Text chunks (semantic splitting, ~500 tokens each)
      → Embedding generation (OpenAI ada-002)
        → pgvector storage (Neon PostgreSQL)

I chose Unstructured.io because it handles the nasty cases: scanned PDFs, mixed layouts, tables, embedded images with OCR. If you've ever tried to extract clean text from a real-world PDF, you know that pdf-parse gives you garbage for anything complex.

Retrieval:

When the chatbot's document lookup tool fires, it runs a cosine similarity search against pgvector:

SELECT content, metadata, 1 - (embedding <=> $1) AS similarity
FROM document_chunks
WHERE project_id = $2
ORDER BY embedding <=> $1
LIMIT 5;

The results feed back into Claude's context as tool output, and it synthesizes an answer with citations.

Where It Gets Hard: Long-Running Tasks

Web search returns in seconds. Document lookup returns in milliseconds. But what about deep research? A task that runs for 1-5 minutes, spawning multiple sub-queries, synthesizing sources, and building a grounded report?

You can't hold an HTTP connection open for 5 minutes. You can't stream a response that takes 3 minutes to start generating. And if your serverless function times out at 60 seconds, your user gets nothing.

This is where durable execution matters.

Why Durable Execution Matters

A durable execution engine treats your function like a state machine. Each step is checkpointed. If the process crashes mid-way, it resumes from the last checkpoint, not from the beginning.

Here's the deep research function using Inngest:

const deepResearch = inngest.createFunction(
  { id: "deep-research", retries: 3 },
  { event: "research/start" },
  async ({ event, step }) => {
    // Step 1: Generate sub-queries from the user's question
    const subQueries = await step.run("generate-queries", async () => {
      return generateSubQueries(event.data.question);
    });

    // Step 2: Execute each sub-query (parallelized)
    const searchResults = await Promise.all(
      subQueries.map((query, i) =>
        step.run(`search-${i}`, () => exa.searchAndContents(query))
      )
    );

    // Step 3: Synthesize into a report
    const report = await step.run("synthesize", async () => {
      return synthesizeReport(searchResults, event.data.question);
    });

    // Step 4: Store result and notify user
    await step.run("deliver", async () => {
      await db.insert(researchReports).values({
        projectId: event.data.projectId,
        content: report,
      });
      await sendNotification(event.data.userId, "Research complete");
    });

    return report;
  }
);

Each step.run() is a checkpoint. If search-2 fails due to a rate limit, Inngest retries that step, not the entire function. Steps 0 and 1 don't re-execute. The user gets a complete report even if the infrastructure hiccupped three times along the way.

Why not BullMQ or a simple queue? Because queues give you at-most-once or at-least-once delivery, but they don't give you step-level checkpointing. If your worker crashes after completing 3 of 5 sub-queries, a queue restarts the entire job. Durable execution restarts from step 4.

The User Experience

From the user's perspective:

They ask a complex question
The chatbot says "I'll research this in depth. This may take a few minutes."
The chatbot sends an event to Inngest, which starts the background function
The user can close the browser, go make coffee, whatever
When the research completes, they get a notification
They open the app and find a grounded report with citations

No progress is ever lost. No research restarts from scratch. The result is always delivered.

The Part Nobody Warns You About: Mobile

I mentioned this is a distributed systems problem. Nowhere is that more apparent than on mobile.

On web, the Vercel AI SDK gives you useChat() with streaming, tool call rendering, and state management. It's good.

On mobile (React Native / Expo), you're mostly on your own. The ecosystem for agentic chatbots on mobile is immature. Here's what I had to build from scratch:

Streaming handler. React Native doesn't have native ReadableStream support in all environments. You end up parsing SSE events manually.
Tool call UI. When the agent calls a tool, you need to show a loading state specific to that tool ("Searching the web..."), then render the tool result inline. No library does this for you on mobile.
Background task completion. When a deep research task finishes while the app is backgrounded, you need push notifications. This means hooking Inngest's completion event into your push notification service.
Auth across platforms. The chat session needs to be authenticated, which means mobile auth tokens need to flow through to the same API that handles web sessions.

The lesson: if you're planning to ship an agentic chatbot on both web and mobile, budget at least 3x the time you'd expect for the mobile portion.

What I'd Do Differently

After shipping this pattern multiple times:

Start with durable execution from day one. Don't build a synchronous chatbot and bolt on background jobs later. Design for async from the start.
Keep tools simple. Each tool should do one thing. Don't build a mega-tool that searches the web AND processes documents. Let the model compose simple tools.
Test tool selection, not just tool execution. Write tests that verify: given this user message, does the model select the right tool? This catches regressions you won't find with unit tests.
Stream partial progress for long tasks. Even if the full research takes 5 minutes, send periodic updates ("Found 3 relevant sources, synthesizing..."). Users tolerate waiting when they see progress.

The Stack

For reference, here's what I use:

Layer	Tool	Why
Chat protocol	Vercel AI SDK	Best streaming + tool calling DX
LLM	Claude	Strong tool calling, long context
Web search	Exa API	Better relevance than Google Custom Search
Document extraction	Unstructured.io	Handles real-world PDFs
Embeddings storage	pgvector (Neon)	No separate vector DB to manage
Durable execution	Inngest	Step-level checkpointing, no Redis
API	Elysia	Type-safe, fast, composable
Web	TanStack Start	SSR + modern React

Every piece is swappable. Don't like Neon? Use Supabase. Prefer LangChain over Vercel AI SDK? The architecture stays the same. The pattern is what matters, not the specific vendor.

If you're starting from scratch, my advice: get the durable execution layer right first. Everything else (streaming, tool calling, RAG) is well-documented. But the part where your AI tasks survive failures and always deliver results? That's what makes users trust your product.

Magnus Rødseth builds AI-native applications and is the creator of Eden Stack, a production-ready starter kit for AI-native SaaS.