Sổ tay kỹ thuật

Claude Code: subagent, skill và slash command tuỳ biến

how-to#claude-code#agents· cập nhật 2026-11-06

Dùng khi muốn đóng gói quy trình lặp lại (review playbook, đọc log, kiểm tra BGP) thành subagent, skill hoặc slash command riêng của project trong Claude Code.

Sửa trang này
Mục lục

Tóm tắt: Subagent là file .claude/agents/<tên>.md gồm frontmatter (name, description, tools, model) và phần thân là system prompt. Subagent chạy trong context riêng và chỉ trả kết quả tóm tắt về phiên chính. Skill là thư mục .claude/skills/<tên>/ có SKILL.md (frontmatter name, description) cùng các file phụ. Model tự nạp skill khi description khớp với việc đang làm, hoặc bạn gọi bằng /<tên>. Slash command là file .claude/commands/<tên>.md và nhận tham số qua $ARGUMENTS. Kiểm chứng trên Claude Code 2.1.x.

Luồng hoạt động

flowchart LR
  U[Yêu cầu của bạn] --> M[Phiên chính]
  M -->|"description khớp"| S["Skill: nạp SKILL.md vào context"]
  M -->|"giao việc"| A["Subagent: context riêng, tool giới hạn"]
  A -->|"chỉ trả tóm tắt"| M
  U -->|"/lint-playbook"| C["Command / skill gọi tay"]
  C --> M
Subagent Skill Slash command
Vị trí (project) .claude/agents/*.md .claude/skills/<tên>/SKILL.md .claude/commands/*.md
Vị trí (user) ~/.claude/agents/ ~/.claude/skills/ ~/.claude/commands/
Context Riêng, không làm đầy phiên chính Nạp vào phiên chính Nạp vào phiên chính
Ai kích hoạt Model tự giao việc, hoặc bạn yêu cầu đích danh Model tự nạp, hoặc /<tên> Chỉ bạn, /<tên>
Hợp với Việc đọc nhiều file/log rồi chỉ cần kết luận, cần giới hạn tool Quy trình + tài liệu/script đi kèm Prompt mẫu ngắn gọi bằng tay

Cấu hình

Subagent

.claude/agents/config-reviewer.md
---
name: config-reviewer
description: Review diff cấu hình IOS XR/Junos và playbook Ansible trước khi đẩy. Dùng chủ động sau khi sửa file trong roles/ hoặc configs/.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
Bạn là reviewer cấu hình mạng. Chỉ đọc, không sửa file.
 
Kiểm tra:
1. Thay đổi BGP/route-policy có thể làm rơi session hoặc leak route không.
2. Có xoá interface, VRF, ACL đang được tham chiếu không.
3. Playbook có `check_mode`/`--check` và `commit confirmed` không.
 
Trả về danh sách: mức độ (block/warn/info), file:dòng, lý do, đề xuất sửa.
Field Ý nghĩa
name Định danh, chữ thường và dấu -
description Quan trọng nhất: model dựa vào đây để quyết định giao việc. Ghi rõ "dùng khi nào".
tools Danh sách tool cho phép, cách nhau bằng dấu phẩy. Bỏ trống thì subagent thừa hưởng toàn bộ tool của phiên chính, gồm cả MCP.
model sonnet, opus, haiku, inherit (theo phiên chính)

Cách dùng:

> Dùng subagent config-reviewer để review thay đổi trong roles/bgp
/agents          # tạo, sửa, xem danh sách subagent bằng giao diện
# định nghĩa subagent tạm thời cho một phiên (CI), không cần file
claude -p "review diff hiện tại" \
  --agents '{"config-reviewer": {"description": "Review diff cấu hình mạng", "prompt": "Bạn là reviewer cấu hình mạng, chỉ đọc."}}'

Skill

.claude/skills/bgp-health/
├── SKILL.md
├── checklist.md          # tài liệu phụ, chỉ đọc khi cần
└── scripts/
    └── parse_bgp.py      # script model có thể chạy
.claude/skills/bgp-health/SKILL.md
---
name: bgp-health
description: Kiểm tra sức khoẻ BGP từ output show bgp summary của IOS XR/Junos. Dùng khi người dùng dán output BGP hoặc hỏi peer nào đang down.
allowed-tools: Read, Bash(python3 *)
---
 
# BGP health check
 
1. Lưu output người dùng dán vào file tạm.
2. Chạy `python3 .claude/skills/bgp-health/scripts/parse_bgp.py <file>`, script in JSON gồm peer, state, prefix.
3. Đối chiếu với [checklist.md](checklist.md) và báo cáo peer không Established, prefix tụt bất thường.
  • Model chỉ thấy name + description của mọi skill. Nội dung SKILL.md chỉ được nạp khi cần, file phụ đọc sau nữa. Nhờ vậy có thể cài nhiều skill mà không tốn context.
  • allowed-tools: tool được dùng không cần hỏi khi skill đang chạy.
  • disable-model-invocation: true: model không tự nạp skill, chỉ chạy khi bạn gõ /<tên>. Hợp với thao tác có side-effect.

Slash command tuỳ biến

.claude/commands/lint-playbook.md
---
description: Lint một playbook Ansible và tóm tắt lỗi
argument-hint: <đường dẫn playbook>
allowed-tools: Bash(ansible-lint *), Bash(yamllint *)
---
 
Chạy `yamllint $ARGUMENTS` và `ansible-lint $ARGUMENTS`.
Gom lỗi theo file, giải thích ngắn từng rule, đề xuất bản sửa nhưng KHÔNG tự sửa.
> /lint-playbook playbooks/bgp.yml

$ARGUMENTS là toàn bộ chuỗi sau tên lệnh, còn $1, $2 là từng tham số theo vị trí. Trong các bản Claude Code gần đây, command và skill dùng chung cơ chế /<tên>. Command cũ vẫn chạy, nhưng skill dùng được thêm file phụ.

Lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
Subagent không bao giờ được gọi tự động description chung chung Ghi rõ tình huống, thêm "dùng chủ động khi...", hoặc yêu cầu đích danh
Subagent không thấy file, không chạy được lệnh tools thiếu Read/Bash Bổ sung tool, hoặc bỏ field để thừa hưởng toàn bộ
Sửa file agent/skill nhưng chưa có tác dụng Phiên đang chạy chưa nạp lại Mở phiên mới, kiểm tra bằng /agents hoặc /help
Skill không xuất hiện Đặt sai: SKILL.md phải nằm trong thư mục con .claude/skills/<tên>/ Đúng cấu trúc thư mục, frontmatter có name + description
/tên-lệnh không nhận Trùng tên lệnh có sẵn, hoặc chạy với --disable-slash-commands Đổi tên, bỏ flag
Subagent hỏi permission liên tục Rule allow của phiên chính không bao lệnh nó chạy Thêm rule trong settings.json
Kết quả subagent quá dài, phiên chính đầy context Prompt không yêu cầu tóm tắt Ghi rõ định dạng trả về ngắn trong thân file agent

Tham khảo