TL;DR

Từ tháng 1/2026, sub-agent trở thành tính năng tạo ra sự khác biệt lớn nhất trong Claude Code - vượt qua commands, skills và hooks.

Một sub-agent là file Markdown tại .claude/agents/<name>.md với YAML frontmatter và system prompt riêng. Claude tự động delegate task phù hợp dựa vào description field, hoặc bạn gọi trực tiếp bằng tên.

Mỗi agent chạy trong context window cô lập - không tích lũy rác vào main thread, có thể chạy song song nhiều agent cùng lúc.

Danh sách dưới đây gồm 30 agent được @heynavtoor xây dựng và kiểm chứng qua 100+ thử nghiệm thực tế, chia theo 9 vai trò cụ thể.

Dùng một model cho tất cả = bỏ 80% giá trị

Khi bạn mở Claude Code và gõ một prompt, mọi thứ xảy ra trong cùng một context window: file reads, log dumps, tangents, failed attempts - tất cả tích lũy lại. Session càng dài, context càng nặng, response càng chậm, cost càng cao. Anthropic gọi đây là context pollution.

Sub-agent giải quyết điều này theo hướng cấu trúc: thay vì push mọi thứ vào main thread, bạn delegate side-task cho một worker riêng.

Worker đó đọc file, chạy search, làm reasoning trong context window của nó - rồi chỉ trả về summary kết quả. Main thread của bạn nhận được insight mà không nhận rác. Và khi các task độc lập với nhau, bạn có thể chạy 3-5 agent song song - hoàn thành trong thời gian của 1 agent.

Sub-agent là gì và hoạt động như thế nào

Mỗi sub-agent là một file Markdown với cấu trúc cụ thể:

---
name: code-reviewer
description: Use after staging changes and before committing. Reviews diffs for silent breakage risk.
tools: Read, Grep, Glob, Bash
model: sonnet
---
System prompt của agent ở đây...

Các field chính cần biết:

  • description: Claude dùng field này để quyết định khi nào tự động delegate. Viết trigger cụ thể thay vì capability chung - "Reviews staged changes before commits" route tốt hơn nhiều so với "code expert".

  • tools: giới hạn tool access theo principle of least privilege. Read-only agents (reviewer, auditor) chỉ cần Read, Grep, Glob.

  • model: route task đơn giản đến haiku, task phức tạp đến opus. Claude Code v2.1.63 đổi tên tool spawn từ Task thành Agent.

Sub-agent lưu tại .claude/agents/ (project-level, share với team qua version control) hoặc ~/.claude/agents/ (user-level, dùng được mọi project).

30 sub-agent chia theo vai trò

Mỗi agent được đánh dấu độ khó: Beginner / Intermediate / Advanced.

Engineering

  • code-reviewer (Beginner) - đọc diff, score "silent breakage risk" 1-5, flag file + line + 1-line repro

  • bug-hunter (Intermediate) - walk stack frame, tìm contract violation, trả về smallest patch <10 lines + 1 regression test

  • git-bisect (Advanced) - tự chạy git bisect với test command, trả về bad commit + diff + suspect line

DevOps

  • migration-validator (Advanced) - dry-run migration, classify ops (additive/backfill/destructive/locking), block nếu thiếu rollback script

  • secret-scanner (Beginner) - scan staged diff cho 3 rule: known prefix, high-entropy string, private key header; output BLOCK với masked value

  • cost-spike (Advanced) - so sánh 7 ngày vs 28-ngày baseline, pinpoint giờ spike, cross-ref với deploys/cron/config rollouts

Product & Design

  • spec-writer (Beginner) - force câu hỏi "user làm gì khác sau khi ship?", xuất PRD <800 words với success metric action-based

  • edge-cases (Intermediate) - 15 edge cases qua 15 axes: empty, max, offline, concurrent, i18n, timezone, currency, partial failure...

  • ab-test-planner (Advanced) - tính sample size với two-proportion z-test (80% power, 95% confidence), định stop-for-harm rule

Sales

  • lead-researcher (Beginner) - hunt 5 buying signals (funding, exec hire, expansion, layoffs, tech change) - kèm date và source URL

  • cold-email (Beginner) - 3 dòng: observation unique to prospect + numeric outcome + soft ask 15 phút; reject nếu dòng 1 generic

  • renewal-risk (Advanced) - score churn qua 5 tín hiệu có trọng số: WAU trend (35%), feature depth (25%), ticket sentiment (15%), champion in seat (15%), exec contact (10%)

Marketing

  • hook-writer (Beginner) - 20 hooks theo 6 pattern: contrarian, specificity, stat-shock, confession, question, time-frame; score curiosity gap + specificity + stop power

  • seo-cluster (Intermediate) - 30-50 keywords với intent labels (informational/comparison/commercial/navigational/transactional), pillar + 5-8 clusters

  • content-audit (Advanced) - score 50 posts trên engagement per impression (không phải raw engagement), tìm 5 pattern có correlation >1.5 SD above mean

Customer Support, Operations, Finance, Research & Personal Productivity

Agent

Job

Key output

ticket-triage

Score urgency 1-10, route to queue

Tag + queue + 1 sentence to read first

inbox-hawk

3-bucket filter: today/week/noise

Max 7 items cần action hôm nay

meeting-notes

Transcript → decisions + actions

<250 words, owner + deadline hoặc MISSING

okr-health

Score OKR vs expected linear progress

Green/Yellow/Red + named unblock

burn-rate

Project full month từ partial actuals

Flag >10% over hoặc >20% under plan

cap-table

Model dilution + post-money

Pre/post table, option pool gotcha

variance

Actuals vs budget, decompose variance

Volume/price/timing/one-time + corrective action

source-verifier

Check claim vs primary source

CONFIRMED / WEAKLY SUPPORTED / STALE / UNFOUND

daily-plan

Calendar + PRs → focused 4-task day

Must-ship + collaboration + admin + learning

decision-log

Log decision với revisit condition

.decisions/YYYYMMDD-slug.md

Sub-agent vs commands, skills và hooks

Đây là điểm dễ nhầm nhất khi mới dùng Claude Code:

  • Commands: invoke explicit, shared context. Đang được tích hợp vào Skills.

  • Skills: reusable prompt/workflow trong main conversation - áp dụng procedure vào context hiện tại.

  • Hooks: scripts deterministíc tại lifecycle events - không hallucinate, dùng cho security & logging.

  • Sub-agents: isolated LLM worker, chạy song song, dùng khi task sinh nhiều output không cần giữ trong main context.

Ba loại phối hợp: Skills định quy trình, Hooks enforce rules, Sub-agents thực hiện công việc nặng trong isolation.

Khi nào không nên dùng sub-agent

Sub-agent có overhead - mỗi lần spawn tốn context khởi động mới. Không dùng khi:

  • Task nhỏ, nhanh - prompt thẳng vào main conversation đơn giản hơn

  • Các bước phụ thuộc nhau (step 2 cần full output của step 1) - một session tuần tự sạch hơn

  • Hai agent cùng edit một file - conflict ngay. Dùng git worktree để isolate nếu cần parallel edits

  • Quá nhiều specialist agents - flooding Claude với roster lớn khiến auto-delegation kém chính xác

Bắt đầu với quy tắc Pick 5

Không cần cài 30 agent ngay. Chiến lược đã được kiểm chứng:

  1. Pick 5 Beginner agent phù hợp với công việc hàng ngày của bạn, a Solofounder: Lead Researcher + Cold Email + Inbox Hawk + Meeting Notes + Burn Rate. Engineer: Code Review + Bug Hunter + Git Bisect + Migration Validator + Secret Scanner.

  2. Chạy 2 tuần liên tục - build muscle memory, không babysit.

  3. Thay 1 Beginner bằng Intermediate. Thêm 2 tuần. Tiếp tục với Advanced.

  4. Tháng 3: một team AI chạy nhiều phần công việc hơn bất kỳ tool nào bạn từng thử.

Nguyên tắc không thay đổi: một agent làm một việc. Bug Hunter tìm bug. Code Reviewer review code. Chain chúng khi cần - đó là cách build team scale được.

Via: Claude Code Docs - Custom Subagents, Anthropic Blog - How and when to use subagents, @heynavtoor