Viết skill đầu tiên: đóng gói quy trình vào SKILL.md

Skill là gì, nằm ở đâu

Skill là một thư mục chứa file SKILL.md — gồm phần frontmatter (tên + mô tả) và phần hướng dẫn. Claude đọc mô tả của mọi skill khi khởi động; khi yêu cầu của bạn khớp mô tả nào, nó nạp toàn bộ skill đó vào và làm theo.

~/.claude/skills/          # skill cá nhân (mọi dự án)
└── pr-description/
    └── SKILL.md

.claude/skills/             # skill của dự án (commit vào git)

Viết SKILL.md

Chú ý tên file: SKILL viết hoa, .md viết thường — sai là không load. Tên trong frontmatter phải khớp chính xác tên thư mục.

---
name: pr-description
description: Writes pull request descriptions. Use when
  creating a PR, writing a PR, or summarizing changes
  for a pull request.
---

When writing a PR description:
1. Run `git diff main...HEAD` to see all changes
2. Structure: What / Why / Changes / Testing
3. Keep it under 200 words, no marketing tone

Description quyết định tất cả

Claude chọn skill bằng cách so yêu cầu của bạn với description — nên description phải chứa các cách nói bạn thường dùng: "tạo PR", "viết PR description", "tóm tắt thay đổi". Mô tả kiểu quảng cáo ("công cụ tuyệt vời giúp bạn…") không giúp matching.

Chuẩn tốt: 150-300 ký tự, mở đầu bằng hành động, liệt kê 2-3 cụm kích hoạt.

Kích hoạt và kiểm tra

• Restart Claude Code sau mỗi lần sửa skill — không có hot-reload
• Hỏi "What skills are available?" để xác nhận skill đã load
• Thử một yêu cầu khớp description và xem Claude có đề nghị dùng skill không
• Không load? Kiểm tra tên file SKILL.md, đường dẫn đúng cấp thư mục, rồi chạy claude --debug

Giữ skill gọn: mục lục, không phải cả cuốn sách

Skill chia context window với hội thoại của bạn. Giữ SKILL.md dưới 500 dòng; chi tiết dài (mẫu tham khảo, bảng quy tắc) tách vào thư mục references/ bên cạnh — Claude chỉ đọc khi cần. Triết lý này gọi là progressive disclosure: nạp mục lục, mở đúng chương khi dùng.

Từ skill cá nhân đến skill của team

Skill chạy ổn một tuần thì chuyển từ ~/.claude/skills sang .claude/skills trong repo và commit — cả team dùng chung, quy trình của bạn thành quy trình của đội. Bắt đầu từ một skill dùng hằng tuần, đừng xây 20 skill trong một cuối tuần rồi bỏ.