Best Agents for Windsurf in 2026

How Windsurf discovers agents

Windsurf's AI assistant, Cascade, supports agents through multiple mechanisms. Understanding how each works helps you choose the right approach for your team.

.windsurfrules (legacy approach)

The .windsurfrules file sits in your project root and gives Cascade instructions about your conventions, stack, and preferences. It's a single flat file with no structure requirements. Many developers still use it, and it works well for project-specific context. But it has limits: no versioning, no metadata, no way to share or discover rules created by others.

The newer .windsurf/rules/ directory-based format improves on this by letting you split rules into multiple files with different activation modes. But it's still Windsurf-specific and doesn't transfer to other tools.

AGENTS.md

Windsurf automatically discovers AGENTS.md files in your project. A root-level AGENTS.md is treated as an always-on rule — its full content is included in Cascade's system prompt on every message. AGENTS.md files in subdirectories apply only when Cascade reads or edits files inside that directory.

This is a step toward portable configuration, but AGENTS.md is still a single file without the structured metadata (version, category, ID) that makes agents discoverable and manageable.

Agent definitions via the Agent Skills spec

The Agent Skills specification is the most structured approach. Agent definitions live in .agents/agents/ as Markdown files with YAML frontmatter. Each file defines a complete agent with an ID, version, category, and detailed instructions.

Windsurf's Cascade discovers skills in .agents/skills/ and ~/.agents/skills/, and agent definitions follow the same discovery pattern. The key advantages over .windsurfrules and AGENTS.md:

• Versioned. Agent definitions use semantic version numbers. You can track changes and pin stable versions.
• Discoverable. Agents published to registries like Agent Shelf can be found and installed by anyone.
• Portable. The same agent definition works in Windsurf, Claude Code, Cursor, GitHub Copilot, and 40+ other tools.
• Composable. Agents can reference MCP servers and skills, pulling in additional capabilities automatically.

If you're still using .windsurfrules for everything, consider splitting your configuration: keep project-specific settings in .windsurfrules or .windsurf/rules/, and use agent definitions from the Agent Skills spec for reusable expertise.

Agent categories that work well with Windsurf

Cascade is a capable assistant across many tasks, but some agent categories deliver outsized value in the Windsurf environment.

Coding agents

Coding agents are the most natural fit. Code review agents, refactoring agents, debugging agents, and test-writing agents align directly with what you do inside an IDE. A good coding agent turns Cascade from a general assistant into a specialist.

What to look for:

• Agents that define a structured workflow, not just "you are an expert in X"
• Framework-specific agents (React, Next.js, Django, Rails) that know common patterns and anti-patterns
• Agents with explicit rules about code style, testing, and error handling

Good coding agents include instructions like: "Before generating new code, search the codebase for existing utilities that solve the same problem" or "Always include error handling for network requests and explain the failure mode in a comment."

DevOps agents

DevOps agents help with infrastructure configuration: Dockerfiles, CI/CD pipelines, Kubernetes manifests, Terraform modules. These agents are especially useful because DevOps work involves dozens of configuration formats where small mistakes cause outages. An agent that knows your stack can generate correct configuration without you looking up syntax.

Writing agents

Writing agents handle documentation, README generation, API docs, changelogs, and technical writing. Since Cascade has full access to your project files, a writing agent can read your source code and produce documentation that stays accurate. This is more effective than using a standalone writing tool disconnected from your codebase.

Useful writing agent patterns:

• Agents that generate JSDoc or docstrings by reading function implementations
• README generators that scan your project structure and produce structured documentation
• Changelog agents that read git history and produce formatted release notes

Automation agents

Automation agents define workflows for repetitive tasks: scaffolding new components, setting up test files, creating boilerplate configs, or running multi-step processes.

Example use cases:

• "Create a new React component with tests, stories, and barrel export"
• "Set up a new API endpoint with route, controller, validation, and tests"
• "Generate a migration file from the diff between two schema definitions"

These agents turn multi-step manual work into single-prompt operations.

How to install agents in Windsurf

You have three options, from simplest to most automated.

Option 1: Manual download and copy

1. Find an agent on Agent Shelf
2. Click Download to get the Markdown file
3. Create .agents/agents/ in your project root if it doesn't exist
4. Drop the Markdown file into that directory

This is straightforward but manual. When an author publishes a new version, you'd need to download it again yourself.

Option 2: Use the AgentShelf skill

The AgentShelf skill automates discovery and installation. Once installed in Windsurf, you can ask Cascade:

• "Install the code-review agent from AgentShelf"
• "Search AgentShelf for React testing agents"
• "Update my agents to the latest versions"

The skill handles authentication, downloading, and file placement. If the agent references MCP servers or other dependencies, the skill detects those and helps you install them too. Follow the installation guide to set it up.

Option 3: Use the AgentShelf MCP server

The AgentShelf MCP server provides tools for searching, browsing, and downloading agents directly from within Windsurf. Add the MCP server to your configuration and Cascade gets direct access to the full Agent Shelf registry. You can search for agents, read their documentation, and download them without leaving the IDE.

The remote MCP server requires no installation — just add the URL to your Windsurf MCP configuration.

Tips for getting the best results

Combine agents with .windsurfrules

Agents provide general expertise. Your .windsurfrules (or .windsurf/rules/) provides project-specific context. Use both: an agent defines how to review code, while your project rules define your team's standards — naming conventions, import ordering, preferred libraries. The combination produces better results than either alone.

Use activation modes strategically

Windsurf's rule system supports activation modes: always-on, manual, and glob-based. For agents you use on every task (like a code style agent), use an always-on configuration. For specialized agents (like a security auditor), load them manually when needed. This keeps Cascade's context focused and avoids instruction overload.

Keep agents focused

An agent that tries to be a full-stack developer, security auditor, and technical writer at once will be mediocre at everything. Install multiple specialized agents and use each for its specific purpose. The best agents have a narrow focus and well-defined workflow.

Read the agent before using it

Every agent on Agent Shelf is a plain Markdown file. Open it and understand what the agent does, what workflow it follows, and what rules it enforces. You'll get better results when you understand the agent's approach and can give it appropriate tasks. You can also customize an agent after downloading it — adjust the rules, change the output format, or add your team's conventions.

Check for updates

Agent authors publish new versions with improved instructions and additional capabilities. If you installed agents manually, periodically check Agent Shelf for updates. If you're using the AgentShelf skill, you can ask Cascade to check for newer versions automatically.

Finding agents for your workflow

The Agent Shelf registry has agents across every category. Here are starting points for common Windsurf workflows:

• Code review and quality: Browse coding agents
• Infrastructure and deployment: Browse DevOps agents
• Documentation and writing: Browse writing agents
• Getting started: Read our beginner's guide

Every agent on Agent Shelf is a Markdown file you can inspect before installing. No hidden logic, no compiled code — just plain text instructions you can read, modify, and version control alongside your project.