An AI assistant can help with that workflow, but only if it can query a real catalog and persist what you already decided. Chat history isn't a database. A hallucinated deadline is worse than no deadline at all.

The Model Context Protocol (MCP) is the standard way to give AI apps that kind of access. In this tutorial, you'll build a scholarship research MCP server with Node.js, Express, and MongoDB.

When you finish, Cursor, Claude Desktop, or any other MCP host will be able to search awards, match them to a student profile, bookmark a shortlist, and store research notes. The model stays the reasoning layer while your server owns the data.

You'll build:

• A MongoDB catalog of scholarships, plus saved-list and notes collections

• Nine MCP tools for search, matching, deadlines, comparison, and research tracking

• Resources so a client can read the catalog without calling a tool

• Prompts that turn a student profile into a research plan

• An Express app that serves MCP over Streamable HTTP

The sample catalog in this project is a teaching dataset. Amounts, dates, and eligibility rules are simplified. Always confirm details on the official application page before applying.

What You Need

You should be comfortable with JavaScript and basic Express routing. You don't need prior MCP experience.

Install:

• Node.js 20 or later

• MongoDB running locally, or a free MongoDB Atlas cluster

• An MCP client if you want to try the last section. Cursor and Claude Desktop both work.

Docker is enough for MongoDB:

docker run -d --name mongo -p 27017:27017 mongo:7

Table of Contents

• What You Need

• What Is the Model Context Protocol?

• Why a Scholarship Research Server?

• How the Architecture Fits Together

• How to Set Up the Project

• How to Connect MongoDB

• How to Model Scholarship Data

• How to Write the Scholarship Service

• How to Register MCP Tools

• How to Expose Resources and Prompts

• How to Serve MCP Over Express

• How to Seed the Catalog

• How to Test the Server

• How to Connect Cursor and Claude Desktop

• How a Research Session Runs

• How the Matching Logic Works

• What You Can Build Next

• Conclusion

What Is the Model Context Protocol?

MCP is an open protocol that lets an AI application talk to external tools and data sources through a shared contract. Anthropic introduced it in 2024, and it's now maintained as an open standard.

Anthropic described MCP as "a USB-C port for AI applications": one connector, many hosts. (Source: Introducing the Model Context Protocol) Instead of writing one integration for Cursor, another for Claude Desktop, and a third for a custom agent, you implement the protocol once.

The official architecture overview splits MCP into two layers:

• The data layer is JSON-RPC 2.0. Clients and servers exchange requests such as tools/list and tools/call.

• The transport layer moves those messages. Local servers usually use stdio. Remote or long-running servers use Streamable HTTP.

This tutorial uses Streamable HTTP, because Express is already an HTTP server and you want the catalog available to any client on your machine.

Hosts, Clients, and Servers

Three roles show up in every MCP setup:

• The host is the AI app. Cursor and Claude Desktop are hosts.

• The client lives inside the host. The host creates one client per connected server.

• The server is your program. It advertises tools, resources, and prompts, then handles calls.

Your scholarship app is the server. You never talk to the model SDK directly. The host does that.

Tools, Resources, and Prompts

MCP servers expose three primitives. You'll use all three.

Tools are actions. The model decides to call them, the way it might call a function in a regular tool-calling API. Search, save, and compare belong here.

Resources are data the host can read and attach as context. A catalog URI and a per-scholarship URI belong here. The model doesn't have to "take an action" to see them.

Prompts are named templates. People usually invoke them from a slash command or a menu. A "research plan" prompt belongs here, because it's a workflow you want to start on purpose.

That split matters. If you put everything in tools, the model has to guess when to look things up. Resources and prompts give the host better knobs.

Why a Scholarship Research Server?

A weather MCP demo is a single API call. Scholarship research is closer to a real product:

• The catalog must be queryable. Keyword search, GPA filters, and deadline windows all live in the database.

• The workflow must persist. A saved shortlist and research notes should survive a new chat.

• Eligibility is logic, not prose. A GPA minimum is a number. First-generation-only is a boolean. Put those checks in code so the model can't invent a match.

• The output must be inspectable. Students should be able to open the official URL and verify every claim.

MongoDB fits this well. Each scholarship is a document with nested arrays for fields of study, citizenship, and requirements. Saved items and notes are separate collections with references back to the catalog.

You could wrap a public API instead of storing documents. That's a good follow-up. Starting with your own catalog keeps the tutorial self-contained and makes the MCP contract obvious.

How the Architecture Fits Together

The finished project looks like this:

MCP host (Cursor or Claude Desktop)
        |
        |  Streamable HTTP  POST /mcp
        v
Express app  (createMcpExpressApp)
        |
        |  createMcpHandler factory
        v
McpServer  tools / resources / prompts
        |
        v
Scholarship service
        |
        v
MongoDB  scholarships, savedScholarships, researchnotes

A few design choices are worth calling out before you write code.

The MCP handler is stateless. The SDK runs your server factory once per HTTP request. That's the recommended v2 pattern for Streamable HTTP. Don't keep tool state on the McpServer instance. Keep it in MongoDB.

The database connection is process-wide. Connecting on every request would be slow and pointless. You connect once at startup and close over that pool from the tools.

The HTTP surface is small on purpose. /health is for you. /mcp is for the protocol. You don't need a REST API in front of the same data unless you want one later.

How to Set Up the Project

Create a folder and initialize a Node.js project. ESM is required because the MCP SDK is ESM-first.

mkdir scholarship-research-mcp-server
cd scholarship-research-mcp-server
npm init -y

Open package.json and set "type": "module". Then install the SDK, Express, Mongoose, Zod, and dotenv:

npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mongoose dotenv zod

The SDK split into packages in v2:

• @modelcontextprotocol/server is the McpServer class and createMcpHandler

• @modelcontextprotocol/express gives you createMcpExpressApp, including DNS rebinding protection

• @modelcontextprotocol/node adapts the web-standard handler to Node's req/res

Create a .env file:

MONGODB_URI=mongodb://127.0.0.1:27017/scholarship_research
PORT=3000
HOST=127.0.0.1

Add a .gitignore that excludes node_modules and .env.

Your source layout can stay small:

src/
  index.js
  config.js
  db.js
  models/
  services/
  mcp/
  utils/
data/
  scholarships.json
scripts/
  seed.js
  smoke-test.js

src/config.js reads environment variables with defaults:

export const config = {
  mongodbUri: process.env.MONGODB_URI ?? "mongodb://127.0.0.1:27017/scholarship_research",
  port: Number(process.env.PORT ?? 3000),
  host: process.env.HOST ?? "127.0.0.1",
};

Keep configuration in one file. Tools shouldn't read process.env directly.

How to Connect MongoDB

Mongoose 9 works cleanly with ESM. A short src/db.js is enough:

import mongoose from "mongoose";
import { config } from "./config.js";

export async function connectDatabase() {
  mongoose.set("strictQuery", true);
  await mongoose.connect(config.mongodbUri);
  return mongoose.connection;
}

Call this once in src/index.js before app.listen. If the connection fails, the process should exit. A running Express server with a dead database is harder to debug than a failed startup.

How to Model Scholarship Data

You need three collections.

Scholarship

This is the catalog. Store the fields a matching engine actually uses, not a blob of markdown.

import mongoose from "mongoose";

const scholarshipSchema = new mongoose.Schema(
  {
    title: { type: String, required: true, trim: true },
    provider: { type: String, required: true, trim: true },
    description: { type: String, required: true },
    amountMin: { type: Number, default: 0 },
    amountMax: { type: Number, default: 0 },
    currency: { type: String, default: "USD" },
    deadline: { type: Date, default: null },
    rolling: { type: Boolean, default: false },
    educationLevels: { type: [String], default: ["undergraduate"] },
    fieldsOfStudy: { type: [String], default: ["any"] },
    gpaMinimum: { type: Number, default: null },
    citizenship: { type: [String], default: ["any"] },
    countries: { type: [String], default: ["any"] },
    firstGenerationOnly: { type: Boolean, default: false },
    womenOnly: { type: Boolean, default: false },
    numberOfAwards: { type: Number, default: 1 },
    renewable: { type: Boolean, default: false },
    applicationUrl: { type: String, required: true },
    applicationRequirements: { type: [String], default: [] },
  },
  { timestamps: true },
);

scholarshipSchema.index({
  title: "text",
  provider: "text",
  description: "text",
  fieldsOfStudy: "text",
});
scholarshipSchema.index({ deadline: 1 });
scholarshipSchema.index({ amountMax: -1 });

export const Scholarship = mongoose.model("Scholarship", scholarshipSchema);

A few field choices are doing real work:

• fieldsOfStudy: ["any"] means the award is field-open. The matcher treats any as a wildcard.

• deadline: null plus rolling: true covers programs that accept applications year-round.

• applicationUrl is mandatory. Every tool result should point back to a human-verifiable source.

• gpaMinimum: null means the provider didn't publish a cutoff. That's different from 0.

Saved Scholarship

A research list is a join between a person and a catalog row.

const savedScholarshipSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    status: {
      type: String,
      enum: ["saved", "applying", "submitted", "won", "rejected"],
      default: "saved",
    },
  },
  { timestamps: true },
);

savedScholarshipSchema.index({ researcherId: 1, scholarship: 1 }, { unique: true });

The unique index makes save_scholarship idempotent. Saving the same award twice updates the status instead of creating duplicates.

researcherId is a plain string. For a tutorial, that's enough. In production you would take it from an auth token.

Research Note

Notes are a separate collection so one scholarship can have many of them.

const researchNoteSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    body: { type: String, required: true, trim: true },
  },
  { timestamps: true },
);

You now have a catalog, a shortlist, and a notebook. That's the whole product surface the MCP tools will wrap.

How to Write the Scholarship Service

Keep MongoDB queries out of the MCP layer. Tools should call a service, get plain objects back, and format text. That makes the same functions reusable from a seed script, a smoke test, or a future REST route.

Search

Search is a filter builder. Each optional argument adds a clause. Open or rolling awards stay in the result set. Closed deadlines drop out.

const OPEN_DEADLINE_FILTER = {
  $or: [{ rolling: true }, { deadline: null }, { deadline: { $gte: new Date() } }],
};

export async function searchScholarships(filters) {
  const query = { ...OPEN_DEADLINE_FILTER };
  const and = [query];

  if (filters.keyword) {
    and.push({
      $or: [
        { title: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { provider: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { description: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.keyword), $options: "i" } },
      ],
    });
  }

  if (filters.fieldOfStudy) {
    and.push({
      $or: [
        { fieldsOfStudy: { $regex: `^any$`, $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.fieldOfStudy), $options: "i" } },
      ],
    });
  }

  // educationLevel, citizenship, country, minAmount, gpa, flags...

  const results = await Scholarship.find({ $and: and })
    .sort({ deadline: 1, amountMax: -1 })
    .limit(100)
    .lean();

  return rankByFieldMatch(results, filters.fieldOfStudy).slice(0, filters.limit ?? 10);
}

Two details are easy to skip and worth keeping.

Escape user input before you drop it into $regex. A keyword of ( shouldn't become a broken regular expression.

When a student searches for computer science, field-open awards (any) are eligible, but the specific CS scholarships should appear first. Rank in memory after the query. MongoDB already did the eligibility filter. You're only adjusting display order.

Match

Matching is not the same as search. Search is "find documents that look like this." Matching is "here is a student, score every open award."

The service loads open scholarships, then applies hard filters and a score:

Hard filters prevent false hope. Soft scores rank the rest. Each result also returns a reasons array, so the model can explain the match instead of inventing one.

That last point is the whole reason to put matching on the server. If you only return raw documents, the model will sometimes "helpfully" include an award the student can't apply for. Returning score and reasons keeps the explanation grounded in code.

Save, Notes, Deadlines, Compare

The remaining functions are thin:

• saveScholarship upserts by (researcherId, scholarshipId)

• addResearchNote inserts a note after confirming the scholarship exists

• getUpcomingDeadlines queries deadline between now and now + N days

• compareScholarships loads two or three documents and returns the same fields for each

Validate MongoDB ids with mongoose.Types.ObjectId.isValid before you query. An LLM will occasionally pass a title where you asked for an id. Fail clearly. Don't throw a CastError into the MCP transport.

How to Register MCP Tools

Create src/mcp/server.js as a factory. The HTTP handler will call it on every request.

import { McpServer } from "@modelcontextprotocol/server";
import { registerPrompts } from "./prompts.js";
import { registerResources } from "./resources.js";
import { registerTools } from "./tools.js";

export function createScholarshipServer() {
  const server = new McpServer({
    name: "scholarship-research",
    version: "1.0.0",
  });

  registerTools(server);
  registerResources(server);
  registerPrompts(server);

  return server;
}

Keep this factory cheap. No database connections, no file reads, and no caches that belong at module scope. The HTTP serving guide is explicit about this: create connection pools once at startup, and close over them.

One Tool, Fully

registerTool takes a name, a config object, and a handler. The inputSchema is a Zod object. The SDK turns that schema into JSON Schema for tools/list, validates arguments before your handler runs, and infers types if you're on TypeScript.

import * as z from "zod/v4";

server.registerTool(
  "search_scholarships",
  {
    title: "Search scholarships",
    description:
      "Search the scholarship catalog by keyword, field of study, education level, citizenship, country, GPA, and award amount.",
    inputSchema: z.object({
      keyword: z.string().min(1).optional().describe("Free-text search across title, provider, description, and fields"),
      fieldOfStudy: z.string().optional().describe("For example computer science, public health, or engineering"),
      educationLevel: z.enum(["undergraduate", "graduate", "doctoral"]).optional(),
      citizenship: z.string().optional(),
      country: z.string().optional(),
      minAmount: z.number().nonnegative().optional(),
      gpa: z.number().min(0).max(4).optional(),
      firstGeneration: z.boolean().optional(),
      womenOnly: z.boolean().optional(),
      limit: z.number().int().min(1).max(25).optional(),
    }),
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  async (args) => {
    const results = await searchScholarships(args);
    return toolText(formatScholarshipList(results));
  },
);

Write descriptions as if the model is the only docs the tool will ever get. .describe() on a Zod field survives conversion to JSON Schema. That's how the host tells the model what fieldOfStudy means.

title is the human label. description is the model-facing contract. They're not the same string.

Annotations

Annotations don't change how the SDK runs the tool. Hosts use them to decide how cautious to be.

• readOnlyHint: true for search, get, match, list, compare, and deadlines

• readOnlyHint: false for save and add-note

• idempotentHint: true on save, because of the unique index

• openWorldHint: false because this server talks to your database, not the open web

A host can auto-approve a read-only search and ask the user before a write. That's worth five extra keys in the config.

Return Shape

Every tool returns MCP content blocks:

export function toolText(text, isError = false) {
  return {
    content: [{ type: "text", text }],
    isError,
  };
}

Return isError: true for domain failures such as "scholarship not found." Throw only for unexpected failures. The spec treats those differently. A validation error from Zod never reaches your handler. The SDK already converts it into an isError result.

Format lists for a person who is skimming a chat transcript. Include the MongoDB id on every row. Later tools need that id, and the model can't invent a valid ObjectId.

The Full Tool Set

The server registers nine tools:

That's enough for a research loop: find, inspect, match, save, annotate, and compare.

Resist the urge to add a delete_everything tool. Destructive tools need extra confirmation and aren't part of this workflow.

How to Expose Resources and Prompts

Tools aren't the only way a host gets context.

Resources

A static resource is a fixed URI. The catalog fits that:

server.registerResource(
  "scholarship-catalog",
  "scholarship://catalog",
  {
    title: "Scholarship catalog",
    description: "Open scholarships currently stored in MongoDB",
    mimeType: "application/json",
  },
  async (uri) => {
    const catalog = await listCatalog();
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(catalog, null, 2),
        },
      ],
    };
  },
);

A resource template covers a family of URIs. Use scholarship://item/{id} rather than scholarship://{id}. If the pattern is scholarship://{id}, the URI scholarship://catalog becomes ambiguous.

import { ResourceTemplate } from "@modelcontextprotocol/server";

server.registerResource(
  "scholarship-record",
  new ResourceTemplate("scholarship://item/{id}", {
    list: async () => {
      const catalog = await listCatalog(20);
      return {
        resources: catalog.map((scholarship) => ({
          uri: `scholarship://item/${scholarship._id}`,
          name: scholarship.title,
          mimeType: "text/plain",
        })),
      };
    },
  }),
  {
    title: "Scholarship record",
    description: "Full details for one scholarship",
    mimeType: "text/plain",
  },
  async (uri, { id }) => {
    const scholarship = await getScholarshipById(id);
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "text/plain",
          text: scholarship
            ? formatScholarship(scholarship)
            : `No scholarship found with id ${id}.`,
        },
      ],
    };
  },
);

list is required on a template. Pass undefined if you can't enumerate instances. Here you can, so the host can show a picker.

Prompts

Prompts are workflows you want a person to start. The research plan prompt doesn't query MongoDB itself. It tells the model to use the tools, then structure the answer.

server.registerPrompt(
  "research-plan",
  {
    title: "Scholarship research plan",
    description: "Build a week-by-week research and application plan from a student profile.",
    argsSchema: z.object({
      fieldOfStudy: z.string(),
      educationLevel: z.string(),
      citizenship: z.string(),
      gpa: z.string(),
      weeks: z.string().optional(),
    }),
  },
  ({ fieldOfStudy, educationLevel, citizenship, gpa, weeks }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Create a ${weeks || "6"}-week scholarship research plan for this student.

Field of study: ${fieldOfStudy}
Education level: ${educationLevel}
Citizenship: ${citizenship}
GPA: ${gpa}

Use the scholarship research tools to find real awards first. Then produce a shortlist, a week-by-week plan, and risks. Name actual scholarships and dates from the tool results.`,
        },
      },
    ],
  }),
);

Notice the instruction "use the scholarship research tools." A prompt isn't a substitute for tools. It's a script that makes tool use more likely and the output shape more consistent.

A second prompt, application-checklist, takes a scholarship id and asks for a document list and a backward calendar. That's the kind of repetitive work MCP prompts are good at.

Prompt arguments are strings in many hosts, even when the value is a number. Typing gpa as a string avoids a frustrating expected number, received string error from a slash-command form.

How to Serve MCP Over Express

This is the part that used to be a page of session-handling code. In SDK v2 it's a factory plus one route.

import "dotenv/config";
import { createMcpExpressApp } from "@modelcontextprotocol/express";
import { toNodeHandler } from "@modelcontextprotocol/node";
import { createMcpHandler } from "@modelcontextprotocol/server";
import { config } from "./config.js";
import { connectDatabase } from "./db.js";
import { createScholarshipServer } from "./mcp/server.js";

const mcpHandler = createMcpHandler(() => createScholarshipServer());
const nodeHandler = toNodeHandler(mcpHandler);

const app = createMcpExpressApp({
  host: config.host,
  allowedHosts: ["127.0.0.1", "localhost"],
});

app.get("/health", (_req, res) => {
  res.json({
    status: "ok",
    service: "scholarship-research-mcp",
    transport: "streamable-http",
  });
});

app.all("/mcp", (req, res) => {
  void nodeHandler(req, res, req.body);
});

async function start() {
  await connectDatabase();
  app.listen(config.port, config.host, () => {
    console.log(`Scholarship research MCP server listening on http://${config.host}:${config.port}/mcp`);
  });
}

start();

Walk through what each helper is doing.

createMcpHandler takes a function that returns a fresh McpServer. It exposes a web-standard fetch. That's the same handler you would export from a Cloudflare Worker.

toNodeHandler adapts that fetch to Express (req, res). You pass req.body as the third argument because createMcpExpressApp already ran express.json(). If you omit the body, the adapter tries to read a stream Express already consumed.

createMcpExpressApp is express() with two extras: JSON parsing, and Host/Origin checks. Those checks exist because of DNS rebinding. A malicious page can point its own domain at 127.0.0.1 and, without a Host check, your browser would treat the local MCP server as same-origin. The default bind is 127.0.0.1 for that reason. The Express serving guide covers this in more detail.

app.all("/mcp", ...) is intentional. Streamable HTTP uses POST for JSON-RPC, and GET for SSE streams. Registering only POST will break some clients.

Shut the handler down on SIGINT:

process.on("SIGINT", async () => {
  await mcpHandler.close();
  process.exit(0);
});

close() waits for in-flight requests. Then you can exit.

Add npm scripts:

{
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js",
    "seed": "node scripts/seed.js",
    "smoke": "node scripts/smoke-test.js"
  }
}

node --watch is enough for local development. You don't need nodemon for this project.

How to Seed the Catalog

MCP tools against an empty database will work and return "no scholarships matched." That's correct, and also a bad first impression.

Put 20 to 30 realistic records in data/scholarships.json. Mix:

• Undergraduate and graduate awards

• STEM and field-open awards

• Country-specific programs and global ones

• Rolling deadlines and hard dates

• First-generation and women-only flags

A seed script should replace the catalog, not append:

import "dotenv/config";
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { connectDatabase } from "../src/db.js";
import { Scholarship } from "../src/models/index.js";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function seed() {
  await connectDatabase();
  const raw = await readFile(path.join(__dirname, "..", "data", "scholarships.json"), "utf8");
  await Scholarship.deleteMany({});
  const inserted = await Scholarship.insertMany(JSON.parse(raw));
  console.log(`Seeded ${inserted.length} scholarships.`);
  process.exit(0);
}

seed();

Run it:

npm run seed

Treat the JSON as sample data. Names of well-known programs help the tutorial feel real. They also create a duty to say, clearly, that students must verify every number and date on the official site. The applicationUrl field exists so that reminder has somewhere to point.

If you later replace the JSON with a live source, keep the same schema. The MCP tools shouldn't care where the documents came from.

How to Test the Server

Start MongoDB, seed, then start the process:

npm run seed
npm start

You should see:

Scholarship research MCP server listening on http://127.0.0.1:3000/mcp

Health Check

curl -s http://127.0.0.1:3000/health

A JSON status: ok means Express is up. It doesn't mean MCP is wired correctly. For that, send a JSON-RPC request.

List Tools

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response is an SSE event whose data: line contains the JSON-RPC result. You should see all nine tools, each with a JSON Schema derived from Zod.

The Accept header matters. MCP Streamable HTTP can return JSON or an event stream. Asking for both is the compatible choice.

Call a Tool

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params": {
      "name": "search_scholarships",
      "arguments": {
        "fieldOfStudy": "computer science",
        "limit": 3
      }
    }
  }'

You should get a numbered list with ids, deadlines, and GPA minimums. Copy one id and pass it to get_scholarship.

A small Node smoke test is nicer than raw curl once you're calling several methods. Parse the data: line, then print result.content[0].text. The repo includes scripts/smoke-test.js for that.

Inspector

The MCP Inspector is the official GUI for servers. Point it at http://127.0.0.1:3000/mcp and you can list tools, fill in arguments, and read resources without a host app in the way.

Use Inspector when a host "can't see" your server. If Inspector works and the host doesn't, the bug is in the host config. If Inspector fails, the bug is in your process.

How to Connect Cursor and Claude Desktop

Keep npm start running. MCP over HTTP is a live server, not a one-shot CLI.

Cursor

Add a server entry in Cursor's MCP settings. A Streamable HTTP server looks like this:

{
  "mcpServers": {
    "scholarship-research": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Restart the MCP session if Cursor had a previous failed connection cached. Then ask:

I am a first-generation undergraduate studying computer science in the United States, GPA 3.6. Use the scholarship research tools to build a shortlist and a six-week plan.

You should see the host call match_scholarships or search_scholarships, then get_scholarship for the interesting rows, then maybe save_scholarship. If it never calls a tool, the server isn't actually connected. Check the MCP logs in Cursor before you change code.

You can also invoke the research-plan prompt from the host's prompt menu if it surfaces prompts.

Claude Desktop

Claude Desktop's config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop prefers stdio. Bridge your HTTP server with mcp-remote:

{
  "mcpServers": {
    "scholarship-research": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp"]
    }
  }
}

Restart Claude Desktop after you save the file. The scholarship tools should appear in the tool list.

Don't put MongoDB credentials in the Claude config. The Node process already loaded .env. The host only needs the URL.

How a Research Session Runs

Here's a realistic session against the seed catalog. The student is a first-generation undergraduate in computer science, a US citizen, GPA 3.6.

The host calls match_scholarships with that profile. The server returns ranked rows. A women-in-technology award and a first-generation program both score well, for different reasons. A graduate-only award never appears.

The host then calls get_scholarship on the top two ids. Each result includes the official URL, the requirement list, and the deadline. That's the moment to tell the student to open the URL. The model shouldn't be the last word on eligibility.

If an award is worth pursuing, the host calls save_scholarship with a researcherId such as ada and status saved. Later it can set applying. list_saved_scholarships is how a new chat picks up the shortlist. Persistence is the whole point of MongoDB here. Without it, every conversation starts from zero.

add_research_note is for the messy human details: "Ask Dr. Chen for a recommendation by October 1." get_upcoming_deadlines is the weekly sweep. compare_scholarships is for the moment the student has two finalists and needs amount, GPA, and requirements in one view.

The research-plan prompt packages that loop. It injects the profile into a user message that tells the model to call tools first and then produce a week-by-week plan. If you invoke the prompt without a connected server, you get a generic essay. If you invoke it with this server running, you get named awards and real dates.

That's the product: a catalog the model can query, a shortlist it can't forget, and prompts that make the workflow repeatable.

How the Matching Logic Works

It's worth slowing down on matching, because this is the part people are tempted to hand to the model.

Suppose the student is:

• GPA 3.6

• Computer science

• Undergraduate

• United States citizen

• First-generation

• A woman

The matcher walks every open award.

A women-in-technology scholarship with a 3.3 GPA minimum, CS as a listed field, and US eligibility scores high: education, GPA, citizenship, women-only flag, and field all hit. A first-generation program that is field-open also scores high, because any counts as a field match. A graduate-only award is skipped, even if the title looks relevant. A 3.8 GPA cutoff is skipped, even if everything else fits.

The tool then returns ranked rows with reasons:

1. Palantir Women in Technology Scholarship — score 90
   Why: education level matches; GPA 3.6 meets the 3.3 minimum; citizenship is eligible; women-only award matches; field of study matches

The model can still write a warm paragraph around that. It shouldn't be the component that decided eligibility.

If you extend this later, keep the same split. New eligibility rules belong in the service. New prose belongs in the prompt.

What You Can Build Next

The server you have is complete enough to use. It's also a base for a more serious research tool.

First, you could replace the seed file with a live source. Official feeds such as Grants.gov and college-maintained lists are safer than scraping commercial aggregators. Keep your schema. Write an importer that upserts by a stable external id.

You could also add authentication. createMcpExpressApp works with requireBearerAuth. Map researcherId from the verified token instead of a tool argument. The Express adapter documents that middleware.

Try adding full-text search. The schema already has a text index. For a large catalog, Atlas Search or a dedicated search engine will beat a pile of regex filters.

You can track documents, not just notes. A documents collection for transcripts, recommendation status, and essay drafts turns the shortlist into an application tracker.

You could also write tests around the matcher. Eligibility code is where silent bugs hurt people. A table of profiles and expected include/exclude lists will pay for itself.

And you could deploy it. Bind to 127.0.0.1 on your laptop. If you put this on a network, set allowedHosts, terminate TLS, and require a bearer token. An open MCP server is an open database with a helpful English interface.

Conclusion

In this guide, you built a scholarship research MCP server that's more than a toy tool list.

You stored awards, shortlists, and notes in MongoDB. You exposed search, matching, and research-tracking as MCP tools, with Zod schemas the host can advertise to a model. You added resources for the catalog and prompts for repeatable workflows. You served the whole thing over Streamable HTTP with Express, including the Host header checks the SDK enables for localhost.

The pattern transfers. Any research workflow with a catalog and a personal working set can use the same three layers: a service that owns the rules, an McpServer factory that registers primitives, and a small Express app that speaks the protocol.

If you take one idea from this tutorial, take this one: let the model write the plan, and let your server decide what's true.

The sample catalog is for learning. Confirm every scholarship on its official application page before you apply, and before you tell someone else to apply.

Behind that conversation sits a pipeline of telephony infrastructure, speech recognition, language models, application logic, APIs, databases, and call routing.

The interesting part isn't just the AI model. It's how these components work together to turn an audio stream into useful business actions.

Businesses that want these capabilities have two paths.

They can buy a finished product. The market now includes dedicated AI receptionists such as XBert from Nextiva, along with tools from Goodcall, Dialzara, and others.

Or they can build one, which is what this article walks you through. Understanding the architecture helps either way: it shows what a commercial product is doing under the hood, and what a custom build needs to assemble.

A typical architecture looks something like this:

In this article, we'll walk through the architecture behind an AI phone agent, from the moment a caller dials a business number to what happens after the call ends.

You'll see how telephony systems connect calls, how speech becomes text, how AI identifies intent and maintains conversation context, and how function calls connect the agent to calendars, CRMs, and other business systems. We'll also look at how agents decide when to hand a call to a human and what information can be passed along during that handoff.

What We'll Cover:

• A Phone Call Enters the System

• Speech Becomes Text

• The System Determines What the Caller Wants

• The Conversation Runs as a Loop

• The AI Calls Business Systems

• Booking an Appointment

• Capturing Lead Information

• Knowing When to Involve a Human

• What Happens After the Call

• What the Business Sees

A Phone Call Enters the System

The process starts like a regular phone call. A customer dials a business number, and the telecommunications provider receives the call.

The provider then needs to connect that call to an application capable of handling it.

One common approach is a webhook. The telephony provider sends an HTTP request to an application when an incoming call arrives. The application can then return instructions describing how the call should be handled.

The call itself needs carrier connectivity. Production systems typically use SIP trunking, which connects a voice application or phone system to the public telephone network over the internet.

Providers such as Nextiva, Twilio, and Bandwidth offer SIP trunking that supplies the numbers and call capacity an AI voice system runs on. From there, the application layer takes over.

For example, Twilio sends an HTTP request to a configured application when an incoming voice call arrives. The application can respond with TwiML instructions that control the call.

A simplified Node.js endpoint might look like this:

app.post("/incoming-call", (req, res) => {
  const response = new VoiceResponse();

  response.say("Hello. How can I help you today?");

  res.type("text/xml");
  res.send(response.toString());
});

This example doesn't contain any AI yet. It simply shows the first architectural boundary.

The phone network handles the call. The application receives an event and decides what happens next.

From here, the application needs to process the caller's audio.

Speech Becomes Text

People communicate with the system through audio, but most application logic works with structured data and text.

An automatic speech recognition system, or ASR system, converts the caller's speech into text.

For example, a caller might say:

"I need to move my appointment from Friday to Monday afternoon."

The speech recognition layer might produce:

{
  "text": "I need to move my appointment from Friday to Monday afternoon."
}

The exact response depends on the speech recognition system. Some systems can also provide timestamps, confidence information, speaker information, or partial transcripts.

The application can now pass the recognized text to its conversational layer.

This separation is useful because the AI reasoning layer doesn't need to understand raw telephone audio. It receives text and returns a decision or response.

The System Determines What the Caller Wants

The next challenge is understanding intent.

Suppose three callers say:

"I want to book a consultation."

"Can I move my appointment to next week?"

"Where is your office?"

The system needs to recognize that these requests require different workflows.

An application could represent the detected intent as structured data:

{
  "intent": "reschedule_appointment",
  "entities": {
    "current_day": "Friday",
    "requested_day": "Monday",
    "time_preference": "afternoon"
  }
}

The language model can produce this structure, or the application can derive it through another classification layer.

The important architectural point is that the application turns natural language into information that downstream systems can process.

The model might understand that the caller wants to reschedule an appointment, but it shouldn't directly modify a calendar simply because it generated that interpretation.

The application needs to control what happens next.

The Conversation Runs as a Loop

An AI phone agent doesn't normally process an entire conversation in a single request.

Instead, it operates as a loop.

The caller speaks. Speech recognition converts the audio into text. The application sends the text and relevant context to the AI system. The AI determines what it needs to say or what action it needs to perform. The application generates audio and sends it back to the caller.

Then the caller speaks again.

A simplified version looks like this:

while (callIsActive) {
  const audio = await receiveAudio();

  const text = await speechToText(audio);

  const result = await processConversation({
    text,
    context: conversationContext
  });

  conversationContext = result.updatedContext;

  const audioResponse = await textToSpeech(result.response);

  await sendAudio(audioResponse);
}

This is conceptual code, not a complete phone implementation. Real systems need to handle streaming audio, interruptions, timeouts, errors, authentication, and provider-specific protocols.

Context is also important.

If the caller says:

"I want to book an appointment."

The system might ask:

"What type of appointment do you need?"

The caller then says:

"An initial consultation."

That second statement only makes sense because the application remembers the previous exchange.

Conversation state might contain information such as:

{
  "intent": "book_appointment",
  "appointment_type": "initial_consultation",
  "customer_name": "Jane Smith",
  "preferred_date": null
}

The system can add to this state as the conversation progresses.

The AI Calls Business Systems

This is where an AI receptionist becomes more than a voice chatbot.

Suppose a caller asks:

"Do you have anything available tomorrow afternoon?"

The AI can't reliably answer that from the conversation alone. It needs current information from a calendar or scheduling system.

This is where function calling, also called tool calling, becomes useful.

The application can expose a limited set of functions to the AI:

const tools = [
  {
    name: "check_calendar",
    description: "Find available appointment slots",
    parameters: {
      date: "string",
      appointmentType: "string"
    }
  },
  {
    name: "book_appointment",
    description: "Book an available appointment",
    parameters: {
      slotId: "string",
      customerId: "string"
    }
  }
];

The model can determine that it needs check_calendar.

The application then executes the function:

const slots = await checkCalendar({
  date: "2026-08-21",
  appointmentType: "consultation"
});

The result goes back into the conversation context:

{
  "available_slots": [
    "2026-08-21T14:00:00",
    "2026-08-21T15:30:00"
  ]
}

The AI can then tell the caller which options are available.

The important architectural boundary is that the AI decides what action may be needed, while application code controls how that action is performed.

That gives developers a place to enforce permissions, validate inputs, handle failures, and control access to business systems.

Booking an Appointment

Now consider the final step.

The caller selects one of the available times.

The AI can request an appointment booking:

{
  "tool": "book_appointment",
  "arguments": {
    "slotId": "slot_123",
    "customerId": "customer_456"
  }
}

The application validates those values before calling the calendar system.

For example:

async function bookAppointment(slotId, customerId) {
  const slot = await getAvailableSlot(slotId);

  if (!slot || slot.booked) {
    throw new Error("Appointment slot is no longer available");
  }

  return calendar.createEvent({
    customerId,
    start: slot.start,
    end: slot.end
  });
}

The application then returns the actual result to the AI.

This distinction matters.

The AI shouldn't tell the caller that an appointment has been booked merely because it decided to call book_appointment.

The calendar system needs to confirm that the operation succeeded.

Calendar APIs commonly expose operations for creating events. For example, Google Calendar provides an events.insert method for creating an event.

Only after receiving a successful response should the conversational layer tell the caller that the appointment is confirmed.

Capturing Lead Information

The same architecture can capture information during a sales conversation.

A caller might provide a name, email address, company, phone number, service requirement, and preferred follow-up time.

The conversation can gradually populate a structured lead object:

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "company": "Example Corp",
  "interest": "enterprise consultation",
  "appointment_booked": true
}

The application can then send this information to a CRM.

This creates an important distinction between conversation data and business data.

The transcript represents what the caller said.

The CRM record represents the structured information that the business needs to act on.

A CRM might contain the caller's contact information, inquiry type, qualification data, appointment details, and follow-up status.

The exact fields depend on the company's CRM and sales process.

Knowing When to Involve a Human

Not every conversation should remain with an AI system.

A production system needs escalation rules.

An escalation might happen when the caller asks for a person, when the request falls outside the agent's supported workflows, or when the business has decided that a particular type of request requires human involvement.

The application can represent this decision explicitly:

if (shouldEscalate(conversation)) {
  return transferToHuman({
    callerId,
    reason,
    conversationContext
  });
}

The important part is what happens during the transfer.

A useful handoff should carry context rather than forcing the employee to start from zero.

The human agent might receive:

{
  "caller": {
    "name": "Jane Smith",
    "phone": "+1-555-0100"
  },
  "reason": "Complex billing question",
  "summary": "Caller needs help resolving an invoice discrepancy.",
  "actionsCompleted": [
    "Customer identity verified"
  ]
}

The exact handoff data depends on the system.

Telephony platforms can also support call transfers and callbacks through their voice APIs. For example, Twilio's voice documentation describes call routing and <Dial> functionality for connecting calls to another destination.

What Happens After the Call

The conversation doesn't necessarily end when the caller hangs up.

Depending on the system and its configuration, the application can retain the transcript and other call data.

A simplified call record might look like this:

{
  "callId": "call_123",
  "duration": 342,
  "customerId": "customer_456",
  "intent": "book_appointment",
  "appointmentId": "appointment_789",
  "leadCaptured": true,
  "escalated": false
}

The transcript can provide the detailed conversation, while structured fields provide information that downstream applications can query.

A call can therefore trigger several business actions.

• A sales call can create a lead.

• An appointment call can update a calendar.

• A support call can create a ticket.

• A complex conversation can result in a human handoff.

Telephony systems can also notify applications about call lifecycle events through status callbacks. Twilio, for example, sends a request to a number's StatusCallback URL when a call ends, and supports a statusCallbackEvent attribute for subscribing to lifecycle events such as initiated, ringing, answered, and completed on dialed legs.

What the Business Sees

From the employee's perspective, all of this infrastructure can be hidden behind a few business records.

An employee might see a new CRM lead with contact information and the reason for the call.

The calendar might contain a newly booked appointment.

The conversation system might contain the transcript and a summary.

If the call was transferred, the employee can receive the relevant context before speaking with the customer.

That's the main architectural idea behind AI phone agents.

The voice interface is only one layer. Underneath it is a collection of systems that convert speech into text, interpret the caller's request, maintain conversation state, call external services, validate business actions, and return results to the caller.

The language model provides the conversational reasoning. The surrounding application provides the state, tools, permissions, integrations, and business rules that turn that conversation into an actual workflow.

Hope you enjoyed this article. You can connect with me on LinkedIn.

A huge variety of servers around all sorts of communities, efforts, and initiatives have been popping up and are still appearing. And they're largely taking the place of forums, chat rooms and, at times, documentation sites and news boards.

To what degree this is a good thing is up for debate, but the long and short of it is that Discord is likely here to stay.

When it comes to accessibility, Discord's had a bit of a rocky road. For years, it was very painful to use for screen reader users due to an apparent lack of forethought regarding accessibility.

Over the last few years, this situation has improved substantially. While it's by no means fully accessible in 2026, it can be used relatively efficiently once you know the tricks of the trade.

freeCodeCamp uses Discord, and the community has often seen that screen reader users struggle to use this communication tool comfortably. This is where this article comes in.

In this article, I'll go over the basics you'll need to use Discord as a platform to send and receive messages and contribute to communities that use Discord as a communication platform. It's relatively easy to learn but can be difficult to fully grasp due to the various interwoven things it does. Still, these basics should get you up and running and will equip you to learn about all the other features it offers by yourself going forward.

Table of Contents

• Screen Reader Prerequisites

• The Broad Strokes: How to Navigate Efficiently

• Speeding Things Up: How to Navigate and Interact Efficiently

• When is Browse Mode More Efficient?

• Conclusion

Screen Reader Prerequisites

Discord is an application that, because of the way it was built, has both web app and desktop app aspects to it. I think this is one of the main issues people run into, so I'll give a brief rundown about why this matters for screen reader users.

Particularly on Windows, screen readers tend to operate in two modes when a web app is encountered: you're either in browse/virtual mode or you're in forms/focus mode.

Discord, being essentially a web app, gives you both of these modes as well. In "browse" mode, you have access to keys that navigate by heading, form field, button, and so on. In focus mode, you only have access to the keyboard shortcuts that work with the app. By default, these are tab/shift+tab, the arrow keys, space, enter, and escape.

Knowing when to use which mode is a bit of a mine field, but in general, a good rule of thumb is that you read/browse in browse mode, and you act/type in forms/focus mode.

Many web apps, Discord included, generally gracefully switch you between modes when required, but this isn't always the case. When this doesn't happen, you need to know how and when to switch, which I'll point out when required in the upcoming sections of this article.

The Broad Strokes: How to Navigate Efficiently

The tricky bit with learning an app like this is generally that documentation can be really scarce and hard to find. Discord probably has articles on this, but you'd need to know what to look for. And at the end of the day, all we want to do is use the app for what we're trying to do and move on with our lives. So here's the Cliff's notes.

Discord has a pretty rich list of keyboard shortcuts that allow you to do all sorts of things, but some of the keys aren't super obvious, and some of the navigation patterns are inconsistent.

In general, when navigating or skimming, you want to be in your screen reader's focus or forms mode. NVDA toggles this with NVDA+space, JAWS with JAWS+z. This allows Discord's own navigation keys to work correctly, which makes things go a little faster.

A key that works in a lot of applications on Windows is f6. This jumps you between specific regions of an application and is a bit of a hold-over from Ye olden Days of Windows 98 and XP. File explorer, office apps and browsers generally use this key in this way, but other apps like VS Code, Slack, and Discord do as well. It's a bit of a super power for keyboard-only navigation, as it gets you places a lot quicker.

In Discord, it bounces you between the server list, the message list, and a few other spots. But, oddly enough, it doesn't take you to the actual message entry field. To go there, the quickest way is to just start typing. This will zip your cursor to the right place.

With Discord having essentially its own keyboard navigation layer, I would generally recommend that you stay in focus/forms mode for most interactions, unless you need the conveniences of browse mode. More on that below.

When in focus mode, f6 moves you between the various regions of the screen, as I mentioned above. Tab will navigate you between those regions, as well as the interactable elements within those regions.

This, together with the arrow keys to navigate lists of channels, messages, and servers, will get you to most places you'll need to go for basic Discord usage.

Speeding Things Up: How to Navigate and Interact Efficiently

If you know where you're going, the best way to get there quickly is the ctrl+k or cmd+k hotkeys, depending on your operating system. This hotkey will bring up a search field where you can type part of a channel name, user name, or server name to search for it. A list of results will be focused after a brief pause, and then you can use the arrow keys to move to the correct result. Pressing enter takes you straight to the server, channel, or user you selected.

On Discord servers, it can be difficult to keep up with everything happening, given how many channels a lot of servers have. Here's a few tips to keep track of it all:

• Ctrl+i / cmd+i will open your so-called "inbox". This is where you can get a list of your mentions on the various servers you're in, which can be a great way to keep track of people trying to get your attention.

• There are a number of hotkeys that also let you cycle between various types of channels. For example, shift+alt+up and down will navigate between channels with unread messages. This is another quick way to get through a large amount of unread channels efficiently.

When is Browse Mode More Efficient?

I'd say there are two scenarios in which browse mode may be beneficial.

First, if you want to look at a message more granularly (for example to see how a word is spelled), dropping into browse mode will let you do that.

You can also use review cursors/object navigation shortcuts if you want, but browse mode tends to be easier in these cases. It also allows for more convenient copying of text if you need to do that.

To my knowledge, there's no quick way to jump to the earliest unread message in focus mode, which can be a bit annoying if you're scrolling back to see what messages you did and didn't read yet.

There is a "NEW" indicator above that message, which you can find with a reverse NVDA search, or by scrolling and listening out for it. Discord does have a hotkey (shift+page-up) to do this as well, but in my testing it doesn't always work as advertised.

Apart from that, barring a few niche edge cases, you can generally stay in focus mode unless you want to NVDA or JAWS search for button labels. This can be useful to quickly, say, find the disconnect button in a voice channel, which currently doesn't appear to have a hotkey associated with it.

Conclusion

Discord is a pretty complicated app, and this guide touches on the basics to get you started. With these general strategies, you should be able to deal with day-to-day messaging, channel management, and voice channels.

I always encourage anyone to just explore and work out your own strategies though. You can rarely break things irreparably, so see how things work for you personally and develop a way of working that works for you, specifically. This is always the best strategy for any kind of app, particularly when using assistive technology.

If you want to learn about all the other hotkeys Discord offers, you can find a keyboard reference on the Discord website. They offer both visual charts, which are inaccessible for screen reader users in this instance, or a readable table.

I hope this was helpful. Go forth and Discord!

This has always been an issue in vulnerability management. While a security team might find out about the vulnerable dependency, fixing it may not always be possible at once. Developers need to ensure that the vulnerable code is in use and perform all necessary checks before releasing the fix into production.

Recently, though, there have been some solid advancements in the use of AI for discovering software vulnerabilities and exploits. This research, for example, details some of the findings and the path forward.

But how will this really help the development community? We need to fix things more quickly, but more importantly, we need to be able to figure out which vulnerabilities actually matter and which ones need attention first.

In this article, we'll examine what the classic patching process looks like, how AI is decreasing the amount of time security teams have to react, and why it's not always reasonable just to address vulnerabilities by their severity score.

We'll also discuss exposure management and the difference between it and traditional vulnerability management. Then we'll cover how developers can analyze dependencies, code reachability, and Software Bill of Materials (SBOMs) to figure out the actual vulnerabilities in their applications.

What We'll Cover:

• Patching vs. Exposure Management: What's the Difference?

  • What Is Patching?

  • What Is Exposure Management?

• The Old Patch Management Workflow Was Built Around Time

• AI Is Shrinking the Time Between "Found" and "Exploited"

• Why "Patch Everything" Doesn't Work at Scale

• Exposure Management: Moving from Flaw Counts to Contextual Risk

• The Dependency Tree as an Attack Surface

• Practical Takeaways for Developers

  • Audit Transitive Dependencies

  • Check Code Reachability

  • Generate an SBOM in CI/CD

  • Use Compensating Controls When a Patch Isn't Ready

  • Apply Least Privilege at Runtime

• Wrap Up

Patching vs. Exposure Management: What's the Difference?

Before we look at how AI is changing vulnerability response, it helps to understand two important concepts: patching and exposure management.

What Is Patching?

Patching is a process of updating software to address an existing issue, including a security vulnerability, bug, or a stability problem. This may involve upgrading a library with a known vulnerability, applying a security update for your operating system, or using a new release of an application with a vulnerability fixed.

For instance, if your application uses a particular library with a known security vulnerability, you can upgrade the library once the patched version is available. After that, you'll need to test the update, ensure that the application still operates as intended, and release the upgraded version into production.

So patching isn't only about installing the latest version of the package in question. A dependency update can break an API, some functionality, or even other dependent packages. That's why teams typically use patch management strategies when identifying vulnerabilities, updating decision-making, testing, deploying, and verifying that the patches work.

What Is Exposure Management?

While vulnerability management is concerned mainly with identifying vulnerabilities, exposure management focuses more broadly on whether those vulnerabilities can actually provide a realistic route for an attack.

For example, a vulnerable library, limited in use to a development system, poses less immediate threat than a similarly vulnerable library used in an internet-facing system that's capable of accessing the database.

Some aspects to consider include accessibility via network, asset exposure, vulnerable code paths, identity and access controls, cloud environments, and the sensitivity of systems and data.

Simply put, vulnerability management is concerned with the discovery and tracking of vulnerabilities, whereas exposure management is focused on determining which of those vulnerabilities pose a true or larger risk.

The Old Patch Management Workflow Was Built Around Time

The classic process of vulnerability mitigation depended on step-by-step actions.

1. CVE discovered

2. Security team assesses the severity

3. Maintainer releases an upstream patch

4. Developer updates the dependency

5. CI/CD pipeline runs regression tests

6. Production deployment

7. Remediation verified

The process wasn't flawed by nature, but it operated under the unspoken premise that the defenders were granted enough room to operate through each step.

Let's take a dependency vulnerability example for practice. If the automated scanner detects a vulnerability within a popular utility package such as lodash, engineers don't immediately bump the dependency version in the production environment. They need to confirm if the application code leverages the vulnerable function, check the presence of breaking API changes after the upgrade, and run build validation through integration tests.

Each security patch is essentially a change to the code and needs to be safely pushed through the development and deployment cycle.

AI Is Shrinking the Time Between "Found" and "Exploited"

The buffer between vulnerability discovery and exploitation that used to exist is being eliminated. This is because automated programs can scan through codebases, generate proofs of concept, and discover edge cases.

Modern AI systems help researchers and would-be attackers alike perform tasks like static binary analysis, detecting vulnerabilities, creating exploit payloads, and finding logical issues in complicated software designs.

Programs such as DARPA’s Artificial Intelligence Cyber Challenge (AIxCC) show how AI systems can be used to automatically find and patch vulnerabilities in complex open-source software. During the 2024 semifinal competition, autonomous Cyber Reasoning Systems were tested against projects based on real-world software such as Jenkins, the Linux kernel, Nginx, SQLite3, and Apache Tika. The systems discovered 22 unique synthetic vulnerabilities and successfully patched 15 of them. They also identified one real-world bug in SQLite3, which was responsibly disclosed.

In the context of a real development process, certain tasks in the patching process can be performed by AI. The AI could perform code analysis and dependency analysis in order to detect potential vulnerabilities. It could also help trace the usage of vulnerable functions, recommend changes in code and dependencies, and generate tests to make sure that the suggested patch doesn’t break the existing functionality. The security team could also use AI for pattern detection.

As AI tools get better at assessing software and detecting vulnerabilities, the window of time between vulnerability detection and its mitigation becomes smaller and more important. This change in paradigm also affects how security professionals approach AI and exposure management, especially as the exploit window gets smaller and vulnerabilities need proper prioritization.

AI can also support exposure management by connecting vulnerability information with the environment in which the vulnerable software is running. For example, an AI-assisted security system could correlate a vulnerable dependency with an internet-facing application, its network connections, cloud permissions, and the data or services it can access. This helps security teams move from simply asking whether a vulnerability exists to asking what an attacker could realistically reach through it.

Why "Patch Everything" Doesn't Work at Scale

When an organization-wide scanner generates a list of 500 vulnerabilities spread across multiple microservices, reacting to each one with urgency starts to seem impossible. Developers can suffer from alert fatigue and get overwhelmed pretty easily.

The Common Vulnerability Scoring System (CVSS) is a standardized framework used to describe the severity of a vulnerability. CVSS v3.1 uses the following severity ranges:

CVSS is useful because it provides both developers and security teams with a common language that describes the severity of a vulnerability. Nevertheless, the rating describes the vulnerability but not the environment where this vulnerability appears. In other words, CVSS doesn't tell you if the functionality used by the vulnerability is really used by your application or if the affected system is exposed to the Internet.

To see why CVSS alone isn't always enough, let's say we have two hypothetical vulnerabilities in an organization's environment:

• Vulnerability A: This critical remote code execution vulnerability is part of an isolated testing harness or development-only dependency that's never included in the production environment and doesn't have any external network accessibility.

• Vulnerability B: A high-severity input validation vulnerability is found in an internet-facing API gateway that processes malicious user input and has access to a backend database with customer information.

Looking at just the CVSS score would require the team to focus on Vulnerability A before Vulnerability B. But it's clear that Vulnerability B poses the greater threat to operations. Security studies show us that very few vulnerabilities get exploited once they're known. Telemetry data from the CISA KEV Catalog clearly indicates that attackers focus on a subset of vulnerabilities that have a real path of exploitation.

In reality, teams must consider the CVSS score in addition to many contextual factors when deciding what to fix. A particular vulnerability might have a higher priority if the following conditions are true:

• it has an impact on an internet-facing production system,

• there's a known exploit for the vulnerability,

• there's sensitive information exposed,

• it impacts an important business function,

• or it offers an attacker a means of gaining access to other privileged systems.

But vulnerabilities that occur only in development or are inaccessible for some reason likely don't need to be fixed immediately.

The most appropriate method for determining the importance of vulnerabilities is asking some straightforward questions: Is the vulnerable system accessible? Is the vulnerable code accessible? Is there any exploit for this vulnerability? What privileges does the affected service have? What will an attacker be able to access after exploiting the vulnerability?

Assigning the same level of priority to all alerts wastes engineering efforts on vulnerabilities that might pose no or little risk at all.

Exposure Management: Moving from Flaw Counts to Contextual Risk

Exposure management shifts focus from simply cataloging static vulnerabilities to evaluating an organization's actual operational risk posture.

Instead of asking "How many CVEs exist in our repositories?", exposure management asks "Which vulnerable components, misconfigurations, and reachable network paths create exploitable risk across our running assets?"

The difference becomes easier to see when you look at what each approach focuses on:

When there are 10,000 cloud assets managed by an engineering environment and 1,000 vulnerable libraries found through dependency scanners, the combined numbers don't represent the actual security situation. In order to focus on the right level of risks, you should have some knowledge about the context within which each of these vulnerabilities exists.

• Is the container exposed to the internet or is it hidden behind the internal load balancer?

• Is the code actually invoking the risky symbol or library function?

• What are the identity permissions, cloud roles, and databases that are accessible through the vulnerable service?

Having an understanding of this denominator (total numbers of assets that should receive a specific patch) helps teams identify the exposures that are actually threats so that engineering time is spent on solving the problems that impact production data.

The Dependency Tree as an Attack Surface

Modern software delivery depends on multi-layered packages such as npm, PyPI, Maven, NuGet, base operating system layer packages, GitHub Actions, and third-party APIs. The application logic is written by developers, but the final runtime software contains numerous levels of packages:

Your Application Logic → Direct Dependency (Declared in manifest) → Transitive Dependency (Pulled in automatically) → Underlying OS System Packages → Base Container Image / Cloud Runtime.

If a vulnerability is three levels down in the transitive dependencies and the transitive dependency is unmaintained, but can be accessed via external inputs, then that's an essential part of your application's attack surface.

That's why software development teams have started to use Software Bill of Materials (SBOMs). An SBOM is an inventory of software components that constitute the software or application. Depending on the technology used to create the SBOM, different information can be available including component name, version, dependencies and package ID.

It's helpful in cases where a new vulnerability has been identified. For example, if a vulnerability is discovered in a specific version of lodash, the security team can use its SBOMs to identify which applications or container images contain the affected version. They'll then be able to investigate if there's an exploitable exposure.

An SBOM alone doesn't provide security for the application. Its significance lies in increasing visibility to developers and security personnel regarding what is present in their applications.

Practical Takeaways for Developers

These principles will be relevant once you integrate them into your team's routine development process. There are some practical ways you and your team can employ these best practices and strategies:

Audit Transitive Dependencies

The first thing to do is to verify what dependencies are included in your application. This is very useful when it comes to transitive dependencies, because these dependencies may have been automatically added when installing some other package directly.

For Node.js applications, the command npm ls will display the dependency tree. Python programmers may use pipdeptree, while Java programs created using Maven can use the mvn dependency:tree command. These commands can help you understand the origins of packages and the direct dependency that introduced a vulnerable transitive dependency into your project.

Check Code Reachability

Finding a weak point in a dependency doesn't automatically imply that you're using it within your application. Don't take every vulnerability report as a critical production blocker. Instead, you should investigate if the impacted functionality is actually accessible from your application.

Suppose you find a vulnerability in a certain library function. In this case, you need to look through your codebase for any usage of this function and figure out if there's any possibility of passing user-controlled data to it. You may use either the search function provided by your IDE or command-line utilities such as grep.

An unused or inaccessible from the outside function reduces the urgency of the finding. But it doesn't automatically imply that you should ignore it.

Generate an SBOM in CI/CD

You can also produce a Software Bill of Materials using your CI/CD pipeline. Creating an SBOM will help you identify the components used in the software and make it easier to identify affected components once a vulnerability is found.

For instance, using Syft, you can generate an SBOM from a container image by executing the command: syft my-app:latest -o cyclonedx-json > sbom.json.

This will create a CycloneDX JSON file with information on the components within the container image. This SBOM will then be stored along with the build artifacts. Once a new vulnerability is identified in a particular package version, it becomes easy for the security team to know which applications and container images contain this particular component.

Use Compensating Controls When a Patch Isn't Ready

Sometimes there may be no patch available or it may be too risky to implement it straight away since doing so might introduce breaking changes that need further testing. In such cases, you can use compensatory controls to lessen the exposure of the application until it's patched properly.

Depending on the environment, this may involve limiting the network access to the vulnerable component, isolating the workload from sensitive resources, disabling the feature that has been compromised, or minimizing the privileges of the application.

These controls don't take the place of the security patch but only minimize the risk of exploitation until a patch is implemented.

Apply Least Privilege at Runtime

Lastly, restrict the amount of access your applications have at run time. When a compromise is made due to exploitation, it prevents the spread of that breach to other applications or systems.

When deploying container-based applications, you can leverage read-only filesystems, as well as remove capabilities that aren't required in Linux. For instance, Docker provides the option to use --read-only and --cap-drop=ALL when running containers.

Cloud applications also need to adopt the same concept by ensuring the use of IAM permissions, giving access only to what the application requires.

The goal is simple: if one element has been breached, the attacker should be able to gain access to as few components of the environment around it as possible.

The future of software security doesn't rely on how fast organizations can update their packages without knowing the underlying reasons for doing so. With vulnerability detection becoming more efficient through automation, effective mitigation relies on knowledge about the relationship between the source code, its dependencies, and infrastructure at runtime.

The purpose here isn't just finding new vulnerabilities but recognizing the ones that pose real risks to the application.

Wrap Up

While artificial intelligence is helping teams detect vulnerabilities quicker, modern applications keep becoming increasingly dependent on numerous software layers. This doesn't mean that patching becomes unnecessary. It means that all vulnerabilities don't require the same immediate attention.

Developers also still need to look at where those vulnerabilities exist, whether they're reachable by attackers, and what they could affect. As the time between vulnerability detection and exploitation continues to change, understanding exposure becomes just as important as the patch itself.

In March 2025, a small nonprofit research group called METR published a chart that made many engineering leaders sit up straighter than usual.

Working backward through six years of model releases, METR measured the length of the software task an AI agent could complete on its own, which they defined as the amount of time a skilled human professional would need for the same task, and found that number has been doubling roughly every seven months since 2019 (METR).

That curve isn't about autocomplete getting a little better: it's about agents crossing from "finishes a function" to "finishes a feature" to, on the current trajectory, "finishes a sprint."

The adoption numbers already reflect that shift. Google Cloud and DORA's 2025 State of AI-assisted Software Development Report found that 90 percent of developers now use AI at work and more than 80 percent say it has increased their productivity, even though roughly three in ten still report low trust in the code the models produce (DORA).

Stack Overflow's 2025 Developer Survey puts a similar number on habitual use: 84 percent of developers now use or plan to use AI tools, up from 76 percent the year before, and about half of professional developers reach for one daily (Stack Overflow).

AI-assisted coding skipped the novelty phase and arrived as the default way software gets written. At the same time, most teams still haven't updated the software development lifecycle they built for the previous default.

That mismatch is the subject of this piece. Anthropic's Applied AI team published a framework in 2026 called the AI-native SDLC, built around a single observation: once an agent can write and revise code faster than a human can review a pull request, the bottleneck in software delivery doesn't disappear so much as relocate (Anthropic).

This guide walks through that framework stage by stage (Plan, Design, Build, Test, Deploy, Maintain), and shows you how to implement each stage with whichever agentic coding tool you have access to: Claude Code, OpenAI Codex, or Gemini CLI. You'll see configuration files, markdown artifact templates, and CI workflows for all three tools, plus a worked example of how a single forward-deployed engineer uses this pattern to cover work that used to require a five-person team.

This guide is one framework, implemented three ways: a practitioner's playbook grounded in config files and command output.

Table of Contents

• Prerequisites

• What is an AI-Native SDLC?

• Where the Bottleneck Moves Once Code Gets Cheap

• Claude Code, Codex, and Gemini CLI: One Framework, Three Vocabularies

• How to Run the Plan Stage

• How to Run the Design Stage

• How to Run the Build Stage

• How to Run the Test Stage

• How to Run the Deploy Stage

• How to Run the Maintain Stage

• How One Engineer Covers a Five-Person Team

  • The Plan Stage

  • The Design Stage

  • The Build Stage

  • The Test Stage

  • The Deploy Stage

  • The Maintain Stage

• Pre-flight Checklist Before You Go All-in on an Agentic AI-Native SDLC

• Conclusion

• What to Explore Next

Prerequisites

Before you start, make sure you have the following:

• One agentic coding CLI installed: Claude Code, OpenAI Codex, or Gemini CLI. You only need one to follow along. The sections below give you the equivalent command or file for each.

• Node.js 18 or later (verify with node --version), since all three tools distribute as npm packages.

• Git 2.30 or later (verify with git --version).

• A GitHub repository with Actions enabled, since the Deploy and Maintain sections use CI workflows.

• Basic familiarity with CI/CD concepts: pull requests, branch protection, and what a build pipeline does. You don't need deep GitHub Actions expertise.

Install whichever tool you plan to use:

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g @google/gemini-cli

Here's what each one gives you:

• claude-code puts a claude command on your path that runs an agentic session against your local repository, with permission modes, subagents, and skills.

• codex puts a codex command on your path with its own sandboxing and approval model, plus a hosted cloud-task mode.

• gemini-cli puts a gemini command on your path, built around Extensions that bundle prompts, MCP servers, and slash commands into one installable unit.

You don't need all three. Pick whichever your employer already pays for, or whichever free tier fits your project, and follow that column through the rest of this guide.

What is an AI-Native SDLC?

The diagram below shows how the six phases are connected as a continuous system rather than a series of isolated steps. The following sections explain how each stage hands off a substantial named artifact to the next, with the final stage looping directly back to the beginning instead of stopping at deployment.

Figure 1: The AI-native Software Development Life Cycle (SDLC) drawn as a closed hexagonal loop rather than a straight pipeline. The six stages, Plan, Design, Build, Test, Deploy, Maintain, run clockwise around the outside. The artifact each stage hands to the next (intent.md, spec.md, plan.md plus code, test results, review.md, bands.yaml) sits inside the loop next to the arrow it travels on. The doubled arrow from Maintain back to Plan is the detail worth noticing first: it's what turns six individual stages into one self-triggering cycle instead of six improvements that happen to sit next to each other.

If you follow along the arrows:

• Plan hands the next stage an intent.md.

• Design hands Build a spec.md.

• Build hands Test and Deploy a plan.md and eventually a diff.

• Deploy hands Maintain a merged pull request with its review findings attached.

• Maintain when something breaks in production, write a new intent.md and start the loop again. That closed loop is the innovation, more than any individual stage.

A traditional SDLC diagram is usually drawn as a waterfall or a horizontal pipeline. This one is drawn as a circle because the entire point is that operational data becomes the next planning input automatically, instead of sitting in a dashboard nobody opens until the next planning offsite.

Engineers built the traditional six-stage software development lifecycle of plan, design, build, test, deploy, and maintain around an assumption that held for fifty years: writing and implementing code was the most expensive, most time-consuming part of the process.

Anthropic's Applied AI team named this assumption explicitly when it published its AI-native SDLC framework in 2026, and framed the entire model around what happens when that assumption stops being true (Anthropic). The framework keeps the same six stage names software engineers already know. What's different is how each stage produces and consumes work.

Anthropic calls the mechanism artifact-driven development. Every stage commits a durable, version-controlled, machine-readable document that the next stage reads: no meeting, no Slack thread, and no shared understanding that lives only in someone's head.

• Plan produces intent.md, a plain description of the problem in the requester's own words.

• Design produces spec.md, the requirements and constraints with any open concerns flagged inline.

• Build produces plan.md, an implementation plan naming the files that will change, the order of changes, and the tests that will confirm them, followed by the diff.

• Test and Deploy produce a pull request carrying multiple layers of automated review findings.

• Maintain produces incident records that feed back into a new intent.md when something in production breaches an expected threshold.

Anthropic's own phrasing captures the design intent well:

"Every stage commits an artifact the next stage can read. Together, the intent, the spec, the plan, the diff and the review findings are the audit trail." (Anthropic)

That audit trail matters for a reason beyond compliance. When an agent can produce a working diff in minutes, what determines whether the software is good is whether the plan it worked from was good, and whether someone checked its output against a requirement before it shipped.

Artifacts make that checking possible without slowing the agent down: a spec document takes ten minutes to review and can be cached, reused, and diffed the way code is diffed. A verbal handoff can't.

Where the Bottleneck Moves Once Code Gets Cheap

Anthropic titles the relevant section of its framework, "Code is no longer the bottleneck," then explains why in the next line:

"Organizations have started using AI to write code at a speed unthinkable one year ago, yet the processes around the code haven't changed at the same pace." (Anthropic)

That observation is worth walking through slowly, because it's the part of the framework that changes how you organize your day, beyond which tool you buy. The chart below puts a number on that reallocation across a sprint's calendar time.

Figure 2: Two stacked timelines, drawn to the same total width, showing how a sprint's calendar time gets reallocated. The top bar, Traditional SDLC, splits time into six roughly equal segments. The bottom bar, AI-native SDLC, keeps Plan, Design, and Deploy wide (labeled "stays human-paced") while Build and Test collapse into thinner slivers (labeled "compresses to hours"). The two bars are the same overall length on purpose: the point isn't that everything gets faster. It's that the time that used to go into Build now has to go somewhere, and that somewhere is Plan and Review.

The diagram above shows the traditional SDLC's time allocation next to the AI-native one. In the traditional model, the Build bar dominates the chart: most of a sprint's calendar time goes into writing and debugging code, while Plan, Test, and Deploy are comparatively thin. In the AI-native version, Build shrinks to a sliver, an agent can produce a working implementation in the time it used to take to schedule the kickoff meeting, and the bars for Plan, Test/Review, and Deploy grow to fill the space Build used to occupy. The chart's total width barely changes. What's changing is which stages are now doing the rate-limiting work.

Anthropic's own framing names the same three stages:

"The bottleneck moves to the steps to the left and right of the build phase. This is mainly plan, review/test, and deploy, which still run at human speed." (Anthropic)

That's a specific, falsifiable claim, and it's worth taking seriously instead of writing it off as a slogan. Speed at Build breaks in three specific, avoidable ways:

• Fast Build, vague Plan. Because there's now less time between "wrong" and "shipped" to notice, an agent confidently implementing the wrong thing at high speed is counterintuitively worse than a human making the same mistake slowly.

• Fast Build, unscaled Test and Review. Nobody redesigned review to handle the higher volume of changes a fast agent produces, so either review quality drops or reviewers become the new queue, and the speed gain evaporates when a human has to read the diff.

• Fast Build, manual Deploy. A human still has to promote a build through three environments by hand, so the agent produces work faster than the organization can absorb it.

The argument here is that the stages surrounding the agent, more than the agent itself, are where an AI-native SDLC earns its name. Agentic coding tools aren't the problem. The rest of this guide treats Plan, Design, Test, Deploy, and Maintain with the same engineering rigor teams have historically reserved for Build, because that's where the constraint lives now.

Claude Code, Codex, and Gemini CLI: One Framework, Three Vocabularies

Every stage below gives you a command or file for Claude Code, Codex, and Gemini CLI side by side: that only works once you know what each tool calls the mechanism you're about to use. All three vendors ship a genuinely capable agentic coding tool, and the right one for you is largely the one your employer licenses or the one whose free tier matches your workload.

The table below is the reference to come back to while reading the stage-by-stage sections.

A few things stand out when you lay the mechanisms side by side. All three tools now converge on the same core idea: a plain-text memory file the agent reads before doing anything else, a packaging system for reusable prompts and tools, an approval layer that decides how much autonomy the agent gets, and a first-party GitHub Action for running the agent in CI.

Once Build stops being the constraint, every vendor has to build the same surrounding infrastructure or their tool becomes fast but unmanageable.

The one place the three tools are not symmetric is the last row. Claude Code and Codex each ship an official, vendor-built Slack presence with a persistent tag identity that turns a channel mention into an asynchronous coding task. Gemini CLI doesn't have a documented equivalent as of this research (only community-built bridges connect it to Slack).

If your Maintain-stage workflow depends on an agent picking up an incident directly from a chat mention, that's a capability gap to plan around rather than a preference.

Because it undercuts the idea that you have to pick a tool and live with it forever, one more piece of interoperability is worth calling out: Claude Code's own memory documentation describes importing an existing AGENTS.md file with an @AGENTS.md reference or a symlink, so a Claude Code session can read the same conventions file a Codex session already uses (Anthropic).

AGENTS.md itself has become a cross-vendor open standard, adopted well beyond Codex, and stewarded outside any single company (OpenAI). A team that standardizes its conventions file on AGENTS.md and has Claude Code import it gets most of the benefit of a single shared memory file, regardless of which tool an individual engineer prefers that day.

How to Run the Plan Stage

The Plan stage answers one question before any code gets touched: what's the problem, in the words of the person who has it?

Anthropic's framework calls the artifact this stage produces intent.md, and it's deliberately unglamorous. It's not a Jira ticket with acceptance criteria already reverse-engineered from a solution. It's closer to a transcript: what the requester said they needed, in their own language, captured before an engineer or an agent starts interpreting it.

Here's a minimal intent.md template you can commit to a repository and reuse for every new piece of work:

# intent.md

## Requested by
Name, role, date

## What they said
Paste the raw request. Do not clean it up yet. If it came from a support
ticket, a Slack thread, or an incident, link it.

## What problem this solves
One or two sentences, written after the raw request above, translating it
into a problem statement. This is the first place interpretation is allowed.

## Why now
What triggered this request. If it came out of an incident, name the
incident record it traces back to.

## Constraints already known
Anything the requester specified: deadline, budget, systems that cannot
change, regulatory requirement.

## Explicitly out of scope
What this request does not include, stated as what it does.

Here's what's happening:

• The "what they said" section is deliberately unedited, so the next stage can catch a misread request before it propagates

• Separating "what they said" from "what problem this solves" forces the interpretation step to happen once, in writing, instead of inside whoever reads the request next

• The "why now" field is what closes the loop from the Maintain stage: an intent that originated from a production incident should say so explicitly, linking back to the incident record that triggered it

Filled in for a request, the same template stays this short:

# intent.md

## Requested by
Maria, independent contractor and beta user, 2026-08-14

## What they said
"I have to check four different calendars every morning before I can tell
a client when I'm free. I've double-booked myself twice this month."

## What problem this solves
Contractors working across multiple clients cannot see a unified view of
their own availability without giving each client's calendar system
access to the others.

## Why now
Direct customer feedback during the private beta, not a production
incident.

## Constraints already known
Beta ships in six weeks. No budget for a dedicated calendar-sync vendor.

## Explicitly out of scope
Two-way sync or write access to any client's calendar. Read-only overlay only, for this release.

A spec written from this intent would name the technical shape: which calendar providers to support first, how the overlay handles conflicting time zones, and what happens when a provider's API is unavailable. Notice how little interpretation is left for Build to improvise. That's the entire point of writing the intent down before touching a design document, let alone code.

Each tool gives you a different mechanism for working through this stage without letting an agent jump straight to code. Claude Code's Plan mode is a dedicated, read-only permission mode built for this scenario: the agent can research the codebase and propose an approach, but it can't edit files or run commands until you switch out of it, toggled with Shift+Tab (Anthropic).

Codex separates the same idea into two independent settings rather than one mode switch: a sandbox setting that controls what the agent is technically capable of touching (read-only, workspace-write, or danger-full-access) and an approval policy that controls when it has to stop and ask (untrusted, on-request, or never) (OpenAI).

Setting the sandbox to read-only during Plan gets you the same guarantee Claude Code's Plan mode gives you, enforced at a different layer. Gemini CLI has a plan approval mode with the same read-only intent, though Google's own documentation flags it as still maturing relative to its other approval modes (Google), so treat it as directionally useful rather than a hard guarantee until you've verified its behavior against your own repository.

The output of a Plan-stage session, regardless of which tool ran it, should be the filled-in intent.md plus a short back-and-forth confirming the agent's summary of the problem matches what the requester meant. That confirmation step is the human-speed part of the stage the earlier section warned you about, and it's tempting to skip when the agent's summary already sounds right. Skipping it because the agent produced a plausible-sounding summary quickly is the failure mode the bottleneck-shift argument predicts: fast, confident, but wrong.

How to Run the Design Stage

Design is where intent.md becomes spec.md, a document that names the technical shape of the solution, the interfaces it touches, and the tradeoffs someone has to sign off on before an agent starts writing implementation code.

Anthropic's framework describes this stage as one where "requirements and design collapse into one session" (Anthropic), which is a meaningful change from a traditional process where a product spec and a technical design document are often written by different people, days apart, with a meeting in between to reconcile them.

A useful spec.md template keeps that collapse explicit rather than accidental:

# spec.md

## Source
Link to the intent.md this spec answers.

## Approach
Plain description of the technical approach: which systems change, which
stay the same, and why this approach over the obvious alternative.

## Interfaces affected
API endpoints, database schemas, public function signatures. Anything
another team or another service depends on.

## Open concerns
Anything the agent or the author is not confident about. This section
exists specifically so uncertainty gets written down instead of quietly
resolved by whichever choice was easiest to implement.

## Explicitly rejected alternatives
What else was considered and why it lost. This is what keeps the next
person from re-litigating a decision six months from now.

## Sign-off
Who reviewed this and on what date.

The "open concerns" and "explicitly rejected alternatives" sections are doing the work here. An agent asked to produce a design document will, by default, present its chosen approach as obvious. A human reviewer's job at this stage is narrow but specific: read those two sections first, because a wrong assumption is far more likely to be hiding there than in the parts of the document the agent is most confident about.

All three tools support this stage the same way they support Plan: keep the session in a read-only or plan-style mode while the spec gets drafted, and switch to a mode that can write files only after a human has read the "open concerns" section and either resolved or explicitly accepted each item. The mechanism differs (Claude Code's Plan mode, Codex's read-only sandbox, Gemini CLI's plan approval mode), but the discipline is identical across all three: nothing gets implemented from a spec until someone has reviewed its open concerns.

One practical note to build into your process: version the spec alongside the code, the same way you'd version a model card alongside the model it documents. A spec.md that lives only in a chat transcript isn't an artifact. A spec.md committed to the repository, in the same pull request as the implementation it describes, is one your Test and Deploy stages can reference later.

How to Run the Build Stage

Build is the stage everyone already associates with agentic coding tools, and it's also the stage that changes the least in this framework, because the tools were already built to do this part well.

What changes is that Build now runs from an approved plan.md, rather than from an ad hoc prompt, which is what keeps a fast agent pointed at the right target instead of an interesting-but-wrong one.

A plan.md names the specific files that will change, the order changes happen in, and the tests that confirm each change:

# plan.md

## Source
Link to spec.md this plan implements.

## Files to change, in order
1. `src/models/user.py`: add the `last_login_at` field
2. `src/api/auth.py`: update login handler to set the new field
3. `tests/test_auth.py`: add coverage for the new field
4. `migrations/0042_add_last_login.py`: schema migration

## Tests that must pass before this plan is considered done
- Existing auth test suite, unmodified tests still green
- New test: login sets last_login_at to the current UTC timestamp
- New test: last_login_at is null for a user who has never logged in

## Rollback
How to revert if this ships broken: a single migration down-step and a
git revert of the three code changes, no data backfill required.

The memory file each tool reads before touching any of this is what governs how the agent writes the code, not the plan alone. A CLAUDE.md at the root of a repository might look like this:

# CLAUDE.md

## Commands
- Run tests: `pytest tests/ -x -q`
- Run linter: `ruff check src/`
- Start local server: `python manage.py runserver`

## Codebase layout
Django monolith. Business logic lives in `src/services/`, not in views or
models. Views call services; services call models. Do not put business
logic directly in a view.

## Standards
- All new API endpoints require a corresponding entry in `openapi.yaml`
- Database migrations are one change per file, never bundled
- No new dependencies without an entry in `docs/decisions/`

## Test coverage
Every new function in `src/services/` needs a corresponding test in
`tests/services/`. Coverage below 85% fails CI.

If your project already standardized on AGENTS.md because it's the cross-vendor format, the file above is nearly a direct port: same structure, same content, different filename, and Codex will read it automatically as it walks from the Codex home directory down to your project root (OpenAI).

A GEMINI.md version is the same content again, and Gemini CLI concatenates it with any global ~/.gemini/GEMINI.md and subdirectory-level files it finds, so a monorepo can layer a company-wide convention file with per-service overrides (Google).

Whichever filename you commit to, the content (commands, architecture, conventions, testing rules) is the part that determines whether the agent's output looks like your codebase or like a generic tutorial.

Reusable behavior beyond a single memory file is where the three tools diverge more visibly. Claude Code splits this into two mechanisms: Subagents, which run in their own context window with restricted tool access for a narrow job like "review this diff for SQL injection," and Skills, folder-based packages that Claude invokes automatically when they're relevant, which absorbed what used to be custom slash commands (Anthropic, Anthropic).

Codex is mid-migration on the same idea: its older custom prompts mechanism is now explicitly deprecated in favor of Skills, which Codex can invoke implicitly and share across a team through the repository (OpenAI).

Gemini CLI takes the broadest approach of the three, packaging prompts, MCP servers, custom slash commands, hooks, and subagents into a single installable Extension, rather than keeping each mechanism as a separately configured feature (Google).

None of these are strictly better than the others. Claude Code and Codex give you finer-grained control over which mechanism does what. Gemini CLI gives you one bundle to install and share, which matters when your team's problem is getting five engineers onto the same conventions, since juggling five separately configured features invites drift.

Every one of the three tools also connects to external systems, databases, ticket trackers, and design tools, through the Model Context Protocol, which Anthropic created and open-sourced as a native, first-class part of Claude Code (Anthropic) and which has since become a genuinely cross-vendor standard. Codex supports it through its own MCP client, and Gemini CLI supports it with OAuth 2.0 for remote servers.

MCP is worth treating as infrastructure you configure once per project rather than a tool-specific feature, precisely because all three tools now speak it.

How to Run the Test Stage

Anthropic frames this stage as "continuous evals woven through implementation" (Anthropic), a deliberate contrast with a traditional model where testing is a phase that starts after Build finishes.

When an agent can produce a diff in minutes, waiting for a separate testing phase means the queue in front of testing grows faster than any team can review. The fix is to make verification a property of every commit the agent produces rather than a gate a human remembers to run afterward.

This is also the stage where the DORA report's less flattering finding becomes relevant: alongside the 90 percent adoption number, roughly three in ten developers still say they have low trust in AI-generated code (DORA). That distrust is rational when testing is a separate phase bolted on after a fast Build stage, because nobody has verified the code yet when someone has to trust it. But it becomes a solvable engineering problem rather than a standing risk once verification runs on every commit instead of waiting for a human to schedule it.

Claude Code implements this with Hooks: shell commands that fire automatically at specific lifecycle events, like right before or right after the agent edits a file or runs a command (Anthropic). A hook that runs your test suite after every file edit and blocks the agent from proceeding on failure looks like this in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pytest tests/ -x -q --timeout=60"
          }
        ]
      }
    ]
  }
}

Here's what's happening:

• PostToolUse fires the hook after the agent finishes an Edit or Write tool call, not before, so it's checking changes on disk.

• pytest -x stops at the first failure, which keeps the feedback loop short instead of dumping a full failure report the agent has to parse.

• A blocking exit code from this command stops the agent from moving on to the next planned file in plan.md until the test suite is green again.

Codex and Gemini CLI don't document a general-purpose local hooks framework with the same maturity as Claude Code's (and if you've come to rely on stopping an agent mid-session on your own laptop). It's less a missing feature than a different point in the pipeline: both tools build their continuous-verification story primarily around CI rather than a local lifecycle-event system, so Codex and Gemini CLI's /review and PR-triggered review products (covered below, under Deploy) catch the same class of problem once the diff reaches a pull request.

If you're running Codex or Gemini CLI locally today, the practical substitute is a pre-commit hook wired through Git itself that calls the same test command a Claude Code hook would call. This gives you most of the same guarantee at a different layer of the toolchain.

The artifact this stage should leave behind, regardless of tool, is a test result attached to the specific commit in plan.md that it verifies, so a reviewer three stages later can see which test proved which claim, rather than trusting a green checkmark that might be testing last week's code.

How to Run the Deploy Stage

Anthropic describes this stage as "layers of agentic review with human review reserved for regulated and critical code," where "governance is enforced as the AI acts, with hooks as approval gates." (Anthropic)

The word layers does work: the framework doesn't propose replacing human review with agent review. It proposes stacking automated review as an earlier, cheaper layer, so humans focus on findings that survived automated scrutiny rather than catching everything from scratch.

All three vendors now ship a first-party GitHub Action, so you don't have to hand-build a CI integration from scratch. Claude Code's anthropics/claude-code-action responds to @claude mentions in a PR or issue, or runs on any GitHub event or schedule you configure (Anthropic):

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this diff against spec.md and plan.md for this PR."

Codex's equivalent, openai/codex-action, runs codex exec inside the CI job itself, which means the agent has the full CLI's capability, not a stripped-down review-only mode, and can apply patches or post a review comment depending on how you configure the step (OpenAI):

name: Codex Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          command: "review this diff against the linked spec.md and flag P0/P1 issues"

Gemini's google-github-actions/run-gemini-cli fires on the same PR and issue events and runs with full project context asynchronously, rather than as a synchronous blocking check (Google):

name: Gemini Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  gemini-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/run-gemini-cli@v1
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          prompt: "Review this pull request for correctness, efficiency, and maintainability."

Beyond the raw CI action, each vendor also ships a dedicated code review product with its own configuration surface. Claude Code's Code Review is a managed service that runs multiple specialized agents against a diff in parallel. It includes a separate verification step to filter out false positives before anything reaches a human as an inline PR comment, triggered by @claude review or the local /code-review command (Anthropic).

Codex's review surface is the /review command in the CLI composer, an @codex review mention on a GitHub PR, or an "automatic reviews" setting that runs on every new PR without a mention. In GitHub mode, it deliberately restricts itself to flagging only the most severe P0 and P1 issues rather than every stylistic nit (OpenAI).

Unlike the other two, Gemini Code Assist for GitHub is configured primarily through a checked-in file, .gemini/config.yaml, a separate surface from the memory file that governs Build. It posts a summary comment plus inline comments across five review dimensions: correctness, efficiency, maintainability, security, and a miscellaneous catch-all covering testing, scalability, and error logging (Google).

The human gate belongs where these automated layers hand off to a person, and where that point sits should depend on the blast radius of the change, and is not a blanket rule. A change to a database migration, an auth flow, or anything touching payments should require human approval, no matter how clean the automated review looks.

A documentation fix or a config value bump that passed every automated layer is a reasonable candidate for auto-merge. Anthropic frames the diff itself as part of the audit trail: "the chain of commits is also the audit trail: who asked for what, what the agent produced, and who approved it" (Anthropic).

That's the useful mental model: the diff isn't done when the agent stops writing code. It's done when it has accumulated the review evidence a human needs to make a fast, informed approval decision.

How to Run the Maintain Stage

Maintain is the stage that gives artifact-driven development its name, because that's where the loop closes. Anthropic describes it as "agents monitor live deployments. Any breached control band is diagnosed and written back into the loop as a new intent.md." (Anthropic)

Without that write-back step, Maintain is just monitoring, the same dashboards teams have run for a decade. With it, a production incident becomes the direct input to the next Plan-stage session, instead of a postmortem doc that gets read once and filed away.

A practical way to encode this is a bands-style configuration that defines the acceptable range for a metric and what happens when it's breached:

# monitoring/bands.yaml

- metric: p99_latency_ms
  service: checkout-api
  band: [0, 400]
  on_breach:
    severity: high
    action: open_incident
    write_intent: true

- metric: error_rate_pct
  service: checkout-api
  band: [0, 1.0]
  on_breach:
    severity: critical
    action: page_oncall
    write_intent: true

- metric: daily_active_users
  service: onboarding-flow
  band: [800, null]
  on_breach:
    severity: medium
    action: open_incident
    write_intent: false

Here's what's happening:

• Each metric has a band, an acceptable range, rather than a single threshold, which lets you catch a value that has dropped too low as easily as one that has risen too high.

• write_intent: true is the mechanism that turns a breach into the start of a new Plan-stage cycle automatically, generating a draft intent.md that names the breached metric, the service, and links to the incident.

• Not every breach should open a new intent. A dip in daily active users on a low-severity service might warrant an incident for visibility without spinning up new planning work, which is why that flag is explicit rather than assumed.

Where an agent receives the page or the mention matters here: this is the one place the three tools aren't equivalent. Claude Tag gives an organization a shared @Claude identity in Slack that works asynchronously in a channel and routes a mentioned coding task to Claude Code on the web. This makes "someone tags the bot in the incident channel with the failing metric" a workable Maintain-stage pattern out of the box (Anthropic).

OpenAI ships the direct equivalent: an official Codex Slack app where @Codex in a channel or thread creates a cloud task, works in the relevant repository, and posts results back into the same thread it was mentioned in (Slack).

As covered above, no first-party Google equivalent exists yet; only third-party and community-built bridges connect Gemini CLI to Slack today. The practical workaround for a Gemini-based Maintain stage is routing automation through your existing on-call paging tool's webhook rather than waiting on a chat mention (worth setting up before you're mid-incident and reaching for a bot that isn't there).

Trace that whole write-back mechanism from one breach to the next planning cycle, and it looks like the diagram below:

Figure 3: A one-way pipeline drawn as a closed loop instead. Reading left to right and down, intent.md feeds spec.md, spec.md feeds plan.md, plan.md feeds an agent build, which flows into automated test and review gates, then Deploy, then Monitoring. The dashed blue return arrow, labeled "triggers next cycle," is the part most teams' processes are missing: it routes a monitoring breach straight back into a freshly generated intent.md, closing the loop instead of ending at Deploy, as a traditional pipeline diagram would.

The diagram above is the payoff of everything in this section: it traces a single breach in bands.yaml through open_incident, into an incident record, into a freshly generated intent.md, and back into the Plan stage this guide started with. That arrow, from Maintain back to Plan, is the one line most teams' engineering processes are missing today, even ones that have adopted an agentic coding tool for the Build stage.

Buying a fast agent for Build without building this feedback arrow gets you fast code (and the same slow, manual incident-to-roadmap process every team already had). The arrow is what makes the six stages a cycle instead of six separate improvements that happen to sit next to each other.

How One Engineer Covers a Five-Person Team

Everything above assumes a team large enough to have a dedicated person for planning, one for review, one for release management, and one for on-call. But a growing number of the engineers reading this don't have that team.

GitHub's Octoverse 2025 report found that nearly 80 percent of developers who joined GitHub in the past year used Copilot within their first week, which suggests that AI-assisted development is more and more becoming the default entry point for a new engineer's career, rather than an advanced technique layered on top of years of experience (GitHub).

Combine that with Stack Overflow's finding that roughly half of professional developers already use an AI tool daily (Stack Overflow), and the engineers seriously considering a solo or two-person startup with this stack aren't a fringe case. It's close to the median new developer.

Here's what the six stages look like when one person, or a founding pair, runs all of them, using a worked example: a solo engineer building a scheduling tool for independent contractors, aiming to ship a paid beta in six weeks.

The Plan Stage:

Plan replaces a product manager's job of turning a customer conversation into a spec. The founder talks to three contractors about why existing scheduling tools frustrate them, pastes the raw notes into intent.md, and runs a Plan-mode session to turn three separate rambling conversations into one problem statement: contractors need to see all of their client calendars overlaid without giving each client platform admin access to the others.

That fifteen-minute session replaces what a two-person team would spend a week doing across customer interviews and a requirements doc.

The Design Stage:

Design replaces an architect's whiteboard session. The same session, still in a read-only mode, produces spec.md: a calendar-overlay service, OAuth against each client's calendar provider, a single unified view, explicitly rejecting a real-time sync in favor of a five-minute polling interval for the beta because real-time sync was the thing most likely to blow the six-week deadline. Writing "explicitly rejected: real-time sync, because of timeline" into the spec is what stops the founder from relitigating that decision under pressure in week five.

The Build Stage:

Build replaces a full engineering team. With plan.md naming the calendar integration, the auth flow, and the unified view component in order, an agentic coding tool implements each piece against a CLAUDE.md (or AGENTS.md, or GEMINI.md) that encodes the stack decisions the founder made once: which calendar library, which auth pattern, and where business logic lives. Every reader of this guide already expected this part to be fast. Whether the beta ships on time depends on the parts around it.

The Test Stage:

Test replaces a QA engineer. Because a hook runs the test suite after every file edit, the founder never debugs a week's worth of untested agent output the night before a demo. The discipline of writing the test criteria into plan.md before Build starts, rather than testing after the fact, is what a dedicated QA engineer would've insisted on.

The Deploy Stage:

Deploy replaces a release manager. A GitHub Action running an automated code review on every pull request, with a human gate specifically on anything touching the OAuth flow or billing, gives the founder the layered review Anthropic's framework describes without a second engineer to pair with. The founder still reads every diff that touches money or credentials personally.

The Maintain Stage:

Maintain replaces an SRE on-call rotation. A bands.yaml watching API error rate and polling job success rate, wired to page the founder's phone directly rather than a shared on-call tool nobody is rotating through, is the entire incident response function for a company this size. When the polling job's error rate breaches its band at 2 a.m., the resulting incident record becomes next week's first intent.md instead of a bug the founder half-remembers by Monday.

Judgment still matters as much as it always did. What disappears is the coordination overhead that used to require a team: the committed file now holds explicitly what a team of specialists used to carry implicitly in separate heads.

That's the argument for bootstrapping with an AI-native SDLC: artifact-driven development lets one person's expertise cover ground that used to require distributing it across several people's job titles.

Pre-flight Checklist Before You Go All-in on an Agentic AI-Native SDLC

Before restructuring a team's workflow around this framework, work through the following, grouped by stage:

Plan and Design

• [ ] An intent.md template exists in the repository, and every new piece of work starts from a filled-in copy of it.

• [ ] A spec.md template exists with an explicit "open concerns" section that a human reads before Build starts.

• [ ] At least one person other than the requester confirms the agent's summary of the intent before it becomes a spec.

Build

• [ ] A memory file (CLAUDE.md, AGENTS.md, or GEMINI.md) exists, is checked into version control, and names commands, architecture, and conventions, rather than just placeholder text.

• [ ] plan.md names the specific files, order of changes, and tests before implementation starts.

Test

• [ ] A hook, pre-commit check, or equivalent local gate runs the test suite automatically and blocks progress on failure.

• [ ] Test results are attached to the specific commit they verify, not just reported as a pass or fail in chat.

Deploy

• [ ] A first-party CI action (Claude Code, Codex, or Gemini) runs an automated review on every pull request.

• [ ] A human approval gate is explicitly required for changes touching auth, payments, migrations, or infrastructure, regardless of what the automated review found.

• [ ] Auto-merge, if enabled at all, is scoped to a defined low-risk category, not the default for every green check.

Maintain

• [ ] A monitoring configuration defines acceptable bands for the metrics that matter to the business, not every metric the platform happens to expose.

• [ ] At least the highest-severity breach category is wired to automatically draft a new intent.md, closing the loop back to Plan.

• [ ] Someone, even if it's the same person running every other stage, is responsible for reading and acting on the incidents this stage generates.

Conclusion

You now have a working mental model for restructuring a software team's lifecycle around agentic coding tools, plus three concrete implementations. The six stages (Plan, Design, Build, Test, Deploy, Maintain) haven't changed names. What changed is the artifact each stage produces and the tool that produces it.

• intent.md captures the problem before anyone interprets it, whether that interpretation happens in Claude Code's Plan mode, Codex's read-only sandbox, or Gemini CLI's plan approval mode.

• spec.md and plan.md turn an agent's speed into an asset instead of a liability, by giving it a target to build against that a human already reviewed.

• Hooks, CI actions, and native code review products replace a testing phase with continuous verification, woven into every commit rather than bolted on at the end.

• Layered review puts human judgment where it still adds the most value: at the gate for changes with blast radius, rather than at every line of every diff.

• A bands-style monitoring configuration closes the loop, turning a production incident directly into the next cycle's intent.md instead of a postmortem nobody reopens.

The common thread across every stage in this guide is the same one METR's task-doubling curve implied at the start: the constraint on how fast software ships has already moved, whether or not your process has caught up. Teams that keep treating Build as the bottleneck will keep optimizing the one stage that stopped being the problem.

What to Explore Next

• Anthropic's AI-native SDLC playbook, the primary source for the six-stage framework this guide implements

• DORA's 2025 State of AI-assisted Software Development Report, for the adoption and trust data behind the opening hook

• METR's research on AI task-length doubling, for the full methodology behind the seven-month doubling curve

• Claude Code's documentation hub, starting from the memory file page and branching out to permission modes, hooks, and subagents

• OpenAI's Codex documentation on agent approvals and security, for the full detail on the sandbox and approval-policy split

• Gemini CLI's configuration reference, for the current state of its approval modes and extension system

Visit my GitHub to explore the 30+ open-source software solutions and developer tools I built and shared using the agentic AI-native engineering process.

As agentic systems mature, much of the work developers have them do is delegated, one subagent at a time. Many teams are also exploring and using a shared, multi-tenant Agentic Infrastructure, where cost isn't tied to a single owner. That's where Observability becomes key to monitoring infrastructure costs.

In this guide, you'll learn how observability works, then enable Claude Code's built-in telemetry, run a backend to collect it, and read the metrics, logs, and traces it emits. This will help you start tracking your team's costs more effectively, and it'll only improve as emitted telemetry matures and correlates more cleanly with your sessions.

Note: In its current state, the emitted telemetry from Claude Code provides no attributes that allow a reliable map to named sessions. Usage can be tracked using session_id, but it's still clumsy in a longer session mixing multiple prompts/skills.

This guide is scoped to Claude Code's telemetry for metrics, logs, and tracing. Note that it applies to Linux and macOS only.

Table of Contents

• Observability with OpenTelemetry

  • Telemetry Data

• Instrumenting Claude Code

  • Pull vs Push: How Telemetry Leaves an App

  • When to run a Collector

  • Prerequisites

  • Setup

• Exploring Telemetry

  • Metrics

  • Logs

  • Tracing

• Conclusion

• References

Observability with OpenTelemetry

Observability is the ability to answer questions about a system's runtime behavior from the data it emits. You do this without looking into its internals, attaching a debugger, reading source code, or manually trying to reproduce the behavior.

Here, a system's runtime behavior means what's externally visible. You can ask questions like:

• How much time 95% of all requests take.

• What the failure rate is across all requests received.

• What the cache hit ratio is for the in-memory cache the service uses.

• The difference between the configured and deployed replica counts for a service.

For Claude Code, the inaccessible inner workings are: how it manages context, how work is divided across multiple LLM calls, and how subagents are orchestrated. But you can read the emitted telemetry from Claude code to answer questions like:

• How much a dev or a team spent over a day, week, or month.

• How that usage is distributed across the supported models and effort levels.

• How many tokens are spent per dollar, and how much that varies by type (input, output, cacheRead, cacheCreation).

• When a compaction event kicked in, and by how much it reduced the context's token usage.

Only an instrumented system can answer these questions. Instrumentation is a piece of code added by the developer or built into the tool that records a program's runtime behavior and emits it as telemetry. For example, a measurement like this request spent 100 tokens.

The telemetry data helps avoid silent failures by providing a well-structured data trail of the system's behavior over time. For example, here's a chart from GitHub's August 17, 2026 outage postmortem explaining a rise in GitHub Actions runs over time from ~30M to ~110M:

Telemetry Data

The emitted telemetry consists of three categories of data:

• Metrics: Numeric measurements aggregated over a time window, like queries per second (QPS).

• Logs: A detailed record of an individual event, with a timestamp. For example, a compaction event in Claude Code.

• Traces: The path of one request through the system, split by time into nested requests. For example, an order-placement request on an ecommerce website, showing which internal services it calls to complete the request.

OpenTelemetry (https://opentelemetry.io/) is an observability framework that helps you generate, collect, and export these signals to a backend, which handles storage, querying, and visualization. Keeping that split makes it tool/vendor agnostic where the backend can be open-source or proprietary. It provides instrumentation SDKs for multiple programming languages.

Instrumenting Claude Code

Instrumentation code usually runs alongside the application, at the points best for measuring: a middleware with a request arriving or a response going out, or a token being counted.

It is plugged into the application in two ways:

1. A Shared Instrumentation Library: Applications using an open source framework can add an instrumentation library as a dependency and link it with the application's lifecycle methods. OpenTelemetry publishes instrumentation libraries for many frameworks (Example: Spring Framework).

2. Customized Implementation by Application Developers: Telemetry data emitters are added directly in the codebase using the OpenTelemetry SDK. For a closed-source product, the code is private, but it can still emit telemetry data compatible with OpenTelemetry standards.

Example: HTTP Instrumentation

Middleware in HTTP handling is a common codepath for all requests, which is why it's chosen for application-wide settings like authentication. The same reason makes it a good place for instrumentation code: wrap the handler once, measure every request.

The diagram shows where instrumentation sits relative to the request path.

• A client request passes through an HTTP middleware before reaching the application's request handler and downstream calls. The middleware uses SDK constructs to time the handler and record duration, status, and a count.

• The SDK then buffers those measurements and pushes OTLP to the Collector on a background thread, off the request path.

Claude Code is the second case, where both the core app and its instrumentation module are provided by Anthropic. The code that measures token usage, cost, and tool calls is built in and emits OpenTelemetry over OTLP. As a Claude Code user, you only need to enable the telemetry and prepare a backend to receive and analyze it.

Note: OTLP is a telemetry data delivery protocol designed in the scope of the OpenTelemetry project. This guide assumes end-to-end compatibility with OTLP. Wiring up incompatible telemetry or using incompatible backend components can give unpredictable results and is out of scope.

To collect, store, and read the telemetry, you'll need the following components:

• OpenTelemetry Collector: A vendor-agnostic implementation of how to receive, process, and export telemetry data. This is optional but great to have for personal setup. Must have for a production use case.

• Jaeger: Distributed tracing backend, released as an open source tool by Uber.

• Prometheus: Collects and stores metrics as Timeseries Data.

• Loki: Scalable Log Aggregation system by Grafana.

• Grafana: for UI visualization of logs, metrics, and traces.

Pull vs Push: How Telemetry Leaves an App

Telemetry leaves an application in one of two ways:

Pull (Scrape): The app exposes its current metrics on an HTTP endpoint, and a scraper (Prometheus) reads that endpoint periodically. Every running instance needs its own port, and the scraper must know all of those addresses ahead of time. The app is passive: the scraper drives the data movement. This suits long-lived processes with stable addresses.

In OpenTelemetry, pull-based scraping is configured with OTEL_METRICS_EXPORTER=prometheus (see the SDK environment variables for the accepted exporter values).

By convention, the app makes its metrics available at http://localhost:9464/metrics. This exporter handles metrics only.

Push (OTLP): The app sends its telemetry to a receiving endpoint on a regular interval. This is more flexible: any number of processes can push to the same endpoint with no registration ahead of time, so apps can start and stop freely even as their addresses change.

In OpenTelemetry, push is configured with OTEL_METRICS_EXPORTER=otlp, which ships over the OTLP exporter.

The push model can carry metrics, logs, and traces.

When to Run a Collector

A Collector is deployed when the existing stack isn't enough to handle the system's growing scale and complexity. It helps in the following ways:

• One export config: every producer points at the Collector instead of each carrying its own per-backend exporter setup.

• Outbound-only connections: enterprise networks often block the inbound connections a pull-based scraper needs. With a Collector, the app pushes out to it and it pushes onward, so nothing has to accept inbound traffic.

• Fan-out and translation: the Collector can convert telemetry into a vendor's storage format and send the same signal to more than one backend.

• Buffering: if a backend goes down, the Collector holds the data and retries, absorbing transient failures.

• Processing: it can apply processors before data leaves for storage, such as redacting attributes.

Note: This guide runs a push-based configuration with a Collector even though the setup is single-user. The stack has three backends that store and query data differently, and letting the Collector receive Claude Code's OTLP once and route each signal to the right place is simpler than wiring the app to all three. That's why the tool list calls it optional for personal use but a must-have in production: its value grows with the number of producers and backends.

Prerequisites

Each section in this guide links relevant docs, but you'll make faster progress if the tools and query languages specified below are already familiar:

You'll need

• Latest version of Claude Code

• Docker Engine (29.4.1+) with Docker Compose.

  • Capacity to run 5 Containers (4-core CPU, 8GB RAM, 15GB Disk)

• A Claude Plan that includes Enhanced Telemetry beta (Pro+ / Max)

• Git

• Ensure these ports are free at localhost:

  • 3000 (Grafana)

  • 3100 (Loki)

  • 4317/4318 (OTel Collector OTLP gRPC/HTTP)

  • 9090 (Prometheus)

  • 16686 (Jaeger UI)

Knowledge that would help

• Docker Compose: bringing up containers defined in compose file, reading container status and logs by docker compose ... commands.

• Bash and Config files: Setting environment variables, editing JSON files.

• PromQL (Prometheus): How to use counters/gauges, range selectors, and sum / increase / rate / by (label) grouping.

• Grafana: Explore a datasource, build dashboards with stat and timeseries panels. Panel transformations and Global variables.

• LogQL (Loki): stream selectors, logfmt, and label_format.

• Jaeger and tracing: the trace/span model (parent-child spans, span count, duration) and the Jaeger UI's tag search.

• Claude Code's execution model: sessions, subagents, skills, tools, and context compaction.

• Claude billing basics: tokens and the prompt-caching tiers.

Setup

The test observability stack is deployed using Docker Compose. For telemetry export to work, Claude Code must be able to reach Collector's OTLP endpoint which is localhost:4317 (gRPC) or localhost:4318(HTTP) when running on same machine. All backend services run in a container with their own Docker volume for persistence.

The diagram shows how the telemetry components we're using are linked.

• Apart from Claude Code, every component runs in a container managed by Docker Compose.

• Multiple instances of Claude Code running on any machine (host or cloud VM) should be able to export telemetry to the Collector as long as those machines have connectivity to it (ports 4317/4318 of the host running the Collector container are reachable).

Moving from top to bottom:

• Claude Code exports all three signals over OTLP to the Collector.

• The Collector then splits them by type, pushing traces to Jaeger and logs to Loki, while exposing metrics on port 8889 for Prometheus to scrape.

• Jaeger, Prometheus, and Loki each persist to their own Docker volume.

• Grafana queries all three as the single dashboard layer.

The goal here is a live stream of telemetry from Claude Code that gets stored in a backend and can be queried on demand, during a session or long after. Two things must be in place:

• Enable telemetry in Claude Code. The instrumentation is built in but emits nothing until telemetry is enabled and its OTLP exporter points at the Collector.

• Run the observability backend. The Collector processes each signal, forwarding it to Prometheus, Loki, and Jaeger for storing and serving queries.

You'll start the backend first, so the telemetry has somewhere to go.

Start the Observability Backend

Before enabling telemetry in Claude Code, ensure the stack is up to collect, process, and read the data. The code for the test observability backend lives in this Github repo.

The repo has the following structure:

.
├── README.md
└── compose
    ├── docker-compose.yml # Docker config for 5 containers in the observability stack. Applies pinned image versions, port mappings and named volumes for each service.
    ├── grafana
    │   └── provisioning
    │       ├── alerting
    │       ├── dashboards
    │       ├── datasources # datasources(Prometheus, Loki, Jaeger) and dashboards. Empty initially.
    │       └── plugins
    ├── jaeger-config.yaml # Jaeger v2, badger (local-file) storage for traces. Ties to the user: root TIP below.
    ├── loki-config.yaml # single-binary Loki, filesystem storage. Near default settings.
    ├── otel-collector-config.yaml # receive/process/export pipeline: OTLP in on 4317/4318, traces out to Jaeger, logs to Loki, metrics exposed on :8889 for Prometheus.
    └── prometheus.yml # a single scrape job against the Collector's :8889, 30s interval.

You'll only need docker compose command to start the containers. It reads docker-compose.yml and starts the containers, linking them to their respective config files.

Connectivity between containers:

All containers start within the same Docker network, which allows them to communicate using container names directly. For example, collector's exporter config uses container names:

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true
  prometheus:
    endpoint: 0.0.0.0:8889
  otlphttp/loki:
    endpoint: http://loki:3100/otlp

Note that it doesn't contain Prometheus config, since Prometheus ends up scraping it from the collector as configured in prometheus.yml:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: otel-collector
    static_configs:
      - targets: ["otel-collector:8889"]

Start the containers using Docker compose:

git clone https://github.com/ps-mir/otel-dev-stack.git
cd otel-dev-stack/compose
docker compose up -d

# Output
 ✔ Volume compose_loki_data                          Created                                                                                                                                          0.0s
 ✔ Volume compose_grafana_data                       Created                                                                                                                                          0.0s
 ✔ Volume compose_prometheus_data                    Created                                                                                                                                          0.0s
 ✔ Volume compose_jaeger_data                        Created                                                                                                                                          0.0s
 ✔ Network compose_default                           Created                                                                                                                                          0.1s
 ✔ Container compose-prometheus-1                    Started                                                                                                                                          4.1s
 ✔ Container compose-loki-1                          Started                                                                                                                                          4.2s
 ✔ Container compose-jaeger-1                        Started                                                                                                                                          4.3s
 ✔ Container compose-otel-collector-1                Started                                                                                                                                          3.3s
 ✔ Container compose-grafana-1                       Started                                                                                                                                          2.7s

Check container status:

# all five services should show "Up"
docker compose ps

# Output
NAME                       IMAGE                                              COMMAND                  SERVICE          CREATED         STATUS         PORTS
compose-grafana-1          grafana/grafana:13.2.0                            "/run.sh"                grafana          3 minutes ago   Up 3 minutes   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
compose-jaeger-1           cr.jaegertracing.io/jaegertracing/jaeger:2.20.0   "/go/bin/jaeger --co…"   jaeger           3 minutes ago   Up 3 minutes   0.0.0.0:16686->16686/tcp, [::]:16686->16686/tcp
compose-loki-1             grafana/loki:3.7.6                                "/usr/bin/loki -conf…"   loki             3 minutes ago   Up 3 minutes   0.0.0.0:3100->3100/tcp, [::]:3100->3100/tcp
compose-otel-collector-1   otel/opentelemetry-collector-contrib:0.159.0      "/otelcol-contrib --…"   otel-collector   3 minutes ago   Up 3 minutes   0.0.0.0:4317-4318->4317-4318/tcp, [::]:4317-4318->4317-4318/tcp, 55679/tcp
compose-prometheus-1       prom/prometheus:v3.11.2                           "/bin/prometheus --c…"   prometheus       3 minutes ago   Up 3 minutes   0.0.0.0:9090->9090/tcp, [::]:9090->9090/tcp

TIP: Jaeger runs as user: root (Compose file) to create the badger dir. Not doing so causes a failure: mkdir /badger/key: permission denied. Jaeger itself doesn't need root permission, but Docker volumes are owned by root:root on first mount.

Enable Telemetry

OpenTelemetry instrumentation, once added to an application, stays disabled until specific configuration enables it.

There are two ways to enable telemetry in Claude Code:

1. Environment Variables

Setting specific environment variables enables telemetry generation. Beyond the standard OTEL_* variables, Claude Code defines its own CLAUDE_CODE_* variables.

This guide uses the following settings:

# master switch: when unset or 0, Claude Code produces no telemetry at all
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# opt into the beta enhanced-telemetry attributes and events (extra session and tool detail)
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

# per-signal exporter selection; "otlp" ships the signal over OTLP.
# other accepted values are "console" (print locally), "prometheus" (metrics only), and "none" (drop the signal)
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp

# OTLP transport: "grpc" talks to the collector's 4317 port; "http/protobuf" would use 4318
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# one endpoint for all three signals: the collector's OTLP listener on the local machine
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# how often metrics are flushed, in milliseconds; the default is 60000 (60s),
# shortened here so a manual check sees fresh data without a long wait
export OTEL_METRIC_EXPORT_INTERVAL=5000

# emit cumulative counters instead of delta (see "Aggregation Temporality" below)
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

Environment variables, however, are process-wide and can affect more than Claude Code. For example,

• Accidentally enabling instrumentation in other applications.

• Interfering with OpenTelemetry code/tests if you're developing your own instrumentation or working on any OpenTelemetry SDK.

2. Claude Code settings.json

OpenTelemetry defines Declarative Config, a YAML based configuration to enable telemetry, but Claude Code doesn't support it. But it lets you set the same env variables in ~/.claude/settings.json. That isn't declarative config, but it's better than shell environment variables because it applies only to Claude Code. An example:

{
  "effortLevel": "medium",
  "tui": "fullscreen",
  "env": {
     "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
     "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
     "OTEL_METRICS_EXPORTER": "otlp",
     "OTEL_LOGS_EXPORTER": "otlp",
     "OTEL_TRACES_EXPORTER": "otlp",
     "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
     "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
     "OTEL_METRIC_EXPORT_INTERVAL": "5000",
     "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "cumulative"
  }
}

Only the env block matters for telemetry. effortLevel and tui are unrelated settings you may already have. The variables match the annotated list above.

Aggregation Temporality

Prometheus counter type metrics only increase over time. Their raw value isn't useful, so you read them through per-second growth (rate()) or total growth over a time window (increase()).

Aggregation temporality decides what number a counter reports on each telemetry export: the change since the previous export(Delta), or the running total since the process started(Cumulative).

A short example. Say Claude Code spends tokens over four 5-second export intervals:

By default, Claude Code emits metrics with AggregationTemporality: Delta. This can be inspected and confirmed from the Collector's container logs using the command:

# Command only works from directory containing docker-compose.yml
docker compose logs otel-collector

Note: To enable detailed logs in the Collector, you need to add the debug exporter to the Collector config.

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger, debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus, debug]

Then restart the container:

# Command only works from directory containing docker-compose.yml
docker compose up -d --force-recreate otel-collector

Log output with AggregationTemporality: Delta:

otel-collector-1  | Descriptor:
otel-collector-1  |      -> Name: claude_code.active_time.total
otel-collector-1  |      -> Description: Total active time in seconds
otel-collector-1  |      -> Unit: s
otel-collector-1  |      -> DataType: Sum
otel-collector-1  |      -> IsMonotonic: true
otel-collector-1  |      -> AggregationTemporality: Delta <---
otel-collector-1  | NumberDataPoints #0

Delta doesn't work well with Prometheus functions like rate()/increase(), since they expect cumulative values.

Setting OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative switches the exported metrics from delta to cumulative temporality. It has been added to both the env and JSON config used in this guide.

As before, you need to restart the Collector container after any config change for it to take effect.

Exploring Telemetry

With telemetry flowing, you can start querying it. Metrics, logs, and traces each answer a different kind of question about Claude Code usage, so the three sections below are largely independent.

The data behind them comes from two places.

• The Metrics and Logs sections query whatever Claude Code usage has accumulated in the backend, so your panels will show your own sessions and the numbers won't match the screenshots. Give it a few real sessions before expecting much to show.

• The Tracing section instead walks a single deliberate run, a custom skill summarizing a batch of meetings, described in enough detail to follow along. You don't need to reproduce it.

Metrics

Metrics are the aggregate, time-windowed view of Claude Code usage. Example: total cost, token volume, and how each trends and breaks down by attributes like model, effort, and token type. Use them to watch spend and spot shifts in consumption.

Each metric is a numeric measurement recorded over time, a time series of timestamped values you can plot or aggregate. Claude Code's metrics are running totals (counters), so a query reports the change over a chosen window rather than the raw value. See Aggregation Temporality above for how that works.

Prometheus is the metrics backend we're using here. It scrapes the Collector, stores the series, and answers queries written in PromQL. Grafana reads the same data for dashboards at localhost:3000. The full list of metrics and their attributes is in the Claude Code monitoring docs.

Open Prometheus in your browser (localhost:9090), type claude in the query field, and you should see the supported metrics:

For each metric below, you'll explore it first using PromQL, and then use the same query to add it to the Grafana dashboard as a panel.

Total USD Spent

claude_code_cost_usage_USD_total represents cumulative usage cost, in USD, tracked per session. It's useful for controlling budgets and spotting sudden spikes in usage.

This is a client-side estimate based on token counts priced at Anthropic's per-model, per-type rates and accumulated. It's completely normal for it to exceed your Claude Code plan's subscription cost.

Note: This metric is more critical if you're paying per raw API call. A subscription gives you a usage allowance with increased but bounded rate limits.

Test the following query in Prometheus first (localhost:9090/query):

sum(increase(claude_code_cost_usage_USD_total[10m]))

increase(...[10m]) gives the counter's growth over the last 10 minutes. sum(...) with no by clause collapses the per-attribute series (model, effort, and others) into one number.

For a Grafana panel, swap the fixed [10m] window for the $__range built-in variable so the value follows the dashboard's time picker:

sum(increase(claude_code_cost_usage_USD_total[$__range]))

To add it as a panel, open Explore, select Prometheus as the data source, and run the query. The result depends on how much you've used Claude Code in the window.

On adding to the dashboard you should get more Panel Options. Select the Stat panel:

This panel needs to be added to the Grafana dashboard.

Total Token Usage

claude_code_token_usage_tokens_total is the cumulative token count, with the same counter shape as the USD cost metric. Read a raw series in Prometheus first to see which labels you can aggregate by. A single series looks like:

claude_code_token_usage_tokens_total{effort="high", exported_job="claude-code", instance="otel-collector:8889", job="otel-collector", model="claude-sonnet-5", otel_scope_name="com.anthropic.claude_code", otel_scope_version="2.1.252", query_source="auxiliary", session_id="e0b9795b-4da3-4171-8fa6-a2866bf44d86", terminal_type="ssh-session", type="cacheCreation"}    213730

The trailing number is the counter value. Key attributes you'll be working with are type, model, and effort. The Token Usage by Type chart below groups on type.

The window total is the same query shape as Total USD Spent, with the token counter:

sum(increase(claude_code_token_usage_tokens_total[$__range]))

Tokens Per USD

Unlike the previous two metrics, this is a derived figure, calculated over a time window as Total Tokens / Total Cost.

sum(increase(claude_code_token_usage_tokens_total[$__range])) / sum(increase(claude_code_cost_usage_USD_total[$__range]))

This one number collapses every attribute combination into a single value. Each distinct combination, for example model A at medium effort versus model B at high effort, is its own time series, and the query sums across all of them.

To analyze a specific combination, run the same ratio split by an attribute and compare.

sum by (model) (increase(claude_code_token_usage_tokens_total[$__range]))
  / sum by (model) (increase(claude_code_cost_usage_USD_total[$__range]))

Swap model for effort or type; the raw series above lists the rest of the labels.

Overall Result:

Stats Panel(6hr window): Total USD Spent ($4.28), Total Tokens Spent (3.02M), and Tokens Per USD (707k).

Token Usage by Type

You'll see how claude_code_token_usage_tokens_total changes over time, broken down by type. A single stat hides the shape, so use a time-series panel.

The type attribute has four values, which differ a lot in cost:

• cacheRead: tokens served from an existing cache entry. They dominate token spend in a long session, and are cheaper than the baseline rate.

• cacheCreation: tokens written into the prompt cache on the first prefix load. Costly.

• input: new, uncached prompt tokens.

• output: model-generated tokens.

To also see the total, use two queries: the per-type breakdown and the un-split total for reference.

# per-type breakdown
sum by (type) (increase(claude_code_token_usage_tokens_total[$__rate_interval]))
# total
sum(increase(claude_code_token_usage_tokens_total[$__rate_interval]))

__rate_interval is Grafana's per-step window for time-series panels, the counterpart to the __range used for the stat panels above.

The two queries running in Explore, before saving them as a panel.

After adding to the dashboard:

Each spike is a burst of Claude Code activity, the flat stretches are idle time. Hovering a point splits the total into the four types: here the total is about 1.0M tokens, of which cacheRead is about 925k (roughly 92%), the rest cacheCreation, output, and input.

TIP: Token consumption is dominated by cacheRead, which is also the cheapest type.

Token Usage by Model and Effort

This is the concrete version of the breakdown suggested under Tokens Per USD: which model and effort pairs are actually consuming tokens.

sum by (model, effort) (
  increase(claude_code_token_usage_tokens_total[$__rate_interval])
)

Here the token counter is grouped by its model and effort attributes. In this window every series is claude-sonnet-5 at either medium or high effort, and one burst of medium effort near 18:13 reaches about 2.6M tokens. The number of unique groupings depends on the cardinality of the chosen attributes.

Logs

A log record is a timestamped event with its full field set attached. You query logs when you want that specific event and the context around it: what happened, when, and with which values.

Metrics are the pre-aggregated form of the same activity. Anything that means counting, summing, or taking percentiles across many records belongs in a metric. If you're aggregating log output downstream, that data should have been a metric from the start.

Logs are the right tool for:

1. Per-event context: the full detail of one occurrence, not a rolled-up number.

2. Discrete or irregular events: a compaction firing, a session start, or an API error.

3. Post-incident forensics: reading raw records back while debugging after the fact.

4. Trace correlation: a log line carrying a trace and span ID drops you into the request it came from.

The log backend we're using here is Loki, queried with LogQL. Running logs through a backend like this buys you:

1. Structured fields: filter and compute on named keys instead of regex over text.

2. Field indexing: label lookups return without scanning every line.

3. Trace and span correlation: pivot from a log to its trace, or pull every log for one trace.

4. Time-bounded queries: each query is scoped to a window, keeping the scan cheap.

Grafana reads Loki for dashboards, the same as it does for Prometheus.

Compaction Event

Compaction is Claude Code trimming its own context when it grows too large. Each compaction emits a log event (event_name="compaction") carrying the token counts before and after (pre_tokens, post_tokens) and the span_id it happened under, so a query over those events shows how often it fires and how much it reclaims each time.

In Grafana Explore, select Loki as the data source and paste the LogQL below. It selects the compaction events, parses their fields with logfmt, and derives a per-event reduction percentage with label_format. The fields only exist once compaction has actually happened, so trigger a few first.

{service_name="claude-code"} | event_name="compaction"
  | logfmt
  | label_format reduction_pct=`{{ printf "%.1f" (mulf (divf (subf .pre_tokens .post_tokens) .pre_tokens) 100) }}`

Deriving reduction_pct for each record is fine here because it stays per-event. A running average across compactions would belong in a metric.

The label_format line adds a reduction_pct label. To show it as a table, switch the panel to Table view and add three Grafana transformations:

1. Extract fields from the labels object.

2. Filter fields by name to keep Time, pre_tokens, post_tokens, reduction_pct, and span_id.

3. Convert field type to turn pre_tokens, post_tokens, and reduction_pct into numbers.

Tracing

Tracing provides a detailed picture of the full path a request takes through an application, from start to completion. Some fundamental concepts behind tracing:

• Span: a timed operation representing a unit of work. Building block for traces. All trace data is recorded as a sequence of spans, and each has a type, its operation name:

  • claude_code.interaction: one prompt and everything Claude Code does to answer it. Normally the root span, so one interaction is effectively one trace.

  • claude_code.llm_request: a single model call inside an interaction.

  • claude_code.tool: a single tool call inside an interaction (Bash, Write, Agent, and so on).

• Trace: a tree of spans representing a request path from start to completion.

• Session: one Claude Code run, identified by session.id. It can result in many interactions and traces.

• Subagent: a nested Claude Code instance started by the Agent tool, running its own interactions.

Jaeger is the tracing backend used here. The Collector forwards spans to it over OTLP. Jaeger stores them and lets you search traces by service and span tags and inspect each one as a span tree. Everything below uses its UI at localhost:16686.

Generating Traces

To generate trace data, this guide will use a test prompt to spawn agents and prepare some text. This prompt was tested with Sonnet 5 at medium effort.

You can paste the prompt directly into Claude Code:

Spawn 4 subagents in parallel, one per topic below. Each subagent researches its topic from your own knowledge and returns a ~150-word summary with 3 key points. Do not have them read files or run commands.
Topics:
1. How TCP congestion control works
2. The CAP theorem
3. How DNS resolution works
4. What a Bloom filter is

Once all 4 return, combine the summaries into one markdown document and write it to summary.md

Note: Ask Claude Code for the session_id in the same session after the prompt finishes. This will be used to find related traces in Jaeger.

Trace By Session ID

The search filters by service = claude-code and the tag session.id=<id>. It returns 6 traces, all rooted at claude_code.interaction, with span counts from 1 to 20 and durations from about 1 second to 33 seconds.

The list alone doesn't say which trace did what. Going through them by hand, or scripting it against the trace API for a real session, gives the following:

A few observations:

• Half the traces are noise. Traces 1, 3, and 4 are single-span interactions with no model call or tool, an idle session being pinged. Trace 2 is a brief exchange. Only Traces 5 and 6 are the run.

• The parallel dispatch is a single interaction. Trace 5 fires all four Agent calls inside one claude_code.interaction. Their nested model calls (7 to 10 seconds each) overlap, so the interaction finishes in about 16 seconds despite roughly 35 seconds of combined subagent LLM time.

• Each subagent's model call is nested under its Agent span and carries an agent_id, so you can tell the four apart.

• agent_id is opaque. There's no agent.name or skill.name. The trace tells you four subagents ran and how long each took, not which topic each was given.

• Spans carry token counts but no USD cost. Each claude_code.llm_request has input_tokens, output_tokens, cache_read_tokens, and cache_creation_tokens, but no USD figure.

• The write is a separate, later interaction. Trace 6 has no Agent spans: one claude_code.llm_request of about 23 seconds produces the combined markdown, then a short Write. The two ScheduleWakeup spans are background coordination.

TIP: From the trace you get the four subagent calls, each with an agent_id, token counts, and timing, but no span says which topic a subagent was handed. In contrast, Metrics can provide attribution by model, effort, and skill.

CAUTION: user_prompt is redacted by default on interaction spans. OTEL_LOG_USER_PROMPTS=1 disables this and logs raw prompt text. Avoid enabling it in multi-user/tenant environments since it exposes prompt content to anyone with access to the telemetry backend.

Conclusion

This guide was an end-to-end walkthrough of observability in Claude Code, enabling its telemetry and collecting each of the three signals in a local backend for analysis.

Metrics give you the ability to dissect cumulative cost and usage readings by attribute over a chosen time period. That matters most in a shared or multi-tenant setup, where cost isn't tied to a single owner and someone still has to account for it.

Logs are records of individual events, useful for digging into exactly what changed during one, like compaction.

Traces show how one prompt expands into subagents and model calls, with timing and token counts on each. That's the starting point for debugging or tightening a complex or multi-agent prompt, though the spans don't yet record which prompt or skill drove a given call.

Some of this telemetry is behind the Enhanced Telemetry beta, so span names and attributes can still change, and gaps like per-call attribution may close as it matures. It's worth re-checking the monitoring docs as the surface settles.

References

• Claude Pricing: Prompt Caching

• Claude Code: Monitoring Usage

• Prometheus: Counter Metric Type

• Jaeger: Finding Traces

• Loki: LogQL Log Queries

• Grafana: Stat Panel

• OpenTelemetry Collector: Configuration

But moving an LLM application from a local prototype to a production enterprise system can reveal a critical reliability issue: overconfidence.

Standard language models are optimized to generate the most statistically probable next token, not to evaluate their own baseline certainty. When confronted with ambiguous prompts, incomplete retrieval context, or out-of-domain edge cases, an unguarded model will confidently invent plausible-sounding falsehoods, hallucinating facts without giving the user any indication of uncertainty.

In mission-critical enterprise environments, an AI application that guesses blindly is a severe business risk. In this guide, you'll learn how to build a production-grade uncertainty framework. I'll walk you through an architecture designed to detect knowledge gaps, compute probabilistic confidence metrics, and gracefully route low-certainty requests to human operators or safe fallback responses.

What We'll Cover

• Prerequisites and Environment Setup

  • Package Installation

  • Local Directory Structure

  • Environment Configuration

• The Challenge: Addressing the Overconfidence Vulnerability

• Understanding the Enterprise Request Lifecycle for Uncertainty Evaluation

  • Step 1: Implementing Layer 1 – Input Intent & Boundary Detection

  • Step 2: Implementing Layer 2 – Semantic Distance & Retrieval Quality Scoring

  • Step 3: Implementing Layer 3 – Probabilistic Logit Analysis & Output Validation

• Operational Insights from Running Uncertainty Detection Systems

• Conclusion

Prerequisites and Environment Setup

To follow this practical guide and run the implementation code locally, you should meet the following baseline requirements:

• Proficiency in writing clean, structured Python code.

• A foundational understanding of Retrieval-Augmented Generation (RAG) concepts and vector embeddings.

• Python 3.9 or higher installed on your computer.

• An integrated development environment such as Visual Studio Code.

Package Installation

Open your terminal and execute the following command to install the necessary external dependencies:

pip install openai sentence-transformers numpy python-dotenv

Local Directory Structure

Organize your workspace with a clean structure to keep execution reproducible:

uncertainty-engine/

│

├── .env

├── README.md

└── app.py

Environment Configuration

Create a .env file in the root directory of your project to store access credentials and threshold configurations:

Code snippet

OPENAI_API_KEY=your_actual_api_key_here
ENVIRONMENT=development
CONFIDENCE_THRESHOLD=0.75

The Challenge: Addressing the Overconfidence Vulnerability

Standard LLMs lack an internal mechanism to declare "I don't know." When a RAG application encounters missing documentation or receives an out-of-scope query, the core model treats the missing data as a text-completion puzzle to be solved at all costs.

Figure 1: Vulnerability architecture of standard LLM pipelines, showing an ambiguous/out of scope request, followed by naive prompt execution, followed by confident hallucination.

Relying on system prompts like "Only answer if you are 100% sure" is ineffective because models easily bypass system prompt constraints when predicting token sequences. Enterprise systems require deterministic code boundaries that evaluate semantic relevance, document distance, and token probabilities independently of the LLM's raw output.

Understanding the Enterprise Request Lifecycle for Uncertainty Evaluation

To prevent uncalibrated outputs, we intercept requests using a deterministic request lifecycle. Every transaction travels through three validation layers before a final output is sent to the end user:

Figure 2: Safe enterprise LLM architecture with fallback escalation, showing a user request passing through input boundary validation, retrieval quality assessment, and output uncertainty checks before a response is delivered.

By decoupling safety decisions from the LLM, your code acts as the decision-making boundary while the language model operates strictly as an analytical generation engine.

Step 1: Implementing Layer 1 – Input Intent & Boundary Detection

The first defensive layer determines whether an incoming query falls within your system's valid domain parameters before calling retrieval pipelines or model APIs.

import numpy as np
from sentence_transformers import SentenceTransformer

class BoundaryDetector:
    def __init__(self, target_domains: list, similarity_threshold: float = 0.45):
        self.encoder = SentenceTransformer("all-MiniLM-L6-v2")
        self.domain_embeddings = self.encoder.encode(target_domains)
        self.threshold = similarity_threshold

    def verify_domain_relevance(self, query: str) -> dict:
        query_vector = self.encoder.encode([query])
        
        # Calculate cosine similarity against domain boundaries
        similarities = np.dot(self.domain_embeddings, query_vector.T) / (
            np.linalg.norm(self.domain_embeddings, axis=1, keepdims=True) * np.linalg.norm(query_vector)
        )
        max_similarity = float(np.max(similarities))
        
        if max_similarity < self.threshold:
            return {
                "is_valid": False,
                "score": round(max_similarity, 4),
                "reason": "Query falls outside operational domain boundaries."
            }
            
        return {
            "is_valid": True,
            "score": round(max_similarity, 4),
            "reason": "Query verified within target operational scope."
        }

if __name__ == "__main__":
    approved_topics = [
        "company VPN configuration",
        "employee payroll schedules",
        "internal IT software deployment"
    ]
    detector = BoundaryDetector(target_domains=approved_topics)
    out_of_scope_query = "What is the optimal baking temperature for sourdough bread?"
    result = detector.verify_domain_relevance(out_of_scope_query)
    print(f"Domain Validation Result: {result}")

This module converts approved operational topics into semantic vector embeddings. When a user submits a query, the script converts the input into an embedding vector and calculates its cosine similarity against defined domain bounds. If the alignment score sits below the threshold, the request stops immediately, saving API compute costs and preventing out-of-domain guessing.

Step 2: Implementing Layer 2 – Semantic Distance & Retrieval Quality Scoring

RAG platforms routinely hallucinate because vector retrieval engines return low-scoring document matches when relevant context is missing. We measure the semantic distance between the query and retrieved context chunks to verify retrieval quality

class RetrievalQualityScorer:
    def __init__(self, minimum_relevance: float = 0.60):
        self.encoder = SentenceTransformer("all-MiniLM-L6-v2")
        self.min_relevance = minimum_relevance

    def evaluate_retrieved_context(self, user_query: str, retrieved_chunks: list) -> tuple:
        if not retrieved_chunks:
            return False, 0.0

        query_vec = self.encoder.encode(user_query)
        chunk_vecs = self.encoder.encode(retrieved_chunks)

        # Compute cosine similarity across retrieved chunks
        scores = np.dot(chunk_vecs, query_vec) / (
            np.linalg.norm(chunk_vecs, axis=1) * np.linalg.norm(query_vec)
        )
        top_score = float(np.max(scores))

        is_sufficient = top_score >= self.min_relevance
        return is_sufficient, round(top_score, 4)

if __name__ == "__main__":
    scorer = RetrievalQualityScorer()
    sample_query = "How do I configure mutual TLS for gRPC services?"
    sample_context = [
        "Standard deployment uses isolated network clusters with automated releases."
    ]
    has_context, score = scorer.evaluate_retrieved_context(sample_query, sample_context)
    print(f"Context Sufficient: {has_context} | Top Match Score: {score}")

This step converts retrieved document chunks into vector embeddings alongside the user query to compute individual similarity scores. If the highest-scoring chunk fails to cross the minimum relevance threshold, the module flags the context as insufficient, blocking the system from sending irrelevant text to the model.

Step 3: Implementing Layer 3 – Probabilistic Logit Analysis & Output Validation

The final layer inspects token generation probabilities (log probabilities) returned by model APIs. When an LLM is unsure of its answers, token distribution entropy increases, revealing uncertainty directly in the API payload.

import math

class OutputLogprobValidator:
    def __init__(self, logprob_threshold: float = -0.35):
        self.threshold = logprob_threshold

    def evaluate_token_certainty(self, token_logprobs: list) -> dict:
        if not token_logprobs:
            return {"is_confident": False, "avg_logprob": -1.0, "perplexity": 999.0}

        avg_logprob = sum(token_logprobs) / len(token_logprobs)
        perplexity = math.exp(-avg_logprob)
        is_confident = avg_logprob >= self.threshold

        return {
            "is_confident": is_confident,
            "avg_logprob": round(avg_logprob, 4),
            "perplexity": round(perplexity, 4)
        }

if __name__ == "__main__":
    validator = OutputLogprobValidator()
    # Simulated logprob arrays from an API output
    unconfident_logprobs = [-0.12, -0.85, -1.20, -0.45, -0.95]
    result = validator.evaluate_token_certainty(unconfident_logprobs)
    print(f"Generation Certainty Assessment: {result}")

This class processes the raw log probabilities of generated tokens to compute an average logprob metric alongside text perplexity. By comparing this value against a calibrated threshold, the application objectively determines whether the model was uncertain during text generation.

Integrating the Verification Layers into a Single Pipeline

We now unify these three isolated verification modules into a single orchestration engine that governs the enterprise request pipeline end-to-end.

class EnterpriseUncertaintyEngine:
    def __init__(self, approved_domains: list):
        self.boundary_layer = BoundaryDetector(target_domains=approved_domains)
        self.retrieval_layer = RetrievalQualityScorer()
        self.output_layer = OutputLogprobValidator()

    def process_request(self, user_query: str, retrieved_docs: list) -> str:
        print(f"\n--- Processing Query: '{user_query}' ---")

        # Check 1: Input Boundary Evaluation
        boundary_result = self.boundary_layer.verify_domain_relevance(user_query)
        if not boundary_result["is_valid"]:
            return f"Request Rejected: {boundary_result['reason']}"
        print("[Pass] Input verified within operational domain.")

        # Check 2: Retrieval Context Quality
        valid_context, ret_score = self.retrieval_layer.evaluate_retrieved_context(user_query, retrieved_docs)
        if not valid_context:
            return f"Escalated: Insufficient ground-truth data retrieved (Score: {ret_score}). Routing to support team."
        print(f"[Pass] Context quality validated (Score: {ret_score}).")

        # Step 3: Simulated LLM Generation & Logprob Verification
        # In production, replace dummy logprobs with actual API responses
        simulated_logprobs = [-0.08, -0.05, -0.12, -0.04]
        certainty = self.output_layer.evaluate_token_certainty(simulated_logprobs)

        if not certainty["is_confident"]:
            return "Fallback Active: Generated output exhibited low token certainty."
        print(f"[Pass] Output probability verified (Avg Logprob: {certainty['avg_logprob']}).")

        return "Response Generated: Navigate to portal.company.internal to reset your VPN credentials."

if __name__ == "__main__":
    domains = ["VPN credentials", "software provisioning", "network settings"]
    engine = EnterpriseUncertaintyEngine(approved_domains=domains)

    # Test Case: Query with valid retrieved context
    context_data = ["To update VPN credentials, access portal.company.internal."]
    final_output = engine.process_request("How do I update my VPN password?", context_data)
    print(f"System Output: {final_output}")

This orchestration class combines input validation, retrieval scoring, and logprob checking into a single execution workflow. It routes requests through each verification checkpoint sequentially, blocking out-of-domain queries, escalating under-retrieved contexts to human support, and filtering low-probability generations.

Operational Insights from Running Uncertainty Detection Systems

Designing uncertainty-aware LLM architectures yields several practical deployment lessons:

• Decouple confidence checks from system prompts: Avoid asking the model "Are you confident in this answer?" inside prompt context. Models frequently generate high self-reported confidence for incorrect statements. Use mathematical indicators like logprobs and vector distances instead.

• Establish clear escalation workflows: Treat "I don't know" as an intentional operational outcome rather than a code failure. Route low-confidence queries directly to internal ticketing queues or human-in-the-loop (HITL) review channels.

• Monitor retrieval metrics for knowledge gaps: Track and aggregate requests that fail retrieval scoring. Low-relevance metrics highlight missing, outdated, or poorly indexed corporate documentation.

• Tune similarity thresholds continuously: Embedding distance metrics are sensitive to document length and vocabulary choices. Periodically evaluate sample system logs to adjust relevance boundaries for optimal precision.

Conclusion

Building production-grade AI applications requires transitioning from naïve prompt engineering to a security-first engineering mindset. While Large Language Models provide powerful natural language capabilities, they're uncalibrated tools that can't natively measure truth or certainty.

By wrapping models in deterministic code boundaries that evaluate input intent, document relevance, and generation probabilities, you transform an unpredictable language model into a reliable enterprise platform: one that delivers helpful answers when confident and knows exactly when to say "I don't know."

Thank you for reading.

I hope this guide offers a clear framework for building uncertainty-aware AI applications within your enterprise environments.

If you would like to discuss AI engineering, Agentic architectures, LLM ops, or AI governance, feel free to connect with me:

• Connect with me on LinkedIn

• Explore my projects on GitHub

As capital expenditure on AI infrastructure increases into the hundreds of billions, hardware is no longer a niche topic reserved only for chip architects. Understanding the physical machinery running modern models has become important for developers, researchers, and tech professionals alike.

The course focusses on Nvidia's latest hardware, tracing how a dual-die GB300 Blackwell Ultra GPU is designed, fabricated, packaged, and networked. Across six structured modules, Kian breaks down:

• Semiconductor Physics & Scaling
  How planar, FinFET, and Gate-All-Around (GAA) architectures work, why GPUs run at lower clock frequencies than CPUs, and how the end of Dennard scaling altered processor design.

• Design & EDA
  The step-by-step pipeline converting Register-Transfer Level (RTL) code into manufacturable mask sets using electronic design automation toolchains like Synopsys, Cadence, and Siemens EDA.

• Fabrication & Cleanrooms
  The mechanics inside leading-edge fabs like TSMC, wafer handling, high-purity North Carolina quartz, and the math behind Poisson defect yield models.

• Lithography & Equipment
  How ASML’s extreme ultraviolet (EUV) scanners bounce 13.5 nm light off atom-flat Carl Zeiss mirrors to pattern features just nanometers wide.

• Memory & Advanced Packaging
  High Bandwidth Memory (HBM3E/HBM4) integration, Through-Silicon Vias (TSVs), and TSMC’s CoWoS-L packaging that binds compute dies together.

• Rack-Scale Systems & Geopolitics
  Scale-up NVLink fabrics, 135 kW power boundaries, export restrictions, and critical single-point-of-failure choke points across the global ecosystem.

You can watch the full course for free on the freeCodeCamp.org YouTube channel (3-hour watch).

You might even know the basic definition, but knowing what OpenTelemetry is vs how it actually works are two different things.

By the end of this guide, you'll understand how OpenTelemetry works end-to-end, from the moment a request enters your application to the moment you can see it in your observability backend. You'll learn how traces, spans, context propagation, and exporters all fit together into one pipeline.

If you're completely new to OpenTelemetry, don't worry: the next section will get you up to speed before we go any further.

Table of Contents

• What is OpenTelemetry?

• How OpenTelemetry Works

  • Step 1: Instrument Your Application

  • Step 2: OpenTelemetry Creates Telemetry Signals

  • Step 3: Traces Follow Requests Through Your Application

  • Step 4: Context Propagation Connects Work Across Services

  • Step 5: The OpenTelemetry SDK Processes the Telemetry

  • Step 6: Exporters Send the Telemetry

  • Step 7: The OpenTelemetry Collector Receives and Processes the Data

  • Step 8: An Observability Backend Stores and Analyzes the Telemetry

• Putting the OpenTelemetry Flow Together

• Do You Need Every OpenTelemetry Component?

• Why Use OpenTelemetry?

• Conclusion

What is OpenTelemetry?

OpenTelemetry is an open-source, vendor-neutral observability framework. It gives you a standard way to instrument your application, generate telemetry data, and export that data to any observability backend of your choice.

Before OpenTelemetry, every monitoring tool had its own way of collecting data. If you used Datadog, you’ll have to instrument your app the Datadog way. If you switched to Jaeger, you started over. OpenTelemetry changed that by giving you one standard way to instrument your application, regardless of which backend you use

[!NOTE] OpenTelemetry is not a monitoring platform, dashboard, or data store. It provides the tools and standards for collecting and exporting telemetry from your application to an observability backend, where the data can be stored, queried, and analyzed.

The data OpenTelemetry collects is called telemetry. It's the information your application produces about itself as it runs, and it comes in three forms:

• Traces tell you how a request traveled through your system.

• Metrics give you numbers, like how many requests per second your app is handling, or how much memory it's using.

• Logs are timestamped records of specific events that happened inside your application.

How OpenTelemetry Works

When a request hits your application, a lot happens behind the scenes. OpenTelemetry's job is to capture all of that activity (the traces, metrics, and logs) and send them to the right place.

Here’s what it looks like:

Each stage has a specific job. Let's walk through them one by one.

Step 1: Instrument Your Application

Before OpenTelemetry can capture anything, your application needs to be instrumented. Instrumentation is simply the process of adding code that tells OpenTelemetry what to watch and what to record.

There are two ways to instrument your application: automatically or manually.

1. Automatic instrumentation

This is the easiest one to start with. You add a library to your project, and it instruments your application for you with no changes to your existing code.

For example, if you're running a Node.js Express app, you can add the OpenTelemetry auto-instrumentation package, and it will automatically start capturing incoming HTTP requests, outgoing calls, database queries, and more.

Here's what that setup looks like:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Once this runs before your app starts, OpenTelemetry begins capturing telemetry automatically. For a complete setup guide, see Getting started with OpenTelemetry in Node.js.

2. Manual instrumentation

Automatic instrumentation covers a lot, but it can't capture everything that happens inside your own code. If you want to track what happens inside a specific function, like how long it takes to process a payment or validate a user, you need to add that yourself.

Here's a simple example. Let’s say you have a function that processes an order:

function processOrder(orderId) {
  // processing logic
}

With manual instrumentation, you wrap it like this:

const { trace } = require('@opentelemetry/api');

const tracer = trace.getTracer('order-service');

function processOrder(orderId) {
  return tracer.startActiveSpan('processOrder', (span) => {
    // processing logic

    span.end();
  });
}

What happens is that you created a span. That span now records when processOrder started, when it ended, and how long it took. You'll learn more about spans in Step 3.

For the full manual instrumentation reference, see OpenTelemetry JavaScript instrumentation.

Step 2: OpenTelemetry Creates Telemetry Signals

Once your application is instrumented, OpenTelemetry starts producing telemetry data about what your application is doing. That data comes in three forms, called signals, which we've already briefly talked about: traces, metrics, and logs. Each signal answers a different kind of observability question.

Traces show you how a request moved through your system, which services it touched, and how long each step took. Metrics give you numbers over time, things like request rate, error rate, and memory usage. Logs are timestamped records of specific events that happened inside your application.

Here's a quick comparison:

You don't have to choose between them. In practice, you'll use all three together. A metric tells you something is wrong, a trace shows you where, and a log tells you exactly what happened.

Step 3: Traces Follow Requests Through Your Application

When a user sends a request to your application, that request usually touches multiple services before a response comes back. A trace is the complete record of that journey, from the moment the request enters your system to the moment it finishes.

A trace is actually made up of smaller units called spans. Each span represents one operation, like an API call, a database query, or a function execution, and together they give you the full picture of what happened.

Every trace gets a unique trace ID, and every span gets its own span ID. The trace ID is what links all the spans together. No matter how many services a request passes through, they all share the same trace ID, so you can follow the request from start to finish in your observability backend.

Here's a simple example. A user places an order, and the request flows through four services:

Each span has a start time and an end time, so you can see how long each operation took. If something slowed down or failed, you can pinpoint exactly where it happened just by looking at the spans.

Step 4: Context Propagation Connects Work Across Services

In Step 3, you saw how a single trace is made up of spans from multiple services. But here's a question you need to ask: how does OpenTelemetry know that a span in your payment service belongs to the same trace as a span in your order service?

Without something connecting them, each service would record its own spans independently. Your API gateway would see one operation, your order service would see another, and your payment service would see a third. They'd look like completely separate requests with no relationship to each other, which makes debugging across services nearly impossible.

That's where context propagation comes in. As a request moves from one service to another, OpenTelemetry attaches the trace context to it, typically as HTTP headers. That context carries the trace ID and the parent span ID, so every service that handles the request knows which trace it belongs to and where it sits in the chain.

Here's what that looks like in practice:

All three services share the same trace ID. That's what lets your observability backend connect the spans together into one complete trace.

OpenTelemetry doesn't invent its own rules for this. It follows the W3C Trace Context standard, a widely adopted specification that defines how trace context should be formatted and passed between services, so it works consistently across different languages, frameworks, and vendors.

The good news is that if you're using automatic instrumentation, context propagation happens automatically. OpenTelemetry handles the headers for you, so you don't have to think about it unless you're working with a custom transport or a non-standard setup.

Step 5: The OpenTelemetry SDK Processes the Telemetry

At this point, OpenTelemetry is capturing telemetry and keeping traces connected across services. But between the moment a span is created and the moment it leaves your application, something has to process it. That's the SDK's job.

When your instrumented code creates a span, it does that through the OpenTelemetry API. The API is what you interact with as a developer, things like trace.getTracer() and tracer.startActiveSpan(). But the API alone doesn't process or send anything. It needs the SDK behind it to actually do the work.

Once the SDK receives the telemetry, it runs it through a processor. The processor is responsible for things like batching spans together before sending them, adding extra attributes, or filtering out data you don't need. The most common one you'll see is the BatchSpanProcessor, which groups spans and exports them in batches rather than one at a time, making it more efficient in production.

Before the processor even runs, the SDK also handles sampling. Sampling lets you control how much telemetry you actually collect. In high-traffic applications, recording every single span would generate an enormous amount of data. With sampling, you can tell the SDK to only capture a percentage of traces, which keeps your costs and data volume manageable without losing visibility.

Once the processor is done, it hands the data to the exporter, which is what actually sends it to its destination. You'll see how that works in the next step.

Step 6: Exporters Send the Telemetry

The exporter's job is simple: take the telemetry the SDK prepared and send it to whatever destination you've configured.

OpenTelemetry uses OTLP, the OpenTelemetry Protocol, to transport telemetry data. It's a standard wire protocol designed specifically for transmitting traces, metrics, and logs, and it runs over either HTTP or gRPC.

[!NOTE] OTLP and OpenTelemetry are not the same thing. OpenTelemetry is the full framework, covering instrumentation, the SDK, the Collector, and more. OTLP is just the protocol it uses to transport data.

Although OTLP is the default, not every exporter uses it. Some exporters send data directly to specific backends in their own format, like Jaeger or Prometheus. So depending on your setup, you might use an OTLP exporter to send data to a Collector or backend, or a vendor-specific exporter to send it directly."

Step 7: The OpenTelemetry Collector Receives and Processes the Data

The OpenTelemetry Collector is a standalone service that sits between your application and your observability backend. It receives telemetry data, processes it, and forwards it to one or more destinations.

Using the Collector is common but not mandatory. You can configure your exporter to send data directly to your backend and skip the Collector entirely. But in most production setups, teams add a Collector because it gives them a central place to manage telemetry, without touching application code.

The Collector has three stages:

• Receivers accept incoming telemetry from your applications, typically over OTLP.

• Processors transform the data at the Collector level, things like batching spans, filtering out noise, or adding attributes before forwarding.

• Exporters send the processed data to your backend, or multiple backends if needed.

Here's a minimal Collector configuration:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  otlphttp:
    endpoint: https://your-backend.com

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

This config accepts traces over gRPC, batches them for efficiency, and forwards them to an observability backend over HTTP.

The Collector can also receive data from multiple applications simultaneously and route it to one or more destinations. So instead of each application shipping telemetry directly to your backend, they all send it to the Collector, and the Collector handles the rest.

For the full configuration, see the OpenTelemetry Collector configuration docs.

Step 8: An Observability Backend Stores and Analyzes the Telemetry

This is where OpenTelemetry's job ends. Once your telemetry leaves the Collector, it arrives at your observability backend.

The backend is what stores your data, lets you query it, and gives you the dashboards and alerts you actually interact with day to day. OpenTelemetry doesn't provide any of that. It gets the data there, and the backend does the rest.

A few popular backends that support OpenTelemetry natively:

• Open-source: Jaeger, Prometheus, Grafana Tempo

• Commercial: Datadog, New Relic, Honeycomb, Dynatrace, Elastic, Lightstep, Grafana Cloud, Middleware.

Once your data is in the backend, you can search through traces to debug a slow request, build dashboards to monitor your application's health, and set up alerts when something goes wrong.

Putting the OpenTelemetry Flow Together

Let’s assume a user initiates a bank transfer on a mobile banking app. The request hits your API gateway, and because your application is instrumented, OpenTelemetry immediately starts capturing what’s happening. It creates a span for the incoming request and assigns it a trace ID.

As the request moves to the authentication service, context propagation carries that trace ID along in the request headers. The authentication service creates its own span and attaches it to the same trace. The same thing happens when the authentication service calls the transaction service, and when the transaction service hits the database to process the transfer. Four services and four spans, with one trace ID connecting them all.

Meanwhile, the SDK processes the telemetry in the background, runs the spans through the batch processor, and hands them to the exporter. The exporter packages everything into OTLP and sends it to the Collector, which applies your processing rules and forwards it to your observability backend.

Here’s a summary of every component involved in that flow:

From that single transfer request, you now have a complete trace in your backend. When you open your dashboard and search the trace ID, you'll see every service, every span, and every millisecond of that transaction laid out in front of you.

Do You Need Every OpenTelemetry Component?

To be honest, you don’t need every component to get started with OpenTelemetry. The pipeline you’ve seen throughout this article is the full setup, but not every team uses all of that.

1. Without the Collector: Your exporter sends telemetry directly to your backend with nothing in between. Works well for smaller projects or when you're just getting started.

2. With the Collector: The more common production setup. Teams add the Collector when they need more control, like routing telemetry to multiple backends, filtering sensitive data, or managing telemetry from dozens of services in one place.

The Collector is powerful, but it’s not mandatory. Start without it if your setup is simple, and add it when you actually need it.

Why Use OpenTelemetry?

You've now seen how every piece of OpenTelemetry fits together. Here's why it's worth using:

• Vendor-neutral instrumentation: Before OpenTelemetry, switching observability tools meant you had to re-instrument your entire application from scratch. With OpenTelemetry, you instrument once and switch backends freely.

• Consistent telemetry across services and languages: Your backend might be in Go, your microservices in Python, and your data pipeline in Java. OpenTelemetry has SDKs for all of them, and they all produce telemetry in the same format, so your whole stack speaks the same language.

• Correlated observability signals: Traces, metrics, and logs all flow through the same pipeline. So when something goes wrong, a spike in your metrics leads you to a trace, and that trace points you to the exact log entry where things broke down.

• It's becoming the industry standard: Most observability backends already support OpenTelemetry natively. Instead of learning a vendor-specific instrumentation approach every time you adopt a new tool, you learn OpenTelemetry once and it works everywhere.

Conclusion

OpenTelemetry gives you a standard way to instrument your application, collect telemetry, and ship it to any backend you choose, without locking you into a specific vendor or tool.

If you remember nothing else from this article, remember this: you instrument your application, generate telemetry, process it, export it, and analyze it. Every step has a component behind it, and now you know what each one does.

If you're just getting started, you don't need to set everything up at once. Start with instrumentation, get your telemetry flowing to a backend, and add the Collector when you need it. You can always add more as your needs grow.

If you found this helpful, I'd love to connect. You can find me on LinkedIn or X. Feel free to reach out if you have questions or just want to talk about observability and developer tooling.

You can take the architecture patterns you've learned, the mistakes you've made, the conventions your team follows, and the standards you've developed as a Flutter engineer and teach them to your AI coding agent through agent skills. That means you don't have to choose between your experience and AI. You can bring both together.

But almost every Flutter developer feels a specific frustration the first time they use an AI coding agent on a real project.

You ask the agent to build a profile screen. It produces something that works. But instead of creating a clean, reusable ProfileCard widget in your widgets/ folder, it writes a _buildProfileCard() private method buried inside the screen file.

Instead of separating concerns and placing the StatefulWidget and its state where your carefully designed file structure expects them, it appends both to the bottom of a file that already has ten classes.

The data model uses Map<String, dynamic> instead of your freezed-annotated classes. The imports skip your barrel files and reach directly into internal package paths. The theming ignores your design tokens and uses hardcoded hex values. The error handling uses raw strings instead of your typed failure hierarchy. The state management is Provider when your team uses Bloc.

None of this is wrong in an absolute sense. The agent didn't make mistakes because it's bad at Dart. It made mistakes because it doesn't know how your team writes Flutter code.

This is the problem that agent skills were built to solve.

Agent skills are structured Markdown files that teach an AI agent the "how" of a specific task, not just the "what." When an agent picks up a skill before generating code, it's equipped with your team's conventions, your architectural patterns, your file organization rules, your naming standards, and your quality expectations. The result is code that belongs in your project.

The Flutter team maintains an official repository of skills at github.com/flutter/agent-plugins, and the Dart team maintains a complementary set at github.com/dart-lang/skills. Together they cover responsive layouts, declarative routing, JSON serialization, unit testing, static analysis, package dependency resolution, pattern matching, and more.

But the most powerful skills are the ones you write yourself, the ones that encode your specific experiences as an engineer, your team's specific mistakes, and your project's specific patterns. A skill you write from your own production experience is worth ten generic ones, because it prevents the exact mistakes your team has actually made in the exact codebase your team maintains.

Skills work across every major AI coding agent. Whether your team uses Claude Code, Antigravity, OpenAI Codex, Cursor, GitHub Copilot CLI, or any other compatible agent, skills follow a universal standard. Write the skill once, and it works everywhere.

This handbook covers everything: what skills are, how they work internally, how to install the official Flutter and Dart skills, how to configure skills for each major agent, how to read and understand an existing skill deeply, and most importantly, how to write your own skills that genuinely improve AI output on your specific codebase.

It also covers the essential skills every Flutter team should have, the Dart skills every developer benefits from, and the advanced patterns that make skills compounding over time.

By the end, you won't just know how to use skills. You'll write them with the same intentionality you bring to writing clean Flutter code, and you'll understand why doing so is one of the highest-leverage investments you can make in your team's engineering quality.

Table of Contents

• Prerequisites

• What Are Agent Skills?

• The Problem: Why AI Agents Get Flutter Wrong

• How Skills Work: Progressive Disclosure

• The Anatomy of a Skill File

• Installing Official Flutter and Dart Skills

• Using Skills with Claude Code

• Using Skills with Antigravity

• Using Skills with OpenAI Codex

• Using Skills with Cursor

• Using Skills with Other Agents

• The Official Flutter Skills: A Deep Dive

• The Official Dart Skills: A Deep Dive

• The flutter-file-organization Skill: A Complete Walkthrough

• Writing Your Own Skills: The Complete Guide

• Essential Flutter Skills Every Team Should Have

• Essential Dart Skills Every Developer Should Write

• Skills for Architecture and Large Codebases

• Advanced Skill Patterns

• Package-Level Skills: Teaching the Agent Your Libraries

• Skills vs Rules vs MCP: Knowing the Difference

• Organizing Skills in a Team

• Best Practices for Writing Skills

• Common Mistakes When Writing Skills

• Conclusion

• References

Prerequisites

Before working through this guide, you should have the following in place.

1. Flutter and Dart proficiency

You should be comfortable building multi-screen Flutter apps, working with state management patterns, and following basic clean architecture principles. You don't need to be a senior engineer, but the skill examples in this guide assume you know what a StatefulWidget is, what a repository pattern looks like, why sealed classes matter, and what json_serializable generates.

2. A working AI coding agent

Skills work with agents including Claude Code, Antigravity, OpenAI Codex, GitHub Copilot CLI, Cursor, and others. You need at least one of these installed and working. This guide covers agent-specific setup for all of them.

3. Node.js installed

The skills CLI tool (used to install official skills) is distributed through npm. Run node -v to check. If Node.js isn't installed, download it from nodejs.org.

4. A Flutter or Dart project to work with

The examples and skill exercises in this guide work best when applied to a real project rather than followed abstractly.

5. Basic Markdown familiarity

Skills are written in Markdown. You should know what a heading is (##), what a code block looks like (triple backticks), and what a YAML frontmatter block looks like (the --- enclosed block at the top of a file).

You don't need any special tools beyond these. Skills are plain text files that live in a folder in your project. There's nothing to build, compile, or install beyond the initial CLI command.

What Are Agent Skills?

Think about the difference between hiring a developer who knows Dart and hiring a developer who has worked on Flutter projects similar to yours for two years.

Both can write working Flutter code. But the experienced one knows things that aren't in any documentation: that your team always extracts widget sections into their own files rather than using private build methods, that you use a specific pattern for handling loading states, that your Bloc events are named as past-tense verbs, that you never use BuildContext inside async gaps without checking mounted, and that your team uses fpdart for Either types instead of throwing exceptions across layer boundaries.

A skill is how you give that experienced-developer knowledge to an AI agent. It's a document that describes not just what to do but how to do it, what to avoid, and why the rules exist.

Formally, agent skills provide a standardized way to give your AI agent a set of task-oriented blueprints to follow. By giving the agent actual domain expertise and repeatable workflows, you drastically reduce mistakes and can enforce consistent patterns.

The key word is task-oriented. A skill isn't a style guide. It's a set of instructions tied to a specific category of work.

The Universal Standard

Skills follow a specification maintained at agentskills.io. This specification defines the file format (Markdown with YAML frontmatter), the directory location (.agents/skills/), and the naming conventions.

Because the specification is universal, the same skill files work across Claude Code, Cursor, Antigravity, Codex, and any other agent that follows the standard.

This portability matters for teams. You don't need to write separate skills for each agent. You write one skill, commit it to your repository, and every agent your team uses benefits from it immediately.

Where Skills Live

Skills live in the .agents/skills/ directory of your project workspace. This is the standard location that all compatible agents discover automatically when they start working on a task.

your_flutter_project/
  .agents/
    skills/
      flutter-file-organization.md
      flutter-state-management-bloc.md
      flutter-testing.md
      flutter-theming.md
      flutter-error-handling.md
      flutter-navigation.md
      flutter-feature-architecture.md
      dart-unit-testing.md
      dart-static-analysis.md
      dart-pattern-matching.md
  lib/
  android/
  ios/
  pubspec.yaml

.agents/skills/ is the convention established by the agent skills specification. When an agent starts a session on your project, it discovers this directory, indexes the skill files, reads their metadata to understand what capabilities are available, and loads full skill content only when a task matches a skill's description.

What Makes Skills Different from System Prompts or Rules

A one-time prompt tells the agent what you want right now, in this session. An AI rules file (like .cursorrules or CLAUDE.md) tells the agent project-wide facts that apply to every task. A skill teaches the agent how to perform a specific category of work correctly across all future requests, loaded only when relevant.

When you write a skill for Flutter file organization, you don't need to explain your conventions in the chat every session. Every time you or a teammate asks the agent to create, split, or refactor a Flutter file, the skill loads automatically and provides the same quality guidance. When a new developer joins the team and starts using an AI agent, they get the benefit of every skill the team has written from day one, without needing to be taught the team's standards manually.

The Problem: Why AI Agents Get Flutter Wrong

To understand why skills are necessary, you need to understand the specific and predictable ways AI agents fail at Flutter and Dart without them. These failures aren't random. They trace to a handful of root causes that skills are designed to address.

The Training Data Problem

An AI agent has knowledge of Dart and Flutter from its training data. That training data includes millions of lines of Flutter code from public repositories, documentation, tutorials, and forum answers. It includes old patterns (pre-null-safety Dart), bad patterns (God-class widgets), and patterns that are correct in isolation but wrong for a specific team's standards.

When an agent generates code without a skill, it draws on all of that mixed training data. It might generate code in the style of a 2021 tutorial that uses setState everywhere, or in the style of a repository that uses ChangeNotifier when your team uses Bloc, or it might use Navigator.push when your team carefully uses GoRouter for deep-linking support.

Skills don't replace the agent's existing knowledge. They give it a clear engineering context. Without skills, the agent chooses from a broad mix of patterns with varying quality. With team-defined skills, those patterns are constrained by the project's architecture, conventions, and standards, making the resulting code more consistent with the existing codebase.

The Most Common Flutter-Specific Failures

1. Private build methods instead of extracted widgets.

An agent asked to build a complex screen nests private methods like _buildHeader(), _buildStatsList(), and _buildActionBar() inside the screen class. This is valid Dart but architecturally harmful: these sections should be separate, testable, reusable widget classes in a widgets/ folder.

2. Separating StatefulWidget from State.

When splitting a large file, an agent may move the StatefulWidget class to one file and the State<T> class to another. This breaks a fundamental Flutter compilation constraint. The two must always live in the same file.

3. Ignoring your state management choice.

Without knowing your state management preference, the agent picks whatever pattern it finds most frequently in its training data. One session it generates Bloc. The next it generates Provider. The next it uses setState. All in the same codebase.

4. Using Map instead of typed models.

Without knowing your serialization conventions, an agent defaults to Map<String, dynamic>. If your team uses freezed and json_serializable, every generated model needs to be completely rewritten.

5. Hardcoded visual values.

Agents default to literal values: Color(0xFF6750A4), EdgeInsets.all(16), and BorderRadius.circular(8). If your project has a design system with theme extensions and spacing constants, the agent ignores it entirely.

6. Inline comments everywhere.

Many teams specifically avoid code comments in favor of self-documenting code with descriptive names. Agents default to adding explanatory comments because most training data includes them, requiring cleanup on every review.

7. Wrong import paths.

An agent may import from internal package paths (package:myapp/src/internal/models/user.dart) instead of going through your barrel files (package:myapp/features/profile/profile.dart), creating invisible coupling to internal APIs that should be hidden.

8. Raw exception handling.

Without knowing your error architecture, agents use try-catch with raw Exception objects everywhere, ignoring your team's typed failure hierarchy and making error handling inconsistent across the codebase.

How Skills Work: Progressive Disclosure

The mechanism behind skills is elegant and efficient. Instead of loading every instruction into the context window upfront, the agent only reads the metadata first. It pulls in the heavy, detailed instructions only when it actually needs them for the task at hand.

The Flutter documentation describes this as "progressive disclosure," analogous to deferred loading in Flutter itself.

This design solves a real problem. An AI agent's context window isn't infinite. If every skill loaded its full content for every task, the agent would be burning context budget on irrelevant information. A navigation skill doesn't need to be in context when you're asking the agent to write unit tests. A testing skill doesn't need to be in context when you're setting up routing.

Progressive disclosure keeps the agent's context focused. First, the agent indexes the lightweight metadata of all available skills. When a task arrives, it uses those descriptions to identify which skills are relevant and loads only their full instructions. Unrelated skills remain unloaded, reducing context usage while giving the agent the detailed guidance needed for the task.

This progressive disclosure model means you can have many skills in your project without worrying about context overflow. Having twenty skills isn't twenty times more expensive than having one skill. Only the relevant subset is ever loaded for any given task.

The Anatomy of a Skill File

Every skill follows a specific structure. Understanding this structure deeply is the prerequisite for writing effective skills.

---
name: skill-name-in-kebab-case
description: A clear, specific description that answers: what does this skill cover,
when should it be applied, and what trigger words indicate this task needs this skill?
This is the ONLY part the agent reads when deciding whether this skill is relevant.
aliases: [alternative-name, another-name]
sources: [chat, code]
---

# Skill Title

Brief introduction of what this skill covers and why it exists.

## First Major Section

Content with specific, actionable rules.

## Second Major Section

More rules, examples, counterexamples.

## Code Examples

Concrete code demonstrating the patterns.

The Frontmatter Block in Detail

---
name: flutter-file-organization
description: Organize and split Flutter/Dart files while preserving StatefulWidget
and State relationships. Use when creating, refactoring, splitting, or reorganizing
Dart files and classes. Applies whenever a new screen, widget, model, or Bloc file
is being created or an existing file is being restructured.
aliases: [flutter-files, dart-organization]
sources: [chat, code]
---

name is the unique identifier for this skill across your project. It follows kebab-case convention (lowercase words separated by hyphens) and conventionally starts with the platform or domain (flutter-, dart-, react-, and so on). The name is used by the agent when referencing the skill in its reasoning and by the CLI when managing skills.

description is the most critical field in the entire file. It's the only field the agent reads during the lightweight Phase 1 indexing. A poorly written description means a perfectly written skill body never gets loaded. The description should answer three questions: what does this skill cover, when should it be triggered, and what are the specific trigger words or phrases that indicate this skill is relevant? Notice in the example how the description includes "Use when creating, refactoring, splitting, or reorganizing" along with a comprehensive list of file types. Each of those phrases is a potential trigger that helps the agent match task descriptions to this skill.

aliases provides alternative names for the skill that the agent can use to reference it. These are optional but useful when the skill might be called different things in different contexts.

sources indicates where this skill comes from. For custom team skills, this is typically [chat]. For skills coming from package authors, this might include [package].

The Skill Body Structure

The skill body is pure Markdown with a specific structural discipline that makes it most effective for agent consumption:

# Title Section (h1)
Brief context-setting paragraph. What problem does this skill solve? Why does it exist?
Keep this under three sentences.

## Core Rules (h2 sections)
Numbered or bulleted lists of specific, verifiable rules.
Each rule should be independently actionable.

## Named Sub-Pattern (h2 sections)
More specific guidance for a particular sub-domain of the skill.
Lead with the rule, then show the wrong pattern, then show the right pattern.

## Code Example (h2 sections)
Complete, runnable code that demonstrates the most important patterns.
Always show both wrong and right versions for patterns that agents commonly get wrong.

Agents navigate heading structure to understand skill organization. Clear ## headings that name the sub-topic they cover help the agent find the specific section relevant to its current sub-task within a larger request.

Installing Official Flutter and Dart Skills

The Flutter and Dart teams maintain official skill repositories that represent years of accumulated knowledge about best practices in the ecosystem. These are your starting point.

Installing Flutter Skills

npx skills add flutter/agent-plugins --skill '*' --agent universal --yes

npx skills add runs the skills CLI tool via npm without requiring a permanent installation. flutter/agent-plugins is the GitHub repository path where the official Flutter skills are maintained by the Flutter team. --skill '*' is a wildcard that installs all available skills from the repository rather than selecting specific ones. --agent universal places the skills in the .agents/skills/ directory, which is the universal location all compatible agents look in. --yes skips the interactive confirmation prompt, making this command safe to put in project setup scripts or Makefiles.

After running this command, your project gains skills for responsive layouts, declarative routing with GoRouter, JSON serialization with json_serializable, integration testing setup, widget preview setup, widget testing, architecture best practices with BLoC and Clean Architecture, Bloc state management, Bloc forms, and more.

Installing Dart Skills

npx skills add dart-lang/skills --skill '*' --agent universal --yes

The Dart team maintains a complementary set of skills focused on the Dart language itself, independent of Flutter's widget system. These skills are valuable for both Flutter apps and pure Dart projects like CLI tools, backend services, and packages.

The official Dart skills cover unit test generation, static analysis configuration, package dependency management, pattern matching and sealed classes, CLI application building, test coverage collection and analysis, runtime error fixing with the LSP, mock generation with Mockito, FFI bindings with ffigen, native assets for C and C++ integration, Dart memory optimization, and migrating from old test assertion styles to modern package:checks.

Installing Both at Once

npx skills add flutter/agent-plugins dart-lang/skills --skill '*' --agent universal --yes

Listing both repository names in a single command installs them together and runs dependency resolution once, which is slightly faster than two separate commands. This is the recommended approach for a new Flutter project setup.

Installing Skills from Your pubspec Dependencies

One of the most powerful aspects of the skills ecosystem is that package authors can ship skills alongside their packages. The skills CLI (available as a Dart package) can discover and install skills from all packages in your dependency tree:

dart pub global activate skills
skills get

dart pub global activate skills installs the skills Dart CLI tool globally on your machine. skills get reads your pubspec.yaml and pubspec.lock, finds every package in your dependency tree that ships a skills/ directory, and installs those skills into your project's .agents/skills/ directory automatically.

When you add a package to your project and run skills get, your agent immediately knows how to use that package correctly according to the package author's own instructions. This is a fundamental shift: instead of the agent guessing how a package works, the package author directly equips the agent with the correct usage patterns.

# Update skills whenever your dependencies change
flutter pub get
skills get

Running flutter pub get updates your dependencies. Running skills get immediately after updates the skills to match. Making this a two-step habit ensures your agent always has current skills for your current dependencies.

Verifying Installed Skills

ls -la .agents/skills/

ls -la .agents/skills/ lists all installed skill files with details. You should see .md files named after each installed skill. The -la flags show hidden files and detailed information including file sizes and modification dates.

Once installed, test your agent's awareness of the skills:

Which of my installed skills can help me with creating a new feature screen?

The agent responds with the skills it found that are relevant to that task, confirming they're loaded and indexed correctly. This is a good first test whenever you add skills to a project.

Using Skills with Claude Code

Claude Code is Anthropic's agentic coding assistant that runs in your terminal. It's one of the most powerful agents for complex, multi-step Flutter development tasks and has excellent support for the skills standard.

Installing the Flutter Plugin for Claude Code

The recommended approach for Claude Code is installing the full Flutter plugin, which bundles skills with MCP server configuration:

claude mcp add flutter-mcp -- dart pub global run dart_mcp_server
npx skills add flutter/agent-plugins --skill '*' --agent claude-code --yes
npx skills add dart-lang/skills --skill '*' --agent claude-code --yes

claude mcp add flutter-mcp registers the Dart MCP server with Claude Code. The MCP server gives Claude Code access to Flutter documentation, pub.dev package information, and Dart tooling directly without making web searches. --agent claude-code in the skills add command places skills in the Claude Code specific location if it differs from the universal .agents/skills/ directory, though Claude Code also reads from the universal location.

Claude Code Skills Directory

Claude Code reads skills from .agents/skills/ (the universal location) automatically. It also reads from .claude/skills/ if you prefer to keep Claude-specific skills separate from universal skills.

your_project/
  .agents/
    skills/
      flutter-file-organization.md    <- universal, works everywhere
      flutter-bloc-state-management.md
  .claude/
    skills/
      claude-specific-workflow.md     <- Claude Code only
    CLAUDE.md                         <- Claude Code rules file

Claude Code Rules vs Skills

Claude Code uses a CLAUDE.md file at the project root (or in .claude/) as a rules file: project-wide instructions that are always in context regardless of task.

Skills are loaded progressively. Use CLAUDE.md for project facts (what package this is, what SDK version, or what state management library is installed). Use skills for task-specific expertise (how to implement Bloc, how to organize files, or how to write tests).

# CLAUDE.md example

This is a Flutter app called Kopa, a personal budgeting tool.

## Technical Stack
- Flutter 3.47 with Dart 3.10
- State management: flutter_bloc ^9.0.0
- Navigation: go_router ^14.0.0
- Data layer: firebase_ai ^2.0.0 for AI features
- Serialization: freezed + json_serializable
- Testing: bloc_test, mocktail

## Package Name
com.example.kopa

## Minimum SDK
Android API 24, iOS 15

## Project Structure
Feature-first with clean architecture layers.
See the flutter-feature-architecture skill for full structure details.

CLAUDE.md contains facts about the project that never change between tasks: the app name, the packages in use, the SDK versions, and the minimum platform targets. Skills contain the expertise for how to work with those packages and structure that code correctly.

Using Skills in a Claude Code Session

Once skills are installed, Claude Code uses them automatically. You don't need to invoke them manually. When you ask:

Create a UserProfile feature with Bloc state management, 
a repository that fetches from Firestore, and a screen 
that shows loading, data, and error states.

Claude Code detects that this request involves multiple skill domains (feature architecture, Bloc state management, file organization, and potentially theming and error handling), loads the relevant skill files, and generates code that follows all of your team's conventions simultaneously.

You can also be explicit:

Using the flutter-bloc-state-management skill, implement 
the CartBloc for the shopping cart feature.

Naming the skill explicitly tells Claude Code to load that specific skill regardless of whether it would have detected the need automatically.

Using Skills with Antigravity

Antigravity is Google's AI coding assistant, deeply integrated into the Flutter ecosystem and developed alongside the Flutter team. It has first-class support for agent skills and is one of the agents most thoroughly tested with the official Flutter skills.

Installing the Flutter Plugin for Antigravity

Open Settings in Antigravity by pressing Cmd+, (Mac) or Ctrl+, (Windows/Linux)
Click the Customizations tab
In the Build with Google Plugins section, click Customize
Click Download next to the Dart and Flutter integration

This installs the official Flutter plugin for Antigravity, which bundles skills, MCP server configuration, and rules in a single step. It's the recommended installation path because it ensures all three components (skills, MCP, and rules) are correctly configured together.

Manual Skills Installation for Antigravity

If you prefer manual installation or need to add custom team skills:

npx skills add flutter/agent-plugins --skill '*' --agent antigravity --yes
npx skills add dart-lang/skills --skill '*' --agent antigravity --yes

--agent antigravity targets the Antigravity-specific skills directory, though Antigravity also reads from the universal .agents/skills/ location.

Antigravity Workflows with Skills

Antigravity supports "workflows," which are pre-defined task sequences that can reference skills. You can create a workflow for common team tasks:

# .antigravity/workflows/new-feature.md

## Create New Feature Workflow

Apply skills: flutter-feature-architecture, flutter-bloc-state-management, 
flutter-testing, flutter-file-organization

Steps:
1. Create the feature folder structure.
2. Create the domain model using Freezed.
3. Create the repository interface and implementation.
4. Create the Bloc with its events and states.
5. Create the screen widget.
6. Extract reusable component widgets.
7. Create unit tests for the repository.
8. Create `bloc_test` tests for the Bloc.
9. Create widget tests for the screen.

Workflows that reference skills ensure the agent applies the correct conventions for every step of a multi-step task. Without this explicit referencing, the agent might apply the file organization skill for step 1 but forget to apply the testing skill for steps 7 through 9.

Using Skills with OpenAI Codex

OpenAI Codex is a terminal-based agentic coding assistant similar in spirit to Claude Code. It runs in your terminal and executes multi-step tasks against your codebase.

Installing Skills for Codex

npx skills add flutter/agent-plugins --skill '*' --agent codex --yes
npx skills add dart-lang/skills --skill '*' --agent codex --yes

--agent codex targets the Codex-specific skills directory. Codex also reads from the universal .agents/skills/ directory, so the --agent universal flag works equally well.

Codex Rules File

Similar to Claude Code's CLAUDE.md, Codex reads from an AGENTS.md file at the project root. Configure this alongside your skills:

# AGENTS.md

Flutter project: Kopa budgeting app
Stack: flutter_bloc, go_router, firebase_ai, freezed
Architecture: Feature-first with clean architecture
Test framework: bloc_test + mocktail

AGENTS.md is the project-wide context file that Codex reads on every task. Keep it brief: five to fifteen lines covering the most important project facts. Detailed conventions belong in skills, not in AGENTS.md, because skills load progressively while AGENTS.md always loads.

Plugin Installation Note for Codex

Codex plugins currently can't bundle rules files automatically. This means installing the Flutter plugin from flutter/agent-plugins installs the skills but doesn't automatically create the AGENTS.md file.

Create this file manually after running the plugin installation. The official Flutter documentation provides a template for the recommended AGENTS.md content for Flutter projects.

Using Skills with Cursor

Cursor is an AI-first code editor built on VS Code. It integrates agent capabilities directly into the editing experience and supports skills through a combination of its rules system and the universal .agents/skills/ directory.

Installing Skills for Cursor

npx skills add flutter/agent-plugins --skill '*' --agent cursor --yes
npx skills add dart-lang/skills --skill '*' --agent cursor --yes

Cursor reads skills from .agents/skills/ as part of its agent context. The --agent cursor flag ensures skills are placed correctly for Cursor's discovery mechanism.

Cursor Rules Integration

Cursor uses .cursorrules (or the newer .cursor/rules/ directory in recent versions) for project-wide instructions, analogous to Claude Code's CLAUDE.md:

# .cursor/rules/flutter.mdc

---
description: Flutter project rules applied to all Dart files
globs: ["**/*.dart", "pubspec.yaml"]
alwaysApply: true
---

This is a Flutter project using flutter_bloc, go_router, and freezed.
All state management uses the Bloc pattern.
Feature-first folder structure with clean architecture.
See installed skills in .agents/skills/ for detailed conventions.

globs: ["**/*.dart"] applies this rule only when Dart files are being edited, which prevents the Flutter rules from loading during Markdown editing or YAML configuration. alwaysApply: true ensures the rule is always in context when matching files are open.

The reference to the skills directory at the bottom is intentional: it tells the agent to look at the skills for implementation details rather than making the rules file exhaustively long.

Using Composer and Chat in Cursor with Skills

In Cursor's Composer (the multi-file editing agent), skills load automatically when you describe a task. In Cursor Chat (the inline assistant), you may need to be more explicit:

@flutter-file-organization Create a new PostCard widget 
extracted from the post list screen

The @ prefix in Cursor chat can reference installed skills by name in some configurations. In others, simply describing the task in enough detail is sufficient for the agent to load the relevant skill automatically.

Using Skills with Other Agents

GitHub Copilot CLI

GitHub Copilot CLI supports the universal .agents/skills/ directory when run in agent mode (gh copilot explain and gh copilot suggest):

npx skills add flutter/agent-plugins --skill '*' --agent copilot --yes

Note from the skills CLI documentation that GitHub Copilot isn't auto-detected when using skills get because the .github/ directory is commonly used for other purposes. Always use the explicit --agent copilot flag when installing skills for Copilot.

Gemini CLI

Google's Gemini CLI supports the universal skills directory:

npx skills add flutter/agent-plugins --skill '*' --agent gemini --yes

Universal Installation

If you want a single installation that works for all agents simultaneously:

npx skills add flutter/agent-plugins --skill '*' --agent universal --yes
npx skills add dart-lang/skills --skill '*' --agent universal --yes

The universal agent target places skills in .agents/skills/, which all compliant agents discover automatically. This is the recommended default for teams that use multiple agents or want to be agent-agnostic.

Verifying Agent Discovery

Regardless of which agent you use, you can verify skill discovery with a natural language question to the agent:

Summarize the capabilities of the skills you have available for this project.

A correctly configured agent responds with a list of installed skills and their descriptions, confirming that discovery is working. If the agent says it has no skills or can't find any, check that:

1. The .agents/skills/ directory exists at the project root

2. The directory contains .md files with valid YAML frontmatter

3. The agent supports the universal skills specification

The Official Flutter Skills: A Deep Dive

The official Flutter skills repository (flutter/agent-plugins) contains a set of skills that represent the Flutter team's best thinking on common development patterns. Understanding what each skill covers helps you decide which to install, which to customize, and which to supplement with your own skills.

flutter-responsive-layout

This skill teaches the agent how to build layouts that adapt correctly across mobile, tablet, and desktop breakpoints. It covers AdaptiveScaffold, LayoutBuilder, MediaQuery, Breakpoints, and the patterns the Flutter Adaptive Framework recommends for handling different screen sizes.

Without this skill, agents build layouts that look fine on a single device size and break on others. With it, agents produce layouts that are responsive from the first line of code, using the correct Flutter-specific tools rather than hardcoded pixel thresholds.

flutter-declarative-routing

This skill teaches GoRouter setup, route definition patterns, nested navigation, redirect logic for authentication, deep linking configuration, and the correct way to pass typed parameters between routes.

Without this skill, agents often use Navigator.push even in codebases that carefully use GoRouter everywhere. They also commonly get deep linking wrong and struggle with the typed parameter extraction pattern GoRouter requires.

flutter-json-serialization

This skill teaches the json_serializable and freezed workflow: adding annotations, running build_runner, creating fromJson/toJson methods, handling nullable fields, and using @JsonKey for field name mapping.

Without this skill, agents manually write serialization code or use Map<String, dynamic> throughout the data layer, producing fragile code that breaks silently when field names change.

flutter-add-widget-test

This skill teaches testWidgets, WidgetTester, pump strategies (pump, pumpAndSettle, pumpWidget), widget finders (find.text, find.byType, find.byKey), gesture simulation, and how to wrap widgets in minimal but sufficient test infrastructure.

flutter-add-integration-test

This skill teaches how to set up and run end-to-end integration tests on devices, web browsers, or Firebase Test Lab. It covers test setup, the IntegrationTestWidgetsFlutterBinding, app startup sequencing, and interacting with a fully running app in test.

flutter-bloc

This skill teaches the complete Bloc workflow: defining events, states, and the Bloc class, providing the Bloc with BlocProvider, consuming it with BlocBuilder, BlocListener, and BlocConsumer, and testing with bloc_test.

flutter-apply-architecture-best-practices

This skill enforces Clean Architecture (Data, Domain, Presentation) with the BLoC pattern as the official Flutter team recommends it. It defines layer boundaries, dependency rules, and the repository pattern.

flutter-add-widget-preview

This skill teaches the Widget Previewer system introduced in Flutter 3.47, including the @Preview annotation, how to set up preview infrastructure, and how to write useful previews for complex widgets.

The Official Dart Skills: A Deep Dive

The Dart team's official skills repository (dart-lang/skills) covers the Dart language itself rather than Flutter's widget system. These skills apply to any Dart code: Flutter app logic, Dart CLI tools, Dart backend services, and Dart packages.

dart-add-unit-test

This is the most fundamental Dart skill and the one with the highest immediate impact. It teaches the agent how to write proper unit tests for any Dart class, including:

• Setting up the test/ directory mirroring the lib/ structure

• Writing group and test blocks with descriptive names

• Using setUp and tearDown for test lifecycle management

• Using expect with the right matchers

• Mocking dependencies with mocktail

• Testing async code with expectLater and stream matchers

Without this skill, agents produce tests that test the wrong things, use incorrect assertion patterns, and structure test files in ways that don't mirror the source tree. With it, agents produce tests that follow the package:test conventions correctly from the first run.

# What dart-add-unit-test teaches the agent

## Test file placement
test/features/profile/data/profile_repository_test.dart
mirrors
lib/features/profile/data/profile_repository.dart

## Test naming
```
group('ProfileRepository', () {
  group('getProfile', () {
    test('returns ProfileLoaded when API call succeeds', () async {
      // ...
    });

    test('returns NetworkFailure when connection fails', () async {
      // ...
    });
  });
});
```

## Async testing
```
await expectLater(
  repository.getProfile('user123'),
  completion(isA<Right<AppFailure, UserProfile>>()),
);
```

dart-run-static-analysis

This skill teaches the agent how to work with Dart's static analysis infrastructure: configuring analysis_options.yaml, running dart analyze, applying dart fix --apply, understanding lint rules, suppressing false positives correctly, and enforcing strict type checks.

# What dart-run-static-analysis covers

## analysis_options.yaml configuration
include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  exclude:
    - '**/*.g.dart'
    - '**/*.freezed.dart'

linter:
  rules:
    avoid_print: true
    prefer_final_fields: true
    require_trailing_commas: true

## Correct suppression (when a lint is a false positive)
// ignore: avoid_print  <- line-level, for one occurrence
// ignore_for_file: type=lint  <- file-level, for generated files

Understanding how to configure analysis_options.yaml correctly is one of those tasks where agents frequently make mistakes without guidance: they enable the wrong rules, forget to exclude generated files, or suppress diagnostics too broadly. This skill makes those configurations correct from the start.

dart-tooling

This skill teaches how to resolve package version conflicts in pubspec.yaml, use dependency overrides correctly, understand the difference between direct and transitive dependencies, and read pubspec.lock to diagnose version resolution issues.

Package dependency management is an area where agents frequently hallucinate package versions or suggest dependency_overrides in ways that mask real conflicts. This skill corrects those behaviors.

dart-use-pattern-matching

This skill is one of the highest-value Dart skills because Dart 3's sealed classes and pattern matching represent a genuinely new coding paradigm that agents trained before Dart 3's release don't use consistently. It teaches:

• Switch expressions on sealed classes with exhaustiveness

• Destructuring patterns in switch cases

• Guard clauses with when

• Record patterns

• List and map patterns

• The correct use of _ (wildcard) in patterns

// What the agent learns to write with dart-use-pattern-matching

// Before: traditional switch on enum (old pattern)
switch (state) {
  case AppState.loading:
    return CircularProgressIndicator();
  case AppState.loaded:
    return ContentWidget(data: data);
  default:
    return ErrorWidget();
}

// After: switch expression with pattern matching (idiomatic Dart 3)
return switch (state) {
  AppStateLoading() => const CircularProgressIndicator(),
  AppStateLoaded(:final data) => ContentWidget(data: data),
  AppStateError(:final message) => ErrorWidget(message: message),
};

The destructuring pattern AppStateLoaded(:final data) is pure Dart 3 and extremely clean, but agents without this skill rarely produce it because it wasn't in the training data for older agent versions.

dart-collect-coverage

This skill teaches test coverage collection, LCOV report generation, HTML report generation, and how to filter out generated code (*.g.dart, *.freezed.dart) from coverage reports so the numbers reflect real coverage rather than being inflated by generated code that can't be meaningfully tested.

dart-generate-test-mocks

This skill teaches the mockito and build_runner workflow for generating type-safe mocks from interfaces and abstract classes. It covers adding the annotations, running dart run build_runner build, and using the generated mocks in tests.

dart-fix-runtime-errors

This is a procedural skill: it teaches the agent to use the LSP (Language Server Protocol) to fetch the current stack trace, locate the failing line, apply a fix, and verify resolution using hot reload. This is the correct workflow for fixing runtime errors in a live Flutter app rather than guessing at the cause.

dart-genkit

This skill teaches how to build AI-powered workflows and agents using the Genkit Dart SDK. It's specifically relevant for Flutter developers building AI features, covering flow definition, tool calling, model selection, and streaming.

dart-migrate-to-checks-package

This skill teaches how to migrate from the older package:matcher assertion style to the newer package:checks style, which produces better error messages and is more composable.

// Old style (package:matcher)
expect(result, isA<Right<AppFailure, UserProfile>>());
expect(result.getOrElse(() => null)?.name, equals('Ade'));

// New style (package:checks)
check(result).isA<Right<AppFailure, UserProfile>>();
check(result.getOrElse(() => null)?.name).equals('Ade');

dart-memory

This skill teaches how to prevent memory leaks and reduce garbage collection pressure in Flutter and Dart apps, covering StreamController disposal, AnimationController disposal, closure capture patterns that prevent garbage collection, and how to use DevTools to identify memory issues.

dart-build-cli-app

For Flutter developers who also write Dart CLI tools, backend scripts, or deployment automation in Dart, this skill covers entrypoint structure, argument parsing with package:args, exit codes, subprocess handling, and cross-platform script patterns.

dart-logic-patterns

This skill covers algorithms, data structures, and Dart-specific patterns for organizing business logic: using Iterable methods correctly, choosing between List, Set, and Map for different use cases, implementing efficient search and sort, and using Dart's collection literals productively.

The flutter-file-organization Skill: A Complete Walkthrough

The file organization skill is the most universally applicable Flutter skill and an excellent teaching example for how skills should be structured. Reading it carefully reveals the principles behind every effective skill.

---
name: flutter-file-organization
description: Organize and split Flutter/Dart files while preserving StatefulWidget and State relationships. Use when creating, refactoring, splitting, or reorganizing Dart files and classes.
---

# Flutter File Organization

When creating, splitting, refactoring, or reorganizing Flutter/Dart files, follow these rules.

## Core Rules

1. Inspect the existing file before modifying it.
2. Identify all classes, enums, extensions, mixins, typedefs, and top-level declarations.
3. Identify relationships and dependencies between declarations before splitting them.
4. Keep each independent primary class in its own file.
5. Treat tightly coupled declarations as a single implementation unit and keep them together.
6. Never separate a `StatefulWidget` from its corresponding `State<T>` class.
7. Update all imports and references after moving declarations.
8. Do not introduce unnecessary private helper classes or methods.
9. Preserve existing application behavior. File organization must not change functionality.
10. Run `dart format` on modified Dart files.
11. Run the project's analyzer and relevant tests.

Rule 1 ("Inspect the existing file before modifying it") prevents one of the most common and costly agent mistakes: making assumptions about file contents without reading them.

An agent that skips inspection may duplicate declarations, break dependencies, or introduce naming conflicts with things that already exist. Making inspection an explicit first rule ensures the agent always starts from a complete picture of the current state.

Rules 2 and 3 ("Identify all classes" and "Identify relationships") are mandatory pre-flight checks. Before the agent touches a single byte of a file, it must map everything that exists and how the pieces depend on each other.

This is the equivalent of "measure twice, cut once" applied to code refactoring, and it prevents the most frustrating class of bug: refactors that break things that were working.

Rule 6 ("Never separate a StatefulWidget from its corresponding State class") encodes Flutter-specific compilation knowledge. A developer who knows Dart deeply but doesn't know Flutter could reasonably split a file by moving every class to its own file. They would hit a compile error because _ProfilePageState references the ProfilePage widget through widget, which has a type that State<T> establishes at the class level. The two classes form a single compilation unit that can't be separated. This rule prevents a compile error that no amount of general Dart knowledge would avoid.

Rules 10 and 11 ("Run dart format" and "Run the project's analyzer") close the task-completion loop. Without these rules, an agent declares success after generating files, leaving formatting inconsistencies and possible analyzer warnings for you to discover later. With them, the agent runs both tools before reporting completion, catching issues immediately.

## Widget Extraction

Do not create private `_build...()` methods as a way of extracting substantial widget UI.

For example, do not do this:

```
Widget _buildUserCard() {
  return Container(
    ...
  );
}
```

Instead separate this into a class that is public and place it inside the widgets folder or the components folder.

The Widget Extraction section does four things that every good skill rule should do: states the rule clearly, explains the prohibited pattern precisely (not just vaguely), shows a concrete code example of what not to do so there's no ambiguity, and tells the agent what to do instead.

The _build...() pattern is very common in training data (tutorials often use it for simplicity), which means saying "avoid it" without a concrete example risks not overriding the learned behavior.

Showing the exact code pattern to avoid and contrasting it with the alternative makes the instruction maximally clear.

## Component Extraction

Do not place large amounts of UI inside a single widget.

Extract logical sections into reusable components whenever appropriate.

Examples include:

- Header sections
- Statistics cards
- Filter bars
- Search bars
- Lists
- Table rows
- Buttons
- Empty states
- Loading views
- Form sections
- Dialog content

Favor small, reusable widgets over large build methods.

The example list in the Component Extraction section is drawn from real experience. These are the actual UI sections that accumulate inside screen widgets in production Flutter apps. An agent reading this list will recognize these patterns in the code it examines and know to extract them.

Without the list, "extract logical sections" is too vague for reliable behavior: the agent needs to know concretely what counts as a "logical section."

## Code Comments

Do not write code comments.

This rule applies everywhere and to every layer.

The code comments rule is brief because it's absolute. The phrase "applies everywhere and to every layer" is deliberate. Without this scope qualifier, an agent might interpret the rule as applying only to the current file organization task and revert to adding comments in other files it creates or modifies. The explicit scope removes ambiguity and makes the rule's intent clear across all contexts.

Writing Your Own Skills: The Complete Guide

The official skills are your foundation. But your most valuable skills are often the ones you write yourself, encoding the specific patterns, mistakes, and standards of your own projects.

The Right Mindset for Writing Skills

Writing a skill is not the same as writing documentation for humans. Documentation for humans relies on shared context, implicit understanding, and the ability to ask questions. Skills for agents must be explicit, precise, and assume no knowledge beyond what the skill file contains.

The best skills come from real experience with your codebase. Keep a running list of every time you manually fix AI-generated code. Every fix is a skill rule. When you explain a convention to a new team member, that explanation is skill content. When you catch the same mistake in code review three times in a row, that mistake needs a skill.

Ask yourself before writing any rule: "Would an agent that doesn't know my codebase know to do this?" If the answer is no, the rule belongs in a skill.

The Description: The Most Important Twenty Words

The description field is the gatekeeper. Write it last, after the skill body is complete, so it accurately describes what the skill actually covers. A good description passes this test: if an agent reads only the description, it knows whether this skill is relevant for a given task.

# Poor: too vague, no trigger phrases
description: How to handle state in Flutter apps.

# Better: specific, multiple trigger phrases, clear scope
description: Implement state management using flutter_bloc in Flutter applications.
Use when adding state management to screens, creating new features that have loading
or error states, fetching data from APIs, handling user interactions that change
UI state, or implementing BlocProvider, BlocBuilder, BlocListener, or BlocConsumer.
Applies when you see references to bloc, cubit, state, event, or stream in a task.

The second description is better for several specific reasons. It lists specific trigger scenarios ("creating new features that have loading or error states") that are more likely to match actual task descriptions than the vague "handle state." It includes the API surface of the relevant package (BlocProvider, BlocBuilder) which are likely to appear in task descriptions. And it lists the conceptual keywords (bloc, cubit, state, and event) that serve as signals.

Writing Rules That Change Agent Behavior

Not all rules are equal. Rules that tell an agent to do something it was already doing provide no value. Rules that change what the agent does are the valuable ones. To write rules that change behavior, start from observation: what did the agent actually produce that was wrong, and what rule would have prevented that?

## Rules That Work vs Rules That Do Not

DO NOT WORK (agent was already trying to do these):
- Write clean, readable code.
- Follow Flutter best practices.
- Use appropriate state management.
- Keep the codebase maintainable.

WORK (these change specific agent behavior):
- Extract any widget build section exceeding 30 lines into a separate class in widgets/.
- Never call setState inside a widget that has a corresponding BlocBuilder.
- Name Bloc events as past-tense verbs: ProfileLoadRequested, not LoadProfile.
- Place all Bloc files (bloc, event, state) in a bloc/ subdirectory inside the feature.
- The state class uses sealed keyword: sealed class ProfileState {}.
- Provide super.key in every widget constructor: const MyWidget({super.key}).
- Check mounted before calling setState in any async method.

Notice that working rules contain specific numbers (30 lines), specific folder names (widgets/, bloc/), specific naming patterns with examples, and specific code patterns. Vague rules like "write clean code" describe something the agent already tries to do by default. Specific rules like "name Bloc events as past-tense verbs with concrete examples" change actual output.

The Counterexample Pattern

For rules that address patterns that are common in training data, showing the wrong pattern alongside the right one is significantly more effective than describing the rule in text alone. The agent has seen the wrong pattern thousands of times in training. A text rule may not be strong enough to override that learned behavior. A visual contrast makes the intention unmistakable.

## Error State Naming

Do not name error states with the word "Error" alone at the end.

Do not do this:

```
final class ProfileError extends ProfileState {
  const ProfileError();
}

Include the error context:

final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}

Including the action name (Load) makes the error state specific to the operation that failed. This is important when a single Bloc handles multiple operations that can fail independently. ProfileLoadFailure and ProfileUpdateFailure can coexist meaningfully. ProfileError and ProfileError2 can't.

The explanation after the counterexample ("Including the action name...") connects the rule to the reason, which helps the agent apply the rule correctly in edge cases rather than just following the letter of the rule.

Essential Flutter Skills Every Team Should Have

Based on the most common areas where AI agents produce incorrect Flutter output, here are the essential skills every Flutter team should write and maintain. Each is presented in full, ready to be adapted to your specific conventions.

The Bloc State Management Skill

---
name: flutter-bloc-state-management
description: Implement state management using flutter_bloc. Use when creating new features,
adding state to screens, fetching data from APIs, handling user interactions that produce
loading or error states, using BlocProvider, BlocBuilder, BlocListener, BlocConsumer,
adding a Cubit, or any task involving state transitions in Flutter.
---

# Flutter Bloc State Management

This project uses flutter_bloc for all state management. Do not use setState, ChangeNotifier,
Provider, or Riverpod unless explicitly instructed.

## File Structure

Every feature that requires state management has three Bloc files in a bloc/ subdirectory:

lib/
  features/
    profile/
      bloc/
        profile_bloc.dart      <- Bloc class and handler methods
        profile_event.dart     <- All events as sealed class hierarchy
        profile_state.dart     <- All states as sealed class hierarchy
      screens/
        profile_screen.dart
      widgets/
        profile_card.dart
      profile.dart              <- barrel export

Sealed Classes

Events and states use Dart's sealed class system for exhaustive handling:

// profile_event.dart
sealed class ProfileEvent {}

final class ProfileLoadRequested extends ProfileEvent {
  const ProfileLoadRequested({required this.userId});
  final String userId;
}

final class ProfileUsernameUpdated extends ProfileEvent {
  const ProfileUsernameUpdated({required this.newUsername});
  final String newUsername;
}

// profile_state.dart
sealed class ProfileState {}

final class ProfileInitial extends ProfileState {}

final class ProfileLoading extends ProfileState {}

final class ProfileLoaded extends ProfileState {
  const ProfileLoaded({required this.profile});
  final UserProfile profile;
}

final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}

sealed class makes the hierarchy exhaustive: Dart's compiler can verify that every possible state is handled in a switch statement. final class on concrete implementations prevents unintended subclassing. Every state and event is final and sealed.

Naming Conventions

The Bloc class should use the feature name followed by Bloc, such as ProfileBloc, AuthBloc, or CartBloc. Events should use a past-tense verb phrase followed by the feature name and the Event suffix, such as ProfileLoadRequested or AuthLoginAttempted. States should use the feature name followed by a descriptive noun or adjective, such as ProfileInitial, ProfileLoading, ProfileLoaded, or ProfileLoadFailure.

Don't name events as commands (not LoadProfile, but ProfileLoadRequested). Don't name error states simply as ProfileError. Include the operation: ProfileLoadFailure, ProfileUpdateFailure.

The Bloc Class

// profile_bloc.dart
class ProfileBloc extends Bloc<ProfileEvent, ProfileState> {
  final ProfileRepository _repository;

  ProfileBloc({required ProfileRepository repository})
      : _repository = repository,
        super(ProfileInitial()) {
    on<ProfileLoadRequested>(_onProfileLoadRequested);
    on<ProfileUsernameUpdated>(_onProfileUsernameUpdated);
  }

  Future<void> _onProfileLoadRequested(
    ProfileLoadRequested event,
    Emitter<ProfileState> emit,
  ) async {
    emit(ProfileLoading());

    final result = await _repository.getProfile(event.userId);

    result.fold(
      (failure) => emit(ProfileLoadFailure(message: _mapFailure(failure))),
      (profile) => emit(ProfileLoaded(profile: profile)),
    );
  }

  String _mapFailure(AppFailure failure) => switch (failure) {
    NetworkFailure(:final message) => message,
    ServerFailure(:final message) => message,
    NotFoundFailure() => 'Profile not found',
    UnauthorizedFailure() => 'Please sign in again',
    _ => 'An unexpected error occurred',
  };
}

Each event handler is a private method named _on + EventClassName. The pattern is consistent across all Blocs. Every handler emits a loading state before the async operation and emits either a success or failure state after. No handler returns data directly. All communication is through emitted states.

Widget Integration

class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key, required this.userId});
  final String userId;

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => ProfileBloc(
        repository: context.read<ProfileRepository>(),
      )..add(ProfileLoadRequested(userId: userId)),
      child: BlocConsumer<ProfileBloc, ProfileState>(
        listener: (context, state) {
          if (state is ProfileLoadFailure) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text(state.message)),
            );
          }
        },
        builder: (context, state) => switch (state) {
          ProfileInitial() => const SizedBox.shrink(),
          ProfileLoading() => const Center(child: CircularProgressIndicator()),
          ProfileLoaded(:final profile) => ProfileContent(profile: profile),
          ProfileLoadFailure(:final message) => ProfileErrorView(message: message),
        },
      ),
    );
  }
}

BlocConsumer combines listener (side effects) and builder (UI). The switch expression on sealed states is exhaustive: the compiler enforces that every state has a corresponding UI.

Prohibited Patterns

Don't use setState in any widget that has a corresponding Bloc. Don't call context.read<SomeBloc>().add(event) from inside initState without deferring with addPostFrameCallback. Don't access BuildContext after an await without checking mounted. Don't create a Bloc inside a StatelessWidget.build method (it is recreated on every rebuild).

The Feature Architecture Skill

---
name: flutter-feature-architecture
description: Structure Flutter features using clean architecture with repository, service,
and presentation layers. Use when creating new features, adding screens, implementing
data fetching, organizing existing code, deciding where a new file belongs, or any task
that involves folder structure, layer boundaries, or the project's directory organization.
---

# Flutter Feature Architecture

This project uses feature-first folder structure with clean architecture layers.

Top-Level Structure

lib/
  core/
    constants/     <- app-wide constants, not feature-specific
    errors/         <- AppFailure sealed class hierarchy
    extensions/     <- Dart extension methods
    theme/          <- theme extensions, color tokens, typography
    utils/          <- pure utility functions
  features/
    auth/
    profile/
    home/
    settings/
  shared/
    widgets/        <- widgets used in 3+ features
    models/         <- models shared between features
    services/       <- services used by multiple features
  app.dart          <- MaterialApp setup
  main.dart         <- entry point

Feature Folder Structure

Every feature follows this internal structure:

features/
  profile/
    bloc/
      profile_bloc.dart
      profile_event.dart
      profile_state.dart
    data/
      profile_repository.dart          <- interface
      profile_repository_impl.dart     <- implementation
      profile_remote_data_source.dart
      profile_local_data_source.dart
    domain/
      profile_model.dart                <- freezed domain model
    screens/
      profile_screen.dart
      edit_profile_screen.dart
    widgets/
      profile_card.dart
      profile_header.dart
      profile_stats_row.dart
    profile.dart                         <- barrel export

Layer Dependency Rules

The presentation layer (screens and widgets) depends only on Bloc and domain models. The Bloc depends only on the repository interface (not the implementation). The repository implementation depends on data sources. Data sources depend on external packages (Firebase, HTTP, SharedPreferences).

Never import across layers in the wrong direction. The data layer never imports from the presentation layer. The domain layer imports from nothing in the project.

The Barrel Export File

Every feature has a barrel file that exports only the public API of the feature:

// features/profile/profile.dart
export 'domain/profile_model.dart';
export 'screens/profile_screen.dart';
export 'screens/edit_profile_screen.dart';
export 'bloc/profile_bloc.dart';
export 'bloc/profile_event.dart';
export 'bloc/profile_state.dart';

Internal implementation files (data sources, repository implementation) aren't exported. Consuming code imports package:myapp/features/profile/profile.dart, never deep paths.

The Core Folder Rule

A file belongs in core/ only if it's used by three or more features. If used by only one or two features, it belongs inside those features' folders. Don't preemptively move things to core/ based on where they might be used in the future.

The Error Handling Skill

---
name: flutter-error-handling
description: Implement error handling using typed AppFailure classes and Either return types.
Use when handling errors from API calls, repository methods, Bloc error states, catching
exceptions in data sources, showing error UI, implementing try-catch, or any task that
involves failure, exception, error state, or error message handling.
---

# Flutter Error Handling

This project uses a typed failure system. Raw exceptions do not cross layer boundaries.

The AppFailure Hierarchy

// core/errors/app_failure.dart
sealed class AppFailure {
  const AppFailure();
}

final class NetworkFailure extends AppFailure {
  const NetworkFailure({required this.message});
  final String message;
}

final class ServerFailure extends AppFailure {
  const ServerFailure({required this.statusCode, required this.message});
  final int statusCode;
  final String message;
}

final class CacheFailure extends AppFailure {
  const CacheFailure({required this.message});
  final String message;
}

final class NotFoundFailure extends AppFailure {
  const NotFoundFailure();
}

final class UnauthorizedFailure extends AppFailure {
  const UnauthorizedFailure();
}

final class ValidationFailure extends AppFailure {
  const ValidationFailure({required this.field, required this.message});
  final String field;
  final String message;
}

sealed class AppFailure makes the hierarchy exhaustive. New failure types are added as final class subclasses. The compiler enforces that switch statements on AppFailure handle every possible subtype.

Repository Return Types

Repository methods return Either<AppFailure, T> from the fpdart package:

abstract class ProfileRepository {
  Future<Either<AppFailure, UserProfile>> getProfile(String userId);
  Future<Either<AppFailure, Unit>> updateUsername(String userId, String username);
}

Returning Either makes failure possible-but-explicit at the type level. Consumers of the repository can't accidentally ignore the possibility of failure because the return type forces them to handle both branches.

Data Source Exception Handling

Data sources are the only layer that uses try-catch. They catch raw exceptions and convert them to AppFailure objects:

class ProfileRemoteDataSource {
  Future<Either<AppFailure, UserProfileDto>> getProfile(String userId) async {
    try {
      final doc = await _firestore.collection('users').doc(userId).get();

      if (!doc.exists) return left(const NotFoundFailure());

      return right(UserProfileDto.fromJson(doc.data()!));
    } on FirebaseException catch (e) {
      return switch (e.code) {
        'permission-denied' => left(const UnauthorizedFailure()),
        'unavailable' => left(NetworkFailure(message: e.message ?? 'Network error')),
        _ => left(ServerFailure(statusCode: 0, message: e.message ?? 'Server error')),
      };
    } catch (e) {
      return left(NetworkFailure(message: e.toString()));
    }
  }
}

Prohibited Patterns

Don't use try-catch in Blocs, repositories, or presentation layer code. Don't throw exceptions from repository methods. Don't use String as an error message type in state classes. Use the typed failure. Don't pass raw exception messages to the UI. Map failures to user-friendly messages in the Bloc.

The Theming Skill

---
name: flutter-theming
description: Apply colors, typography, spacing, and visual styling using the project's
theme extension system. Use whenever writing code that involves colors, text styles,
padding, margin, border radius, shadows, or any visual appearance of UI components.
Apply when you see requests involving styling, colors, fonts, spacing, or visual design.
---

# Flutter Theming

This project uses theme extensions for all visual styling. Hardcoded visual values are not permitted anywhere in the codebase.

Color Access

// Do not do this
color: const Color(0xFF6750A4)
color: Colors.deepPurple
backgroundColor: Theme.of(context).colorScheme.primary

// Do this
color: context.appColors.primary
backgroundColor: context.appColors.surface

context.appColors is an extension on BuildContext defined in core/theme/app_colors_extension.dart. It provides typed access to the full color palette with names that communicate intent.

Available colors: use the semantic colors provided through context.appColors.

For branding and surfaces, use context.appColors.primary for the main brand color, context.appColors.secondary for secondary accents, context.appColors.surface for card and container backgrounds, and context.appColors.background for screen backgrounds.

For states, use context.appColors.error for error states and context.appColors.success for success states.

For text, use context.appColors.textPrimary for primary readable text, context.appColors.textSecondary for captions, labels, and secondary information, and context.appColors.textDisabled for disabled controls and text.

Spacing

// Do not do this
padding: const EdgeInsets.all(16)
margin: const EdgeInsets.symmetric(horizontal: 24, vertical: 8)

// Do this
padding: const EdgeInsets.all(AppSpacing.md)
margin: const EdgeInsets.symmetric(
  horizontal: AppSpacing.lg,
  vertical: AppSpacing.sm,
)

AppSpacing is defined in core/constants/app_spacing.dart and provides the following spacing values:

xs: 4 · sm: 8 · md: 16 · lg: 24 · xl: 32 · xxl: 48

Typography

// Do not do this
style: const TextStyle(fontSize: 16, fontWeight: FontWeight.w600)

// Do this
style: context.appTypography.bodyMedium
style: context.appTypography.headlineLarge.copyWith(
  color: context.appColors.textPrimary,
)

context.appTypography is an extension on BuildContext providing the full type scale.

Border Radius

// Do not do this
borderRadius: BorderRadius.circular(8)

// Do this
borderRadius: BorderRadius.circular(AppRadius.sm)

AppRadius constants: xs (4), sm (8), md (12), lg (16), xl (24), round (999).

The Navigation Skill

---
name: flutter-navigation
description: Implement navigation using GoRouter. Use when adding routes, navigating
between screens, implementing deep links, setting up route guards or redirects,
handling authentication-gated routes, working with nested navigation or shell routes,
or any task involving navigation, routing, back button, browser URL, or deep link.
---

# Flutter Navigation

This project uses GoRouter for all navigation. Do not use Navigator.push, Navigator.pushNamed, Navigator.pop (only via GoRouter), or any Navigator API that bypasses GoRouter.

Route Constants

All route paths are constants in core/router/routes.dart:

abstract class Routes {
  static const splash = '/';
  static const login = '/auth/login';
  static const register = '/auth/register';
  static const home = '/home';
  static const profile = '/home/profile/:userId';
  static const editProfile = '/home/profile/:userId/edit';
  static const settings = '/settings';
}

Never use string literals for navigation. Always use Routes.home, not '/home'.

Navigation Methods

// Replace the current location (no back button to previous)
context.go(Routes.home);

// Push on top (back button returns to previous location)
context.push(Routes.profile.replaceAll(':userId', userId));

// Pop (go back)
context.pop();

// Pop with a result
context.pop(result);

Never use Navigator.of(context).push(...). It bypasses GoRouter and breaks deep links.

Router Definition

All routes are defined in core/router/app_router.dart:

final router = GoRouter(
  initialLocation: Routes.splash,
  redirect: _redirectLogic,
  routes: [
    GoRoute(
      path: Routes.home,
      pageBuilder: (context, state) => NoTransitionPage(
        child: const HomeScreen(),
      ),
    ),
    GoRoute(
      path: Routes.profile,
      builder: (context, state) {
        final userId = state.pathParameters['userId']!;
        return ProfileScreen(userId: userId);
      },
    ),
  ],
);

Typed Parameters

Extract path parameters from state.pathParameters, and query parameters from state.uri.queryParameters. Never parse the path string manually.

Essential Dart Skills Every Developer Should Write

Beyond Flutter-specific skills, pure Dart development benefits enormously from team-level skills. These apply to any Dart code: business logic, data processing, testing, or CLI tools.

The Dart Model and Freezed Skill

---
name: dart-models-freezed
description: Create immutable data models using the freezed package with json_serializable
for serialization. Use when creating new data models, DTOs, request or response objects,
value objects, or any Dart class that represents structured data. Applies when working
with JSON parsing, API response mapping, or defining data structures.
---

# Dart Models with Freezed

All data models use the freezed package for immutability and code generation.

Model Definition

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user_profile.freezed.dart';
part 'user_profile.g.dart';

@freezed
class UserProfile with _$UserProfile {
  const factory UserProfile({
    required String id,
    required String name,
    required String email,
    String? avatarUrl,
    @Default(false) bool isVerified,
    required DateTime createdAt,
  }) = _UserProfile;

  factory UserProfile.fromJson(Map<String, dynamic> json) =>
      _$UserProfileFromJson(json);
}

@freezed triggers code generation that produces an immutable class with a named constructor, copyWith for creating modified copies, == and hashCode based on all fields, toString for debugging, and fromJson/toJson via json_serializable.

The part directives are mandatory and must match the filename. user_profile.dart generates user_profile.freezed.dart and user_profile.g.dart.

Field Rules

Use required for fields that must always be present. Use String? (nullable) for optional fields. Use @Default(value) for fields with a sensible default that avoids nullability. And use @JsonKey(name: 'field_name') when the JSON field name differs from the Dart field name.

After Adding or Modifying a Model

Always run:

dart run build_runner build --delete-conflicting-outputs

Never manually edit .freezed.dart or .g.dart files. They're generated and will be overwritten on the next build.

DTOs vs Domain Models

Data Transfer Objects (DTOs) live in data/ and map directly to API shapes. Domain models live in domain/ and represent the app's internal data model.

A DTO may have fields like created_at (snake_case from API). The domain model has createdAt (camelCase). The repository maps from DTO to domain model.

The Dart Pattern Matching Skill

---
name: dart-pattern-matching-idiomatic
description: Use Dart 3 pattern matching, switch expressions, and sealed class hierarchies
for exhaustive control flow. Use when working with sealed classes, enums, discriminated
unions, conditional logic on types, or any switch statement that could be a switch
expression. Applies when refactoring if-else chains, handling multiple subtypes, or
implementing business logic that branches on type.
---

# Dart Pattern Matching

Use Dart 3 pattern matching for all control flow that involves type discrimination, sealed class hierarchies, or structural decomposition of data.

Switch Expressions Over Switch Statements

// Do not do this (switch statement is an imperative flow)
switch (state) {
  case ProfileLoading():
    return const CircularProgressIndicator();
  case ProfileLoaded():
    return ProfileContent(profile: state.profile);
  case ProfileLoadFailure():
    return ErrorView(message: state.message);
  default:
    return const SizedBox.shrink();
}

// Do this (switch expression is a value, works in build methods)
return switch (state) {
  ProfileInitial() => const SizedBox.shrink(),
  ProfileLoading() => const CircularProgressIndicator(),
  ProfileLoaded(:final profile) => ProfileContent(profile: profile),
  ProfileLoadFailure(:final message) => ErrorView(message: message),
};

Switch expressions are values, not statements. They work naturally as the argument to return or as the value of a variable. Sealed class hierarchies make them exhaustive: if you add a new state, the compiler tells you every switch expression that needs to handle it.

Destructuring in Patterns

// Access fields directly in the pattern
case ProfileLoaded(:final profile) => ProfileContent(profile: profile),
// Equivalent to:
case ProfileLoaded() => ProfileContent(profile: state.profile),

The :final field syntax inside a pattern binds the field's value directly in the case branch. This eliminates the need to access state.profile separately and makes the code more concise.

Guard Clauses

return switch (state) {
  ProfileLoaded(:final profile) when profile.isVerified => VerifiedProfileView(profile: profile),
  ProfileLoaded(:final profile) => UnverifiedProfileView(profile: profile),
  _ => const LoadingView(),
};

when adds a guard clause to a pattern. The case only matches when both the pattern matches and the guard condition is true. Guards allow fine-grained branching within a single type.

Record Patterns

// Matching on records
final (name, age) = getUserInfo();

// In switch expressions
final description = switch ((user.name, user.isAdmin)) {
  (final name, true) => '$name (Admin)',
  (final name, false) => name,
};

Records are structural tuples. Pattern matching on records extracts the components directly without named accessors.

Converting If-Else Chains

When you see an if-else chain that branches on type or value, convert it to a switch expression:

// Do not do this
String label;
if (priority == Priority.high) {
  label = 'Urgent';
} else if (priority == Priority.medium) {
  label = 'Normal';
} else {
  label = 'Low';
}

// Do this
final label = switch (priority) {
  Priority.high => 'Urgent',
  Priority.medium => 'Normal',
  Priority.low => 'Low',
};

The Dart Testing Conventions Skill

---
name: dart-testing-conventions
description: Write Dart unit tests following package:test conventions with mocktail mocks,
descriptive group/test naming, and correct async testing patterns. Use when writing any test
file, adding tests to existing files, mocking dependencies, testing async functions,
or verifying error handling behavior.
---

# Dart Testing Conventions

Test File Structure

import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:myapp/features/profile/data/profile_repository_impl.dart';
import 'package:myapp/core/errors/app_failure.dart';

class MockProfileRemoteDataSource extends Mock
    implements ProfileRemoteDataSource {}

class MockProfileLocalDataSource extends Mock
    implements ProfileLocalDataSource {}

void main() {
  late MockProfileRemoteDataSource mockRemote;
  late MockProfileLocalDataSource mockLocal;
  late ProfileRepositoryImpl repository;

  setUp(() {
    mockRemote = MockProfileRemoteDataSource();
    mockLocal = MockProfileLocalDataSource();
    repository = ProfileRepositoryImpl(
      remote: mockRemote,
      local: mockLocal,
    );
  });

  group('ProfileRepositoryImpl', () {
    group('getProfile', () {
      test(
        'returns Right(profile) when remote data source succeeds',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => right(fakeProfileDto));

          final result = await repository.getProfile('user123');

          expect(result.isRight(), isTrue);
          expect(result.getOrElse(() => null)?.id, equals('user123'));
        },
      );

      test(
        'returns Left(NetworkFailure) when remote throws network error',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => left(NetworkFailure(message: 'No internet')));

          final result = await repository.getProfile('user123');

          expect(result.isLeft(), isTrue);
          expect(result.fold((f) => f, (_) => null), isA<NetworkFailure>());
        },
      );
    });
  });
}

Test Naming

Use descriptive test names that follow the pattern "does X when Y" or "returns X when Y".

Examples: returns Right(profile) when remote data source succeeds, returns Left(NetworkFailure) when connection fails, and calls local data source when remote fails.

Avoid using "test" or "should" in test names. For example, use returns profile when repository call succeeds instead of test that profile is returned correctly or should return profile when called.

Mock Setup

Create fresh mocks in setUp, not at the top level of main. This ensures state from one test can't leak into another.

Use registerFallbackValue in setUpAll for any custom types passed to any():

setUpAll(() {
  registerFallbackValue(const ProfileLoadRequested(userId: ''));
  registerFallbackValue(left<AppFailure, UserProfile>(const NotFoundFailure()));
});

Async Testing

// For Future results
final result = await repository.getProfile('user123');
expect(result.isRight(), isTrue);

// For Stream results
expectLater(
  bloc.stream,
  emitsInOrder([ProfileLoading(), ProfileLoaded(profile: fakeProfile)]),
);

Always use await for Futures. Use expectLater with emitsInOrder for Streams. Don't use await Future.delayed(...) in tests. Use pump() for widget tests or mock the async behavior with thenAnswer.

Skills for Architecture and Large Codebases

As your Flutter project grows, the complexity of architectural decisions increases. These skills are designed for larger codebases where consistent architecture is especially important.

The Performance Skill

---
name: flutter-performance
description: Apply Flutter performance best practices including const widgets, selective
rebuilds, lazy loading, and proper use of keys. Use when optimizing screens, implementing
lists, adding animations, working with images, or any task where rendering performance,
jank, frame rate, or memory usage is relevant.
---

# Flutter Performance

Const Widgets

Every widget that can be const must be const. Every constructor that can be const must have a const constructor:

// Do not do this
class UserAvatar extends StatelessWidget {
  UserAvatar({super.key, required this.url}); // Missing const
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(  // Missing const where possible
      backgroundImage: NetworkImage(url),
    );
  }
}

// Do this
class UserAvatar extends StatelessWidget {
  const UserAvatar({super.key, required this.url});
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(
      backgroundImage: NetworkImage(url),
    );
  }
}

List Performance

Use ListView.builder for lists with unknown or large item counts. Never use ListView with children for lists that could grow beyond 20 items.

// Do not do this for variable-length lists
ListView(
  children: items.map((item) => ItemCard(item: item)).toList(),
)

// Do this
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemCard(item: items[index]),
)

Selective Rebuilds with BlocSelector

When only part of a widget tree depends on part of a state, use BlocSelector to rebuild only the dependent widget:

// Do not do this (entire subtree rebuilds on any state change)
BlocBuilder<CartBloc, CartState>(
  builder: (context, state) => CartBadge(count: state is CartLoaded ? state.itemCount : 0),
)

// Do this (rebuilds only when item count changes)
BlocSelector<CartBloc, CartState, int>(
  selector: (state) => state is CartLoaded ? state.itemCount : 0,
  builder: (context, count) => CartBadge(count: count),
)

Image Optimization

Use cached_network_image for network images. Never use Image.network directly. Use cacheWidth and cacheHeight to resize images at decode time for list items. Use WebP format on Android and HEIC/WebP on iOS for significantly smaller file sizes.

The Accessibility Skill

---
name: flutter-accessibility
description: Implement accessibility features including semantic labels, focus management,
contrast requirements, and screen reader support. Use when creating interactive widgets,
images, icons, form fields, or any element that needs to be usable by people with
disabilities. Apply when working with Semantics, ExcludeSemantics, Focus, or FocusNode.
---

# Flutter Accessibility

Semantic Labels on Interactive Elements

Every IconButton, FloatingActionButton, and GestureDetector that performs a meaningful action must have a semantic label:

// Do not do this
IconButton(
  onPressed: _onShare,
  icon: const Icon(Icons.share),
)

// Do this
IconButton(
  onPressed: _onShare,
  icon: const Icon(Icons.share),
  tooltip: 'Share post', // Used as semantic label on mobile
)

Images and Decorative Icons

Purely decorative icons and images must be marked as such so screen readers skip them:

// Decorative icon (no semantic value)
Icon(
  Icons.star,
  semanticLabel: '', // Empty label marks it as decorative
)

// Informative icon (has semantic value)
Icon(
  Icons.warning,
  semanticLabel: 'Warning: action cannot be undone',
)

Form Accessibility

All form fields must have labels that screen readers announce. Never rely solely on placeholder text for field identification:

TextFormField(
  decoration: const InputDecoration(
    labelText: 'Email address',    // Screen readers announce this
    hintText: 'name@example.com', // Only visible when empty
  ),
)

Minimum Touch Target Size

All interactive elements must be at least 48x48 dp. If the visual size is smaller, use SizedBox or Padding to expand the hit area:

SizedBox(
  width: 48,
  height: 48,
  child: IconButton(
    iconSize: 20,
    onPressed: _onClose,
    icon: const Icon(Icons.close),
  ),
)

Advanced Skill Patterns

Teaching Tool Usage as Part of Task Completion

Skills can make specific commands part of the definition of "task complete." This is one of the most powerful patterns because it closes the quality loop automatically:

## Required Verification Steps

After any code generation or modification task, always:

1. Run `dart format .` to format all Dart files
2. Run `flutter analyze` to check for analyzer errors and warnings
3. Run `flutter test` to verify no tests are broken by the changes
4. If any of the above produce errors, fix them before reporting the task as complete

Do not report a task complete if any of these commands fail.

This pattern transforms the skill from a code generation guide into a full quality assurance workflow. The agent doesn't just write code: it validates the code against your quality bar before saying it's finished.

Conditional Rules Based on Context

Some rules apply only in certain circumstances. Express these with conditional phrasing that helps the agent apply them correctly:

## Context-Dependent Rules

When a widget initiates a network request:
- Disable all interactive elements while the request is in flight
- Show a loading indicator appropriate to the UI scope
- Handle errors with a user-readable message
- Re-enable interactive elements when the request completes (success or failure)

When a Bloc handles multiple independent operations:
- Create separate error states for each operation (not a single generic Error state)
- Name each error state after the operation: ProfileLoadFailure, ProfileUpdateFailure

When creating a widget that appears in a ListView:
- Always provide a key
- Use const constructors wherever possible
- Consider using ListView.builder at the list level if the list may exceed 50 items

Cross-Referencing Skills

Complex tasks may require multiple skills working together. Reference related skills explicitly in your skill body so the agent knows to load them:

## Related Skills

When this skill's rules result in widget extraction, also apply the
flutter-file-organization skill to determine the correct file location.

When the extracted component requires state management, apply the
flutter-bloc-state-management skill to determine whether it needs its own Bloc.

When writing tests for code created using this skill, apply the
dart-testing-conventions skill for test naming and structure.

Skills That Encode Hard-Won Production Lessons

Some of the most valuable skill content comes from specific production incidents. Document the lesson from the incident as a skill rule with enough context that anyone (and any agent) understands why it exists:

BuildContext After Async Gaps (Learned from Production)

Always check mounted before using BuildContext after any await:

Future<void> _onSubmit() async {
  final result = await _repository.save(formData);

  // WRONG: context may be stale if widget was disposed during the await
  ScaffoldMessenger.of(context).showSnackBar(...);

  // CORRECT: check mounted first
  if (!mounted) return;
  ScaffoldMessenger.of(context).showSnackBar(...);
}

This error is silent in development (the widget is usually still mounted by the time the async operation completes) but causes "FlutterError (looking up a deactivated widget's ancestor)" crashes in production where network latency is higher and users navigate away while operations are in flight.

Package-Level Skills: Teaching the Agent Your Libraries

The skills CLI tool (available as a Dart package at pub.dev/packages/skills) enables a powerful pattern: installing skills directly from your project's package dependencies.

# Install the Dart skills CLI globally
dart pub global activate skills

# Install skills from all packages in your project that ship skills
skills get

When you add a package to your pubspec.yaml and run skills get, the CLI searches each package in your dependency tree for a skills/ directory and installs those skills automatically. This means package authors can ship their own usage instructions directly to agent users.

Why This Matters

Before package-level skills, adding a new package to a Flutter project meant the agent knew the package existed (from its training data) but might not know the current API, preferred usage patterns, or common mistakes. This led to agents hallucinating method names, using deprecated APIs, or missing the idiomatic usage pattern the package author intended.

With package-level skills, the agent receives authoritative usage instructions directly from the people who wrote the package. When go_router ships a skills/go-router-navigation.md file, every Flutter team that runs skills get after adding GoRouter gets a skill that teaches the agent exactly how GoRouter works, from the GoRouter team.

Writing Skills for Your Own Packages

If you maintain internal Dart or Flutter packages that your team uses, shipping skills with them is a high-value investment:

my_design_system/
  lib/
    src/
      components/
    my_design_system.dart
  skills/
    my-design-system-components.md    <- teaches agents how to use your components
    my-design-system-theming.md       <- teaches agents your theming system
  pubspec.yaml
  README.md

---
name: my-design-system-components
description: Use the MyDesignSystem component library for UI elements. Use when creating
any UI elements including buttons, cards, form fields, navigation elements, or any visual
component. Apply instead of raw Material or Cupertino widgets wherever a design system
component exists.
---

# MyDesignSystem Component Usage

Always use MyDesignSystem components instead of raw Flutter widgets where equivalents exist.

## Available Components

DsButton replaces ElevatedButton, TextButton, and OutlinedButton.
DsCard replaces Card.
DsTextField replaces TextFormField.
DsAvatar replaces CircleAvatar.
DsChip replaces Chip.
DsBottomSheet replaces showModalBottomSheet.

## DsButton Usage

Do not do this: ElevatedButton( onPressed: _onSubmit, child: const Text('Submit'), ).

Do this: DsButton( label: 'Submit', onPressed: _onSubmit, variant: DsButtonVariant.primary, ).

`DsButton.variant` accepts `primary`, `secondary`, `destructive`, and `ghost`. When loading, pass `isLoading: true` to show the button's built-in loading state.

When a developer on your team runs skills get, this skill installs automatically alongside any official Flutter or Dart skills, giving the agent complete knowledge of your internal component library.

Skills vs Rules vs MCP: Knowing the Difference

Agent skills exist alongside two other agent customization mechanisms: AI rules files and MCP servers. Understanding the distinct role of each helps you put knowledge in the right place.

Three Customization Mechanisms

1. AI rules (always in context, project-wide facts).

CLAUDE.md, AGENTS.md, and .cursorrules should contain facts about the project that are always true. These files are loaded for every task and every session.

They're best used for information such as the project name and package identifier, Flutter and Dart SDK versions, core packages like flutter_bloc and go_router, minimum platform versions such as Android API 24 and iOS 15, and the project's architecture style such as feature-first or clean architecture. Detailed how-to instructions shouldn't be placed here because those belong in skills.

2. Skills (.agents/skills/*.md, loaded progressively).

Skills should contain instructions for how to perform a specific category of work. They're loaded only when the agent detects that they are relevant to the current task.

They're best used for instructions such as how to organize Flutter files, how to implement BLoC state management, how to write tests, how to handle errors, and other task-specific patterns that aren't always relevant. Project-wide facts shouldn't be placed in skills because those belong in the project rules.

3. MCP servers (extend the agent's capabilities with tools).

MCP servers are configured through the agent-specific MCP configuration and are used to extend the agent's capabilities by providing access to tools and external data. Their tools are available throughout the session.

They're best used for tasks such as looking up Flutter documentation through a Dart MCP server, retrieving package information from pub.dev, running Flutter commands in the project, reading logs from a connected device, and searching for code across the repository. Instructions, conventions, and project-specific rules shouldn't be placed in MCP servers because those belong in the rules and skills.

A useful heuristic: if the information would be in a README, it probably belongs in a rules file or skill. If the information requires a network call or executing a program, it belongs in an MCP server. If the information is only relevant for a specific type of task, it belongs in a skill rather than a rules file.

Another heuristic: context budget. Rules files are always in context, so they consume context budget on every task regardless of relevance. Keep rules files short (under 50 lines) and factual. Skills amortize their context cost because they are only loaded when relevant. MCP servers have their own cost model based on tool calls.

Organizing Skills in a Team

Skills as Shared Team Knowledge

The .agents/skills/ directory must be committed to your Git repository. When you commit a skill, every developer on the team gets it on their next git pull. When a new developer joins, they clone the repo and immediately have the accumulated skill knowledge the team has built. When someone writes a skill from a production incident, that lesson is preserved in the repository alongside the code it protects.

This makes skills a living institutional knowledge system: the skill file is simultaneously the instruction for the AI agent and the documentation of the standard itself. Unlike a wiki page or a Confluence article, a skill is read by the tooling that actually generates code, not just by developers who may or may not remember to apply it.

Skill Review Process

Changes to skill files should go through the same pull request review process as code changes. A skill that encodes a wrong convention or expresses a rule too vaguely can produce incorrect output across the entire team's agent usage until it's corrected.

Here's a skill review checklist, to check before merging a skill change:

• The description correctly and completely describes when this skill applies.

• Every rule is specific enough to change agent behavior and isn't vague guidance.

• Counterexamples are provided for patterns that are common in training data.

• Code examples compile correctly in isolation.

• The skill doesn't duplicate content in another skill.

• The skill was tested by asking the agent to perform the relevant task and verifying that the output follows the skill's rules.

• The skill has been reviewed by at least one other team member who would use it in their daily work.

Keeping Skills Current

Skills become outdated when your team's conventions change: when you migrate from one navigation library to another, adopt a new testing framework, update your design system, or refactor your error handling approach. An outdated skill is worse than no skill because it actively steers the agent toward patterns you no longer use.

Treat dependency upgrades as skill review triggers. When you upgrade go_router to a new major version, review the navigation skill to ensure it reflects the current API. When you adopt a new pattern from a team retrospective, update the relevant skill in the same PR.

Skill Discoverability Within Your Team

As your skill library grows, developers need to be able to find the right skill for their task. Use consistent naming conventions and consider maintaining a brief skills index:

# .agents/skills/README.md (not a skill, just an index)

## Flutter Skills
flutter-feature-architecture      -- Feature folder structure and layer rules
flutter-bloc-state-management     -- Bloc events, states, and widget integration
flutter-file-organization         -- File splitting, extraction, and naming
flutter-error-handling            -- Typed failures and Either return types
flutter-navigation                -- GoRouter routes, navigation methods, deep links
flutter-theming                   -- Design tokens, color extensions, spacing constants
flutter-testing                   -- Widget tests, Bloc tests, and test naming
flutter-accessibility             -- Semantic labels, focus, and touch targets
flutter-performance               -- Const widgets, selective rebuilds, list optimization

## Dart Skills
dart-models-freezed               -- Freezed models, json_serializable, DTOs
dart-testing-conventions          -- package:test conventions, mocktail, async testing
dart-pattern-matching-idiomatic   -- Switch expressions, sealed classes, destructuring
dart-run-static-analysis          -- analysis_options.yaml, dart analyze, dart fix

This index isn't read by agents (it's a README.md, not a skill file). It's for developers who are new to the project and want to know what skills exist before asking the agent to perform tasks.

Best Practices for Writing Skills

Start from Real Mistakes, Not Ideal Patterns

The most effective skills come from observing AI-generated code that was wrong in a specific, reproducible way. The mistake is evidence that the agent's default behavior needs correction for your project. Every time you manually fix AI output, that fix is a skill rule.

Ideal-pattern skills ("here is how Bloc should work in theory") are less effective than mistake-correction skills ("the agent always produces X but we need Y, so the rule is Z"). The mistake tells you where the training data diverges from your conventions. The rule corrects it.

Test Skills Before Committing

After writing a skill, test it by asking your agent to perform the task the skill covers. Ask the agent to create a new screen with Bloc state management, or split a large file, or write unit tests for a repository. Then verify that the output follows every rule in your skill.

Rules that aren't being followed need to be either more explicit, given a counterexample, or combined with a more specific description that helps the agent recognize when to load the skill.

One Skill per Domain of Expertise

Resist the temptation to write one large skill that covers everything. A skill per domain (file organization, state management, testing, theming, navigation, error handling) is easier to maintain, loads progressively (so each skill is only in context when relevant), and is easier to share with other teams or publish as a community resource.

Write the Description with Trigger-Word Richness

The description is the only part of a skill that is always read. Pack it with the specific trigger words and phrases that indicate the skill is relevant:

# Trigger-poor description
description: How to set up navigation in Flutter.

# Trigger-rich description
description: Implement navigation using GoRouter in Flutter apps. Use when adding routes,
navigating between screens, setting up deep links, handling authentication redirects,
configuring nested navigation, working with ShellRoutes, or any task involving
Navigator, route, path, deep link, URL, back button, or go_router package.

The trigger-rich description will match a much wider range of task descriptions, ensuring the skill loads when it is relevant rather than only on exact phrase matches.

Common Mistakes When Writing Skills

Rules That Are Too Vague to Change Behavior

# These change nothing: the agent was already trying to do these
- Write clean, maintainable code.
- Follow Flutter best practices.
- Use the appropriate state management solution.
- Organize files logically.

# These change specific behavior: the agent was doing something different
- Place every extracted widget class in the widgets/ subdirectory of its feature folder.
- Name BlocEvent subclasses as past-tense verb phrases: ProfileLoadRequested, not LoadProfile.
- Never use Navigator.push; use context.go() or context.push() from GoRouter.
- Mark every widget constructor parameter with required unless it has a default value.

Vague rules describe aspirations. Specific rules describe concrete, verifiable behaviors. Every rule in a skill should answer the question: "What would an agent do differently after reading this rule compared to before?"

Missing the Counterexample for High-Frequency Wrong Patterns

Some wrong patterns appear millions of times in training data. An agent that has learned _buildHeaderSection() as a valid Flutter pattern from thousands of examples may not abandon it based on a text rule alone.

Show the exact code the agent would produce and contrast it with the code you want. This is effective because the agent recognizes the specific code pattern, and the contrast communicates the rule at the code level, not just the text level.

Descriptions That Don't Trigger on the Right Tasks

A skill about Bloc state management that has a description saying "implement state management" won't load when someone asks "add a loading state to the checkout screen." The description needs to include "loading state" as a trigger phrase.

Test your descriptions by thinking about the variety of ways someone would describe tasks that need this skill, and ensure the description includes trigger phrases from all of those ways.

Not Committing Skills to Version Control

Skills left on a single developer's machine are personal notes, not team knowledge. Committed skills are institutional knowledge that new hires get from day one, that agent users across the team benefit from without separate setup, and that can be reviewed, improved, and maintained like code. Always commit .agents/skills/ to Git.

Writing Skills That Are Too Prescriptive

A skill should encode conventions, not dictate every possible implementation decision. If your skill specifies the exact pixel dimensions of a widget, the exact color of a specific loading indicator, or the exact parameter order of a constructor, you're over-specifying in ways that prevent the agent from making reasonable decisions in novel situations.

Skills should capture the structural and architectural patterns that are genuinely inconsistent without guidance. Implementation details that have many equally valid choices shouldn't be in skills.

Conclusion

The shift to agentic development in Flutter isn't about replacing developers. It's about multiplying what developers can accomplish.

An AI agent with strong skills can draft a complete, architecture-correct feature implementation that follows your team's exact conventions in minutes. A senior developer reviews it, adjusts, and ships. The skill is what bridges the gap between the agent's general knowledge and your team's specific standards.

What makes skills genuinely powerful is that they're the only part of the AI development workflow that contains knowledge the model wasn't trained on. The model has learned from millions of lines of public Flutter and Dart code. But it has never seen your codebase. It has never made a mistake in your project and been corrected. It has never attended your team's architecture discussions or retrospectives. It doesn't know that your team tried one pattern, found it painful, and deliberately chose a different one. Your skills are the container for all of that knowledge.

The official Flutter skills from github.com/flutter/agent-plugins and the official Dart skills from github.com/dart-lang/skills give you a production-quality starting point that covers the most common Flutter and Dart development patterns. The skills CLI tool makes installing them as simple as a single npm command. The package-level skills system means your dependencies can ship their own usage instructions and update them as the package evolves.

But the skills you write yourself, drawn from your own production incidents, your own code review feedback, and your own architectural decisions, are the ones with the highest leverage. They encode knowledge that's irreplaceable because it can't be found in any public repository.

A rule like "never separate a StatefulWidget from its State class" comes from understanding Flutter's compilation model at a level that most training data does not communicate. A rule like "use sealed class hierarchies with final concrete classes for all Bloc events and states" comes from understanding both Dart 3's type system and the real-world benefits of exhaustive switching. A rule like "check mounted before using BuildContext after any await" comes from seeing the specific crash that happens in production when this rule is violated.

These rules, drawn from your experience, documented as skills, and committed to your repository, transform your AI agent from a generalist Flutter developer into a developer who knows your project. That transformation is worth every minute spent writing the skills.

References

Agent skills for Flutter and Dart (Flutter Documentation): Comprehensive guide to agent skills including the progressive disclosure model, official repositories, and universal installation commands. https://docs.flutter.dev/ai/agent-skills

Get Started with AI in Flutter (Flutter Documentation): Step-by-step setup guide for Claude Code, Antigravity, Codex, Cursor, and other agents including the official Flutter plugin installation instructions for each tool. https://docs.flutter.dev/ai/get-started

Flutter Agent Plugins Repository (GitHub): The official repository of Flutter agent skills maintained by the Flutter team, covering responsive layouts, GoRouter navigation, JSON serialization, widget testing, integration testing, BLoC patterns, and more. https://github.com/flutter/agent-plugins

Dart Skills Repository (GitHub): The official repository of Dart agent skills maintained by the Dart team, covering unit testing, static analysis, package tooling, pattern matching, CLI apps, native assets, and more. https://github.com/dart-lang/skills

Flutter AI Rules Documentation (Flutter Documentation): Documentation for project-wide AI rules files (CLAUDE.md, AGENTS.md, .cursorrules) and how they complement skills. https://docs.flutter.dev/ai/ai-rules

The Agent Skills Specification: The specification site that defines the universal SKILL.md format, directory conventions, and agent compatibility requirements. The source of truth for the skills standard. https://agentskills.io

skills Dart Package (pub.dev): The Dart CLI tool for installing agent skills from project dependencies. Enables package authors to ship skills alongside their packages and teams to install them automatically. https://pub.dev/packages/skills

skills CLI (npm): The npm-distributed CLI for installing agent skills from GitHub repositories. Used for the canonical npx skills add flutter/agent-plugins installation command. https://www.npmjs.com/package/skills

skills-registry Serverpod: A collection of agent skills for popular Dart and Flutter packages that do not yet ship their own skills, including Riverpod, flutter-shadcn-ui, and others. Maintained by the Serverpod team. https://github.com/serverpod/skills-registry

dhruvanbhalara/skills Premium Flutter Skills Documentation: An extensive documentation project covering the full list of available Flutter agent skills with detailed descriptions of what each skill covers and teaches. https://github.com/dhruvanbhalara/skills