Agents

Agents are specialized AI assistants that live in .claude/agents/ and handle delegated tasks. Each agent has focused expertise, specific tools, and structured workflows for its domain.

Available Agents

AI Kit generates up to 16 agents based on your project’s detected stack:

How to Use Agents

In Claude Code, agents are automatically available for delegation. You can invoke them directly:

@planner Plan the implementation for adding dark mode support
@code-reviewer Review the changes in src/components/Header.tsx
@security-reviewer Run a security audit on the authentication flow
@e2e-runner Write E2E tests for the checkout flow
@build-resolver Fix the TypeScript build errors
@doc-updater Update docs for the changes I just made
@refactor-cleaner Find dead code in src/components/
@tdd-guide Walk me through adding tests for the cart feature using TDD
@ci-debugger Diagnose the failing GitHub Actions workflow
@sitecore-specialist Debug why the Hero component isn't rendering in Experience Editor
@architect Design the rendering strategy for the new product pages
@data-scientist Profile this dataset and recommend a modeling approach
@performance-profiler Audit the homepage for Core Web Vitals issues
@migration-specialist Plan the upgrade from Next.js 14 to 15
@dependency-auditor Run a full dependency audit with license check
@api-designer Design the REST API for the orders resource

You can also use the /orchestrate skill to coordinate multiple agents on a complex task.

Agent Details

Planner

Breaks down feature requests into concrete implementation plans. Outputs:

• Files to create and modify (with reasons)
• Numbered implementation steps
• Testing strategy
• Risks and considerations

Follows existing patterns in your codebase. Flags changes that touch more than 7 files for approval.

Code Reviewer

Provides thorough reviews across multiple dimensions:

• Correctness — logic errors, null handling, async patterns
• React patterns — hooks rules, memoization, Server vs Client Components
• TypeScript — no any, proper generics, strict null checks
• Performance — unnecessary re-renders, bundle size, data fetching
• Accessibility — semantic HTML, ARIA, keyboard nav, color contrast
• Sitecore — JSS helpers, Experience Editor compatibility, GraphQL efficiency

Rates each category as PASS / WARN / FAIL with specific line references.

Security Reviewer

Focused exclusively on security vulnerabilities:

• XSS prevention — dangerouslySetInnerHTML, URL params, eval()
• Injection — SQL, NoSQL, command injection, path traversal
• Auth & session — route protection, JWT validation, localStorage secrets
• Secrets — hardcoded keys, .env in git, NEXT_PUBLIC_ misuse
• API security — rate limiting, input validation, CORS, HTTP methods
• Dependencies — npm audit, known CVEs, typosquatting

Outputs findings as CRITICAL / HIGH / MEDIUM / LOW with a score out of 100.

E2E Runner

Generates and runs Playwright tests using Page Object Model:

• Creates page objects in tests/pages/
• Uses accessible selectors (getByRole, getByLabel, getByText)
• Covers happy paths, error states, accessibility, and responsive viewports
• Uses CLI only (npx playwright test) — never the Playwright MCP plugin

Build Resolver

Diagnoses root causes of build failures:

• TypeScript errors — type mismatches, missing declarations, module resolution
• Next.js errors — Server/Client boundary, dynamic imports, image config
• Sitecore errors — component factory, GraphQL schema, layout service
• Module resolution — missing deps, circular imports, path aliases

Follows the two-attempt rule: if an approach fails twice, tries a different strategy.

Doc Updater

Keeps documentation in sync with code changes:

• Updates JSDoc comments and component docs when props change
• Creates documentation entries for new components
• Updates README sections for new features or changed setup
• Generates Storybook stories if Storybook is detected
• Appends dated entries to docs/decisions-log.md

Refactor Cleaner

Finds and removes dead code and unnecessary complexity:

• Unused exports — uses Knip if available, otherwise manual search
• Unused imports — including type-only import optimization
• Dead code — unreferenced functions, commented-out blocks
• Over-abstraction — wrappers that just pass through, single-use utilities

Groups findings by severity: Remove / Simplify / Consider.

TDD Guide

Coaches you through the red/green/refactor cycle for test-driven development:

• Red — writes a failing test that captures the desired behavior before implementation
• Green — implements the minimal code needed to make the test pass
• Refactor — cleans up the implementation while keeping tests passing
• Suggests test structure using React Testing Library, Vitest, or Jest depending on your stack
• Helps design testable interfaces before writing the implementation

CI Debugger

Diagnoses CI/CD pipeline failures and suggests targeted fixes:

• Reads CI log output (GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines)
• Identifies root cause categories: failing tests, TypeScript errors, lint failures, build errors, missing environment variables, or flaky infrastructure
• Distinguishes genuine code regressions from flaky test failures or environment issues
• Provides specific file and line references where relevant
• Suggests the minimal fix to unblock the pipeline without over-engineering

Invoke with: @ci-debugger Diagnose the failing workflow — here's the log output: [paste log]

Sitecore Specialist

Handles all Sitecore XM Cloud development patterns:

• Component development — JSS field helpers, Experience Editor compatibility
• Field type mapping — TextField, RichTextField, ImageField, LinkField, DateField
• GraphQL — efficient queries, fragments, Experience Edge pagination
• Layout service — rendering host config, placeholder nesting
• Personalization — component variants, A/B testing rules
• Debugging — component not rendering, empty fields, GraphQL errors, 404s

Architect

Makes high-level design decisions for Next.js, Sitecore XM Cloud, and Tailwind projects:

• Rendering strategy — SSR, SSG, ISR, and client-side rendering decisions per route
• Component hierarchy — Server vs Client Component boundaries, composition patterns
• Data flow — Sitecore Layout Service, Experience Edge GraphQL, caching layers
• State management — URL params, server state, React state, global store (minimal approach)

Outputs Architecture Decision Records with rendering strategy tables, component hierarchies, and trade-offs.

Data Scientist

Handles ML pipelines, data analysis, and model evaluation:

• Data analysis — profiling, quality assessment, feature engineering
• ML pipeline design — end-to-end pipeline architecture, feature stores
• Model evaluation — metric selection, evaluation harnesses, distribution shift detection
• Experiment tracking — structured experiments with reproducibility

Starts with exploratory analysis before modeling. Reports confidence intervals and statistical significance.

Performance Profiler

Diagnoses and fixes web performance bottlenecks:

• Core Web Vitals — LCP, INP, CLS analysis with specific element identification
• Bundle analysis — heavy dependencies, tree-shaking opportunities, code splitting
• Runtime profiling — unnecessary re-renders, memory leaks, network waterfalls
• Rendering optimization — Server/Client Component boundaries, Suspense placement

Follows a measure-first approach: baseline → identify bottleneck → fix → verify → repeat.

Migration Specialist

Plans and executes safe, incremental framework and library migrations:

• Breaking change detection — scans for deprecated APIs, removed features, behavior changes
• Migration planning — phased plans with rollback points, minimum viable upgrade paths
• Codemod execution — applies official codemods, writes custom transforms for edge cases
• Incremental adoption — adapter patterns, feature flags, mixed-state app support

Never upgrades multiple major versions in one step. Keeps the app deployable at every step.

Dependency Auditor

Audits project dependencies for security, compliance, and hygiene:

• Vulnerability scanning — classifies by severity, checks reachability of vulnerable code paths
• Outdated detection — prioritizes security fixes over feature updates, flags abandoned packages
• License compliance — flags copyleft in proprietary projects, generates license reports
• Bundle impact — measures install/bundle size contribution, finds lighter alternatives

Distinguishes direct vs transitive vulnerabilities. Never recommends npm audit fix --force blindly.

API Designer

Designs, reviews, and improves REST and GraphQL APIs:

• API design — resource endpoints, HTTP methods, status codes, pagination strategies
• Schema validation — Zod/JSON Schema definitions, naming conventions, nullable/required fields
• Versioning — backward-compatible changes, deprecation workflows, sunset headers
• Error handling — consistent error format, actionable messages, rate limit responses

Outputs endpoint tables, request/response examples, Zod schemas, and error response catalogs.

Conditional Agents

Some agents are only generated when their tools are detected in your project:

All other agents (planner, code-reviewer, security-reviewer, build-resolver, doc-updater, refactor-cleaner, architect, tdd-guide, ci-debugger, data-scientist, performance-profiler, migration-specialist, dependency-auditor, api-designer) are generated for every project. This keeps the agent list relevant and avoids confusion from agents that can’t do their job.

Agent File Format

Each agent is a markdown file with YAML frontmatter in .claude/agents/:

---
name: planner
description: Implementation planning agent — breaks features into tasks...
tools: Read, Glob, Grep, Bash
---
 
# Implementation Planner
 
[Agent instructions and workflow...]

The tools field controls which Claude Code tools the agent can use when delegated to. The description helps the main agent decide when to delegate.

Customizing Agents

You can modify any agent file in .claude/agents/ to fit your team’s workflow. Changes are preserved across ai-kit update since agent files are only added, not overwritten.

To create a custom agent, add a new .md file to .claude/agents/ with the same frontmatter format. Claude Code will discover it automatically.