Best Claude Code subagents in 2026: 15 from the AY CLAUDE catalog

Published 2026-11-10 · Last updated 2026-11-10

Abstract cover: one large glowing orange circle sending lines to a column of eight smaller circles

Short answer

The best Claude Code subagents in the AY CLAUDE catalog that install as-is are ui-tester, test-generator, api-documenter, refactoring-assistant and security-auditor. Deeper prompts like code-audit-expert need a one-line tools fix first. Save a subagent in .claude/agents/ or ~/.claude/agents/.

How we ranked them

Every subagent here comes from the AY CLAUDE agents catalog, which lists 76 agents. Each entry links to its catalog page, where you can read and download the full file.

We did not rank by downloads or stars. Real agents in the catalog have no download counts yet: only 5 seed entries have any, and their files are empty. GitHub stars belong to the source repository, not the agent, and every source repo here has 0 or 5. Ranking on those numbers would be noise.

Instead we used two checks you can verify on each catalog page. First, does the file match the format in the Claude Code subagent docs: a valid name, a description, and tools as a comma-separated list, a YAML list, or left out? Second, how long is the agent file? Nearly all of it is the system prompt, and a longer, specific prompt gives the subagent more to work with. Subagents that install as-is come first, ordered by file length. Strong prompts that need a tools fix follow.

Most of these files were written for one project: a budget app (billybbuffum/budget), a note app (Nemo-4552/noteamp) or Vigil-Code (tbartel74/Vigil-Code). Read the prompt and swap the project names, paths and stack details for your own before you rely on it.

Subagents that install as-is

Subagents that install as-is, compared
Subagent	Install status	Tools allowed	Model	File length (chars)
1. ui-tester	Installs as-is	Read, Write, Grep, Glob, Bash	Not set	10,205
2. test-generator	Installs as-is	Read, Write, Grep, Glob, Bash	Not set	9,945
3. api-documenter	Installs as-is	Read, Write, Grep, Glob	Not set	8,256
4. refactoring-assistant	Installs as-is	Read, Edit, Grep, Glob, Bash	Not set	6,137
5. security-auditor	Installs as-is	Read, Grep, Glob	Not set	4,871
6. test-writer	Installs as-is	Inherits all	Not set	3,977
7. doc-updater	Installs as-is	Inherits all	Not set	3,284
8. nextjs-developer	Installs as-is	Inherits all	Not set	2,728
9. database-migration	Installs as-is	Inherits all	Not set	1,836

Subagents that install as-is, compared. Source: ayclaude's agents catalog, each subagent's latest version file, read 2026-11-10. Install status checks the frontmatter against the Claude Code docs, code.claude.com/docs/en/sub-agents.

1. ui-tester

Best for: Front-end teams that already run the Playwright MCP server and want UI checks plus generated tests.

Drives a browser through the Playwright MCP server to test UI flows, then writes automated tests for what it checked.
When Claude picks it, from its description field: "Interactive UI testing with Playwright MCP and automated test generation"
Tools allowed: Read, Write, Grep, Glob, Bash. Model: Not set.
Agent file: 10,205 characters, frontmatter included. Source: billybbuffum/budget.

2. test-generator

Best for: Go projects that need test coverage on existing packages.

Writes unit and integration tests for Go code.
When Claude picks it, from its description field: "Generates comprehensive unit and integration tests for Go code"
Tools allowed: Read, Write, Grep, Glob, Bash. Model: Not set.
Agent file: 9,945 characters, frontmatter included. Source: billybbuffum/budget.

3. api-documenter

Best for: Teams that want API docs kept close to the code without giving the subagent Bash.

Reads your code and writes API documentation, including OpenAPI specs and usage examples. It can read and write files but has no shell access.
When Claude picks it, from its description field: "Creates comprehensive API documentation from code, including OpenAPI specs and usage examples"
Tools allowed: Read, Write, Grep, Glob. Model: Not set.
Agent file: 8,256 characters, frontmatter included. Source: billybbuffum/budget.

4. refactoring-assistant

Best for: Codebases with a known architecture that need careful, scoped refactors.

Refactors code toward clean architecture and better code quality.
When Claude picks it, from its description field: "Helps refactor code while maintaining clean architecture and improving code quality"
Tools allowed: Read, Edit, Grep, Glob, Bash. Model: Not set.
Agent file: 6,137 characters, frontmatter included. Source: billybbuffum/budget.

5. security-auditor

Best for: Go teams that want a read-only security pass before review.

Audits Go code for vulnerabilities and security best practice violations. Read-only: Read, Grep and Glob, no Edit or Bash.
When Claude picks it, from its description field: "Performs security audits on Go code, identifying vulnerabilities and security best practices violations"
Tools allowed: Read, Grep, Glob. Model: Not set.
Agent file: 4,871 characters, frontmatter included. Source: billybbuffum/budget.

6. test-writer

Best for: React teams working test-first who are fine with a Korean prompt or will translate it.

Writes tests test-first (TDD) with Jest, React Testing Library and Vitest. The prompt and description are in Korean.
When Claude picks it, from its description field: "TDD(Test-Driven Development) 방식으로 테스트 코드를 작성하는 전문 에이전트. Jest, React Testing Library, Vitest를 활용"
Tools allowed: not set in the file, so it inherits every tool available to subagents. Model: Not set.
Agent file: 3,977 characters, frontmatter included. Source: Nemo-4552/noteamp.

7. doc-updater

Best for: Projects that track work in PRD, TODO and TASK files inside the repo.

Keeps memory-bank project documents (PRD, TODO, TASK) updated and in sync. The prompt and description are in Korean.
When Claude picks it, from its description field: "메모리뱅크 문서(PRD, TODO, TASK)를 자동으로 업데이트하고 동기화하는 에이전트"
Tools allowed: not set in the file, so it inherits every tool available to subagents. Model: Not set.
Agent file: 3,284 characters, frontmatter included. Source: Nemo-4552/noteamp.

8. nextjs-developer

Best for: Next.js App Router projects on the shadcn/ui and Tailwind stack.

Builds components and pages on Next.js 14 App Router with TypeScript, Tailwind CSS and shadcn/ui. The prompt and description are in Korean.
When Claude picks it, from its description field: "Next.js 14 App Router 기반 개발 전문 에이전트. TypeScript, Tailwind CSS, shadcn/ui를 활용한 컴포넌트 및 페이지 개발"
Tools allowed: not set in the file, so it inherits every tool available to subagents. Model: Not set.
Agent file: 2,728 characters, frontmatter included. Source: Nemo-4552/noteamp.

9. database-migration

Best for: Teams running a MariaDB to PostgreSQL migration.

Moves data from MariaDB to PostgreSQL: schema conversion, data transfer and integrity checks. The prompt and description are in Korean.
When Claude picks it, from its description field: "MariaDB에서 PostgreSQL로 데이터 마이그레이션을 담당하는 전문 에이전트. 스키마 변환, 데이터 이전, 무결성 검증을 수행"
Tools allowed: not set in the file, so it inherits every tool available to subagents. Model: Not set.
Agent file: 1,836 characters, frontmatter included. Source: Nemo-4552/noteamp.

Strong prompts that need a tools fix first

These six come from one project and have the deepest prompts in the catalog. Their frontmatter lists tools under core, extended and deferred keys, which is not one of the forms the docs describe. Flatten tools to a single comma-separated line before you install them.

Subagents that need a tools fix, compared
Subagent	Install status	Tools allowed	Model	File length (chars)
10. code-audit-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	opus	24,379
11. redis-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	sonnet	18,008
12. kubernetes-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	sonnet	15,941
13. security-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	sonnet	12,207
14. python-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	sonnet	11,637
15. docker-expert	Fix tools first	Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch	sonnet	10,046

Subagents that need a tools fix, compared. Source: ayclaude's agents catalog, each subagent's latest version file, read 2026-11-10. Install status checks the frontmatter against the Claude Code docs, code.claude.com/docs/en/sub-agents.

10. code-audit-expert

Best for: Leads who want a ranked list of the few changes that matter most in a codebase.

Audits code quality across 10 categories, from structure and testability to security and DDD patterns, and picks 5 to 10 high-leverage fixes.
When Claude picks it, from its description field: "Universal code auditing expert. Performs systematic code quality assessments across 10 categories: Structure, Readability, Testability, CI/CD, Security, Observability, Technical Debt, Documentation, Performance, and DDD patterns. Identifies 5-10 high-leverage improvement opportunities rather than 200 issues."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: opus. The prompt also refers to paths in its source project; adjust them.
Agent file: 24,379 characters, frontmatter included. Source: tbartel74/Vigil-Code.

11. redis-expert

Best for: Back-end teams designing or debugging Redis caching and rate limits.

Covers Redis data structures, caching patterns, rate limiting, session management and clustering.
When Claude picks it, from its description field: "Redis database and caching expert. Deep knowledge of data structures, caching patterns, rate limiting, session management, and clustering."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: sonnet. The prompt also refers to paths in its source project; adjust them.
Agent file: 18,008 characters, frontmatter included. Source: tbartel74/Vigil-Code.

12. kubernetes-expert

Best for: Platform teams running Kubernetes day to day.

Covers Kubernetes operations: pods, deployments, services, networking, RBAC, troubleshooting and multi-cluster setups.
When Claude picks it, from its description field: "Kubernetes cluster operations expert. Deep knowledge of pods, deployments, services, networking, RBAC, troubleshooting, and multi-cluster management."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: sonnet. The prompt also refers to paths in its source project; adjust them.
Agent file: 15,941 characters, frontmatter included. Source: tbartel74/Vigil-Code.

13. security-expert

Best for: Teams that want a security reviewer with write access to fix what it finds.

Covers application security: OWASP Top 10, secure coding, authentication, authorization, input validation and audits.
When Claude picks it, from its description field: "Application security expert. Deep knowledge of OWASP Top 10, secure coding, authentication, authorization, input validation, and security auditing."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: sonnet. The prompt also refers to paths in its source project; adjust them.
Agent file: 12,207 characters, frontmatter included. Source: tbartel74/Vigil-Code.

14. python-expert

Best for: Python back-end and data teams.

Covers Python with Flask and FastAPI, async code, data processing, type hints, testing and ML/NLP integration.
When Claude picks it, from its description field: "Python development expert. Deep knowledge of Flask/FastAPI, async programming, data processing, type hints, testing, and ML/NLP integration."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: sonnet. The prompt also refers to paths in its source project; adjust them.
Agent file: 11,637 characters, frontmatter included. Source: tbartel74/Vigil-Code.

15. docker-expert

Best for: Teams containerising services or hardening Dockerfiles.

Covers Dockerfiles, Docker Compose, networking, volumes, container security and production deployment.
When Claude picks it, from its description field: "Docker and container orchestration expert. Deep knowledge of Dockerfiles, Docker Compose, networking, volumes, security, and production deployment."
Tools: the file lists Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch under core, extended and deferred keys. Claude Code reads tools as a comma-separated string or a YAML list, so flatten it to tools: Read, Edit, Glob, Grep, Write, Bash, WebFetch, WebSearch before you install it. Model: sonnet. The prompt also refers to paths in its source project; adjust them.
Agent file: 10,046 characters, frontmatter included. Source: tbartel74/Vigil-Code.

How to install a subagent

A subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt. Download the file from the subagent's catalog page and save it in one of these places (Claude Code docs):

# This project only (commit it to share with your team)
mkdir -p .claude/agents
#   save the file as .claude/agents/ui-tester.md

# All your projects
mkdir -p ~/.claude/agents
#   save the file as ~/.claude/agents/ui-tester.md

# One session only, defined on the command line
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

When two subagents share a name, the higher-priority location wins: managed settings, then the --agents flag, then .claude/agents/, then ~/.claude/agents/, then a plugin's agents/ directory (docs). The --agents flag is in the CLI reference.
Claude picks a subagent from your request, each subagent's description field, and the current context. To encourage it, the docs suggest phrases like "use proactively" in the description.
To run one yourself, name it ("Use the test-runner subagent to fix failing tests") or @-mention it: @"code-reviewer (agent)" look at the auth changes.
A subagent file is not a skill. A skill is a folder with a SKILL.md file, in the open Agent Skills format that the Agentic AI Foundation now hosts (what changes for skill authors).

FAQ

What are the best subagents in Claude Code?

Claude Code ships built-in subagents it uses on its own, including Explore (a fast, read-only agent for searching code), Plan and general-purpose (docs). For custom ones, the list above ranks the catalog's subagents by format and prompt depth. Start with the one that matches your stack, and keep its tools as narrow as the job allows.

Are Claude Code subagents worth it?

Often, for focused jobs. The docs list the gains: each subagent keeps its work out of your main conversation, can be limited to certain tools, can be reused across projects, and can run on a cheaper model such as Haiku. The cost: each subagent "sends its own requests, which count toward the same usage limits as your main conversation", and it starts fresh, so it may need time to gather context (docs).

How many subagents can Claude Code use?

There is no limit on the total number of subagents Claude can spawn over a session. By default, when 20 subagents are running at once, spawning another fails with "Concurrent subagent limit reached". The CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS environment variable changes that limit. Subagents can also spawn their own, up to three layers below the main conversation by default (docs).