Cursor 2.4: Subagents & Skills Explained

Cursor 2.4 represents a massive leap in AI-assisted development. With subagents, Agent Skills, cloud execution, and enterprise features like Cursor Blame, this update transforms how teams build software. Here's everything you need to know.

What's New in Cursor 2.4

The January 2026 release packs several game-changing features:

• Subagents: Independent specialized agents with their own context and tools
• Agent Skills: Define domain knowledge in SKILL.md files
• Image Generation: Generate images directly from the agent
• Clarification Questions: Agents ask for clarity while continuing work
• Cursor Blame (Enterprise): AI attribution showing which code is AI-generated

Subagents: Parallel Specialized Workers

Subagents are independent agents that run in parallel with the main agent. Each subagent has:

• Its own context window (separate from the main conversation)
• Custom system prompts for specialized tasks
• Specific tool access based on its role
• Ability to work simultaneously with other subagents

Example use case: While you're discussing architecture with the main agent, a subagent can be running tests, another can be writing documentation, and a third can be researching best practices—all in parallel.

Agent Skills: Domain-Specific Knowledge

Skills are defined in SKILL.md files that provide domain-specific knowledge and workflows to agents. This is powerful for:

• Team coding standards and patterns
• Project-specific conventions
• Domain expertise (finance, healthcare, etc.)
• Common workflows and procedures

Example SKILL.md:

# SKILL.md - React Component Patterns

## Component Structure
- Use functional components with hooks
- Prefer composition over inheritance
- Keep components under 200 lines

## Styling
- Use Tailwind CSS classes
- Follow mobile-first responsive design
- Use our design system tokens from @/styles/tokens

## Testing
- Write tests alongside components
- Use React Testing Library
- Aim for 80% coverage on critical paths

## Common Patterns
```tsx
// Standard component template
export function ComponentName({ prop1, prop2 }: Props) {
  const [state, setState] = useState(initialState);
  
  return (
    <div className="component-wrapper">
      {/* content */}
    </div>
  );
}
```

Background & Cloud Agents

Cursor's cloud agents let you run tasks without keeping your laptop connected. Key capabilities:

• Up to 8 parallel agents: Each in isolated codebases via git worktrees
• Background execution: Hand off tasks and check back later
• Integrations: Slack, Linear, and GitHub notifications
• Plan Mode: Create plans with one model, build with another

When to Use Cloud Agents

Plan Mode & Debug Mode

Plan Mode

Plan Mode allows the agent to research your codebase, ask clarifying questions, and create detailed markdown plans with file paths and code references. Key features:

• Inline Mermaid diagrams for architecture visualization
• Clarifying questions before implementation
• Searchable plan history
• Build from plan in foreground or background

Debug Mode

Systematic troubleshooting with runtime evidence:

• Runtime logs across different stacks and languages
• Automatic error correlation
• Step-by-step debugging assistance

Cursor Blame (Enterprise)

For enterprises tracking AI-generated code, Cursor Blame provides:

• Visual indicators for AI-generated vs. human-written code
• Links to original conversation summaries
• Audit trails for compliance
• Metrics on AI assistance usage

Productivity Workflow with Cursor 2.4

1. Morning standup: Review what cloud agents completed overnight
2. Plan complex features: Use Plan Mode to design before implementing
3. Define skills: Create SKILL.md files for team patterns
4. Delegate tasks: Launch background agents for bug fixes and documentation
5. Focus on high-value work: Handle architecture decisions while agents handle implementation
6. Review and iterate: Use AI code review in the editor sidepanel

Real-World Subagent Workflows

The concept of subagents sounds interesting in theory, but the real value becomes clear when you see how production teams are using them. After several weeks of working with Cursor 2.4 across multiple client projects, these are the patterns that deliver the most impact.

Frontend + Backend in Parallel

This is the most immediately useful pattern. When you need a new feature that touches both the UI and the API, you no longer have to build one side first and then the other. Instead, you describe the feature once, and two subagents work simultaneously: one builds the React component with proper TypeScript types, state management, and Tailwind styling, while the other builds the corresponding API endpoint with validation, database queries, and error handling.

The key to making this work is defining a shared contract up front. Have the main agent generate the TypeScript interface or Zod schema first, then hand that contract to both subagents. The frontend subagent builds against the interface types, and the backend subagent implements the actual endpoint to match. When both finish, the integration usually works on the first try because they're building against the same specification.

Test-Driven Development with a Dedicated Test Runner

This pattern changed how we think about TDD with AI agents. The main agent writes implementation code while a subagent continuously runs the test suite in the background. Every time the main agent saves a file, the test subagent picks up the change, runs the relevant tests, and reports failures back to the main conversation.

What makes this powerful is the feedback loop speed. The main agent does not have to stop coding, switch context to run tests, read output, and switch back. The test subagent handles that entire cycle independently. When a test fails, it surfaces the exact failure message and the main agent can course-correct immediately. This cuts the typical write-test-fix cycle time roughly in half compared to running everything sequentially.

Automated Code Review Pipeline

For teams that want thorough review before merging, you can set up a three-subagent pipeline that runs in parallel:

• Subagent A (Linting & Formatting): Runs ESLint, Prettier, and your custom rules. Flags any violations and auto-fixes what it can.
• Subagent B (Security Analysis): Checks for common vulnerabilities — SQL injection patterns, exposed secrets, insecure dependencies, and unsafe data handling.
• Subagent C (Test Coverage): Runs the test suite with coverage enabled, identifies untested code paths, and flags any coverage regressions against your baseline.

Each subagent produces a focused report. The main agent collates the results into a single review summary. This gives you a comprehensive automated review in the time it would normally take to run just one of those checks manually. It is not a replacement for human review, but it catches the mechanical issues so human reviewers can focus on architecture and business logic.

Migration Assistant

Framework migrations are one of the most tedious tasks in software development, and subagents make them significantly less painful. The pattern works like this: a research subagent reads the target framework's documentation, migration guides, and changelog, then produces a summary of the key differences and patterns. Meanwhile, the main agent starts refactoring your existing code, referencing the research subagent's findings as needed.

We used this pattern recently when migrating a client project from Next.js Pages Router to App Router. The research subagent built up a knowledge base of all the API differences — how data fetching changes, how routing conventions differ, how middleware works in the new model — while the main agent worked through the actual file-by-file migration. Without this pattern, the main agent would have had to pause repeatedly to look up documentation, breaking its flow.

Example SKILL.md for a Next.js Project

Skills are what make subagents truly effective for your specific codebase. Here is a practical SKILL.md that we use for Next.js App Router projects:

# SKILL.md - Next.js App Router

## Routing
- Use App Router (not Pages Router)
- Server Components by default
- 'use client' only when state/effects needed

## Data Fetching
- Server Components: async/await directly
- Client Components: React Query with server prefetch
- Never fetch in useEffect

## API Routes
- Use Route Handlers in app/api/
- Validate with Zod schemas
- Return NextResponse.json()

## Patterns
- Loading states: loading.tsx per route segment
- Error boundaries: error.tsx per route segment
- Metadata: generateMetadata() for dynamic SEO

The specificity matters. A generic "use React best practices" skill gives the agent nothing useful. But telling it exactly how your project handles data fetching, routing, and error boundaries means every subagent working on your codebase makes decisions that align with your architecture. Drop this file in your project root and every agent — main or sub — will reference it automatically.

Subagents vs Claude Code: When to Use Which

Since both Cursor's subagents and Claude Code use Claude models under the hood, the natural question is: when should you use which? The answer comes down to workflow context, not intelligence. Both tools are backed by the same underlying models. The difference is how and where you interact with them.

Cursor Subagents

Cursor subagents are the right choice when you are actively working inside the IDE and want to stay there. You get visual diffs, inline code review, and the ability to accept or reject changes file by file. The tight integration with your editor means you can see exactly what each subagent is doing, approve changes incrementally, and maintain a conversational flow with the main agent while subagents work in parallel.

This is ideal for single-codebase work: building features, fixing bugs, refactoring modules, and writing tests within one project. The visual context — seeing your file tree, open tabs, and terminal output alongside agent work — makes it easier to catch issues early and steer the agent when it drifts.

Claude Code

Claude Code is purpose-built for terminal-first workflows. It excels at tasks that span multiple repositories, integrate with CI/CD pipelines, or need to run headlessly in automation scripts. If you need an agent to clone a repo, run a build, analyze the output, make changes, run tests, and push a commit — all without a GUI — Claude Code is the better fit.

It is also the stronger choice for background automation. You can run Claude Code in a CI pipeline to auto-fix failing tests, generate changelogs, or triage incoming issues. The terminal interface means it composes naturally with other CLI tools and scripts in ways that an IDE-based agent cannot.

Using Both Together

Many teams — including ours — use both tools in tandem. Cursor handles active development during the day: building features, reviewing code, and iterating with subagents. Claude Code handles the background operations: running deployment scripts, managing multi-repo changes, processing batch tasks overnight, and integrating with project management tooling.

The mental model is straightforward. If you are looking at code and want to change it interactively, use Cursor. If you want to describe a task and walk away, use Claude Code. There is no conflict between the two, and the shared underlying model means the quality of reasoning is equivalent regardless of which interface you choose.

Common Mistakes with Cursor Agents

After months of working with Cursor agents across dozens of projects, we have catalogued the mistakes that waste the most agent time and developer patience. Avoid these five, and your agent workflows will be dramatically more effective.

1. Overloading Context

The instinct is to give the agent everything — paste your entire codebase summary, every relevant file, the full project history. This backfires badly. Large context windows do not mean that more context is always better. When you flood the context, the agent spends more time processing irrelevant information and is more likely to miss the critical details buried in the noise.

Instead, let agents discover context dynamically. Give them a clear task description and let them use their file search and code navigation tools to find what they need. Agents are remarkably good at locating relevant files on their own. If they need something specific, they will ask. Start lean and add context only when the agent explicitly requests it or when you see it heading in the wrong direction.

2. Skipping SKILL.md

Running agents without project-specific skills is like hiring a senior developer and not giving them any onboarding. They will write perfectly valid code that does not match your conventions, uses different libraries than your stack, or follows patterns that conflict with your architecture. Then you spend time correcting the output, which defeats the purpose of using agents in the first place.

A well-written SKILL.md takes 15 minutes to create and saves hours of correction over the life of a project. Document your routing conventions, data fetching patterns, state management approach, testing requirements, and any domain-specific rules. This is the single highest-leverage improvement you can make to your agent workflow.

3. Not Using Plan Mode for Complex Tasks

Jumping straight into implementation for a complex feature is a recipe for rework. The agent will start building immediately, make assumptions about architecture, and produce code that needs significant restructuring once you realize it went down the wrong path. By that point, you have wasted both agent compute and your own review time.

Plan Mode exists for exactly this reason. For any task that touches more than two or three files, or that involves non-trivial architectural decisions, start with a plan. Let the agent explore the codebase, ask clarifying questions, and produce a detailed implementation plan with file paths and code outlines. Review the plan, correct any wrong assumptions, and only then let it build. The upfront investment of five minutes in planning regularly saves thirty minutes or more of rework.

4. Running Too Many Agents on the Same Files

Cursor's git worktree isolation is a significant technical achievement — each background agent works in its own copy of the codebase, so agents cannot directly conflict with each other. However, merge conflicts still happen when multiple agents modify the same files and you try to integrate their work. Two agents both editing your main layout component or your database schema will produce changes that are individually correct but mutually incompatible.

The solution is to be intentional about work boundaries. Assign agents to different areas of the codebase. If two features will touch the same files, run them sequentially rather than in parallel. Use Plan Mode to identify file overlap before launching parallel agents. A little planning about which agent works on which files prevents the frustrating experience of spending more time resolving merge conflicts than the agents saved you.

5. Not Reviewing Agent Output

Agents are fast, capable, and increasingly reliable — but they are not infallible. Blindly merging agent output without review is how subtle bugs, security issues, and architectural drift sneak into your codebase. The speed of agents can create a false sense of security: if it wrote 500 lines of working code in two minutes, surely it is all correct.

Always review before merging. Use Cursor's diff view to step through changes file by file. Pay special attention to error handling (agents tend toward optimistic paths), security boundaries (agents do not always think about authorization), and edge cases (agents solve for the happy path first). The review does not need to be exhaustive — focus on the areas where mistakes are most costly. A five-minute review of agent output is significantly faster than debugging a production issue that a quick glance would have caught.

Getting Started

Update to Cursor 2.4 via the app's auto-update or download from cursor.com. Enable cloud agents in Settings → Agents.