Skills và subagent trong Claude Code: khi nào dùng cái nào

Custom slash command là một file Markdown, nội dung của nó thành prompt khi bạn gõ /ten. Skill là một thư mục có file SKILL.md, chứa được thêm file phụ trợ, và Claude có thể tự load khi mô tả của skill khớp với việc đang làm.

Phạm vi phụ thuộc vào vị trí file:

Team cần một lệnh /review dùng chung thì đặt ở .claude/commands/ của project và commit lên. Muốn biến thể riêng thì tạo trong ~/.claude/skills/ với tên khác để không ảnh hưởng đồng đội.

Tài liệu hiện tại ghi rằng custom command đã được gộp vào skill: .claude/commands/deploy.md và .claude/skills/deploy/SKILL.md đều tạo ra /deploy, và thư mục commands cũ vẫn chạy. Exam guide coi chúng là hai tính năng liên quan, cách hiểu đó vẫn dùng tốt.

Frontmatter SKILL.md cần biết cho đề thi

---
name: analyze-deps
description: Map dependencies of a module and summarize risky imports
argument-hint: "<module-path>"
context: fork
allowed-tools: Read, Grep, Glob
---

Analyze the dependencies of $ARGUMENTS and return a short summary...

• context: fork chạy skill trong context subagent tách biệt, nên output dài (phân tích codebase, brainstorm phương án) không tràn vào hội thoại chính. Chỉ kết quả quay về.
• allowed-tools giới hạn hoặc cấp sẵn quyền các tool skill được dùng, ví dụ chỉ tool đọc cho skill phân tích.
• argument-hint gợi ý tham số cần nhập khi ai đó gọi skill mà không truyền đối số.

Skill hay CLAUDE.md: CLAUDE.md luôn được load và chứa chuẩn chung. Skill chỉ load khi cần cho một quy trình cụ thể. Quy tắc áp dụng cho mọi việc thì để trong CLAUDE.md, còn quy trình thỉnh thoảng mới chạy thì làm skill. Phần CLAUDE.md xem ở thứ bậc CLAUDE.md và rules.

Subagent chạy trong context window riêng, có system prompt và bộ tool riêng. Nó không thấy lịch sử hội thoại của coordinator, không chia sẻ bộ nhớ với subagent khác hay với lần chạy trước của chính nó. Nó cần gì thì bạn phải đưa vào prompt.

Một điểm này quyết định khá nhiều đáp án:

• Truyền finding tường minh. Subagent tổng hợp cần kết quả tìm kiếm và phân tích tài liệu từ bước trước thì phải đưa đầy đủ vào prompt của nó. Định dạng có cấu trúc tách nội dung khỏi metadata (URL nguồn, số trang) giúp giữ được nguồn trích dẫn.
• Coordinator cần Task tool. Trong Agent SDK, subagent được tạo qua Task tool, nên allowedTools của coordinator phải có "Task". Bản Claude Code gần đây đổi tên tool này thành Agent, Task vẫn chạy như alias. Đề thi nhiều khả năng vẫn gọi là Task.
• Song song trong một response. Muốn ba subagent nghiên cứu chạy cùng lúc, coordinator phát ra ba lời gọi Task trong cùng một lượt, không phải mỗi lượt một cái.
• Giao mục tiêu, đừng giao kịch bản. Prompt của coordinator nên nêu mục tiêu và tiêu chí chất lượng, để subagent tự quyết cách làm.

Định nghĩa subagent nằm ở .claude/agents/ (project) hoặc ~/.claude/agents/ (cá nhân), mỗi loại có description, system prompt và giới hạn tool.

Plan mode cho Claude đọc, khảo sát codebase và đề xuất kế hoạch trước khi sửa bất cứ thứ gì. Dùng khi việc cần làm có:

• nhiều file (migrate thư viện đụng tới 45+ file),
• quyết định kiến trúc (tái cấu trúc một service),
• nhiều hướng làm hợp lý với đánh đổi khác nhau.

Chạy thẳng (direct execution) khi thay đổi nhỏ và rõ: sửa bug một file có stack trace chỉ đúng dòng, hoặc thêm một điều kiện kiểm tra. Lập kế hoạch ở đây chỉ làm chậm.

Hai cách kết hợp tốt với nhau: lập kế hoạch migrate trong plan mode, chốt hướng làm, rồi chuyển sang chạy thẳng để thực hiện.

Explore là subagent dựng sẵn, chỉ đọc, chuyên cho việc khám phá. Khi một task nhiều giai đoạn bắt đầu bằng rất nhiều tìm kiếm, giao giai đoạn đó cho Explore. Nó đọc đống output ồn ào và trả về bản tóm tắt, để context chính không đầy file dump trước khi vào việc thật. Phần quản lý context xem ở bài về long context.

flowchart TD
    A[Task mới] --> B{Quy tắc áp dụng cho mọi việc?}
    B -- Có --> C[CLAUDE.md]
    B -- Không --> D{Quy trình lặp lại?}
    D -- Có --> E{Dùng chung với team?}
    E -- Có --> F[Command hoặc skill project trong .claude/]
    E -- Không --> G[Skill cá nhân trong ~/.claude/]
    D -- Không --> H{Nhiều file hoặc kiến trúc?}
    H -- Có --> I[Plan mode, rồi thực thi]
    H -- Không --> J{Khám phá dài hoặc việc song song?}
    J -- Có --> K[Explore hoặc subagent khác]
    J -- Không --> L[Chạy thẳng]

Một coordinator tạo subagent tổng hợp sau khi hai subagent nghiên cứu chạy xong. Output tổng hợp cứ báo "không có nguồn nào được cung cấp", dù hai subagent nghiên cứu đã trả về finding chi tiết. Cách sửa hợp lý nhất?

A. Cấp cho subagent tổng hợp cùng allowedTools với các subagent nghiên cứu. B. Đưa đầy đủ finding của các subagent nghiên cứu vào thẳng prompt của subagent tổng hợp. C. Chạy cả ba subagent trong cùng một lượt để chúng chia sẻ bộ nhớ. D. Bật context: fork trên coordinator để subagent thừa hưởng context của nó.

Đáp án: B. Subagent không thừa hưởng context của coordinator. Bước tổng hợp cần finding thì coordinator phải truyền vào prompt.

• A đổi thứ subagent làm được, không đổi thứ nó biết. Tool không mang theo kết quả cũ.
• C nhầm chạy song song với chia sẻ trạng thái. Subagent chạy cùng lúc vẫn tách biệt.
• D dùng sai một option frontmatter của skill. context: fork tách skill khỏi hội thoại chính, không phải cách chia context của coordinator cho subagent.

• Phạm vi project (.claude/) được chia sẻ qua version control; phạm vi cá nhân (~/.claude/) chỉ của bạn.
• context: fork, allowed-tools và argument-hint là các option SKILL.md cần thuộc.
• Subagent bắt đầu với context trống. Đưa mọi thứ nó cần vào prompt, và cho coordinator quyền dùng Task tool.
• Plan mode cho việc lớn, nhiều file hoặc kiến trúc; chạy thẳng cho sửa lỗi nhỏ, rõ ràng.
• Dùng Explore subagent để giữ phần khám phá dài dòng ngoài hội thoại chính.