Hướng dẫn tạo Skill cho Claude Code từ một quy trình làm việc thực tế

Mình là Tony, hiện làm và vận hành các sản phẩm web, sử dụng Claude Code làm công cụ phát triển chính hằng ngày. Khi làm việc với coding agent trên dự án có nhiều module, mình nhận thấy cùng một loại yêu cầu nhưng agent có thể xử lý theo những trình tự khác nhau. Bạn có thể giải thích lại bằng prompt, bổ sung quy tắc vào CLAUDE.md, hoặc đóng gói thành Skill để sử dụng nhiều lần. Chọn cách nào phụ thuộc vào loại công việc và mức độ ổn định của quy trình.

Bài này thuộc series Claude Code cho dự án thực tế, tập trung vào những vấn đề developer gặp khi đưa Claude Code vào quy trình phát triển phần mềm. Mình viết cho bạn đã sử dụng Claude Code, có những workflow lặp lại và muốn chuẩn hóa cách agent thực hiện chúng. Thay vì giới thiệu danh sách Skill nên cài, mình sẽ phân tích một quy trình review API, tạo SKILL.md, bổ sung script hỗ trợ và kiểm tra cả những tình huống Skill không nên kích hoạt. Sau bài này, bạn có thể mang về một thư mục Skill hoàn chỉnh cùng bộ test để điều chỉnh cho dự án của mình.

1. Skill giải quyết loại vấn đề nào?

Claude Code Skill là một bộ hướng dẫn được tổ chức quanh file SKILL.md. Claude có thể tự sử dụng Skill khi nhận thấy yêu cầu phù hợp, hoặc bạn chủ động gọi bằng /ten-skill. Skill phù hợp với những quy trình nhiều bước, có tiêu chí kiểm tra và cần được sử dụng nhất quán trong những tình huống tương tự.

Không phải thao tác lặp lại nào cũng cần trở thành Skill. Nếu chỉ cần một câu lệnh cố định, bạn có thể tiếp tục dùng câu lệnh đó. Nếu một quy tắc phải áp dụng xuyên suốt dự án, CLAUDE.md thường phù hợp hơn. Mình chọn Skill khi muốn Claude nhận diện một loại công việc, thực hiện các bước theo thứ tự và báo cáo theo tiêu chí đã xác định.

Lấy một monorepo TypeScript giả định làm ví dụ:

apps/
  admin/
  api/
packages/
  ui/
  shared/

apps/admin chứa ứng dụng quản trị, còn apps/api phục vụ nhiều tổ chức khách hàng. API bắt buộc cách ly dữ liệu theo tenant, vì vậy một thay đổi ở endpoint có thể ảnh hưởng đến authorization hoặc phạm vi dữ liệu được truy cập. Team sử dụng pnpm và chạy test cho API bằng pnpm -F api test. Đây là bối cảnh đủ phức tạp để một checklist review chung chung dễ bỏ sót những ràng buộc riêng của dự án.

Giả sử developer thường xuyên nhờ Claude review thay đổi API trước khi merge. Mỗi lần, agent cần kiểm tra backward compatibility, authentication, tenant isolation, schema migration, test và API documentation. Có lần Claude xem kỹ schema nhưng bỏ qua tenant isolation, lần khác kiểm tra code đầy đủ nhưng không đối chiếu tài liệu API. Team cần chuẩn hóa phương pháp review thay vì tiếp tục viết lại prompt.

Một workflow đáng đóng gói thành Skill thường có các đặc điểm:

• Lặp lại: Team thường xuyên thực hiện cùng một loại công việc.
• Có trình tự: Các bước kiểm tra tương đối ổn định.
• Có đầu ra: Reviewer nhận báo cáo với cấu trúc xác định.
• Có tiêu chí kiểm tra: Team phân biệt được bằng chứng đầy đủ, thiếu bằng chứng và lỗi đã xác nhận.
• Có ranh giới: Agent biết trường hợp nào nằm ngoài phạm vi.

Với API review, Claude có thể tìm rủi ro, đọc thay đổi, chạy test được phép và tổng hợp bằng chứng. Tuy nhiên, Skill không được tự xem báo cáo của mình là quyết định approve hoặc merge. Quyền đó vẫn thuộc reviewer và quy trình của repository.

2. Phân biệt Skill, CLAUDE.md và MCP

Ba khái niệm này giải quyết những nhu cầu khác nhau. CLAUDE.md chứa hướng dẫn mà Claude luôn được nạp trong phạm vi tương ứng, còn Skill dành cho quy trình chỉ cần thiết khi thực hiện một loại tác vụ cụ thể. MCP cung cấp kết nối đến công cụ hoặc hệ thống bên ngoài mà agent cần sử dụng.

Có thể chọn theo bảng sau:

Nhu cầu	Nên dùng	Ví dụ
Quy tắc luôn áp dụng trong dự án	CLAUDE.md	Mọi truy vấn dữ liệu khách hàng phải tôn trọng tenant isolation
Quy trình nhiều bước, chỉ dùng khi cần	Skill	Review một thay đổi API trước khi merge
Truy cập hệ thống hoặc công cụ bên ngoài	MCP	Đọc dữ liệu từ một hệ thống quản lý công việc
Tự động hóa một thao tác cụ thể	Script hoặc công cụ	Thu thập danh sách file thay đổi từ Git

Mình phân biệt bằng ba câu hỏi: Claude cần biết quy tắc nào, cần làm theo quy trình nào, hay cần truy cập công cụ nào. Quy định mọi thao tác đọc dữ liệu của apps/api phải giữ đúng tenant isolation thuộc về CLAUDE.md. Skill api-review hướng dẫn Claude kiểm tra quy định đó khi review, còn MCP chỉ cần thiết nếu agent phải truy cập một hệ thống bên ngoài. Một Skill không bắt buộc phải sử dụng MCP.

Mình đã viết riêng bài Hướng dẫn viết CLAUDE.md để Claude Code hiểu đúng dự án của bạn, tập trung vào cách đưa context và quy tắc nền của dự án vào file hướng dẫn. Bạn có thể đọc bài đó nếu chưa phân biệt rõ hướng dẫn áp dụng toàn dự án với hướng dẫn cho một workflow. Phần tiếp theo giả định team đã có quy tắc nền và cần đóng gói quy trình review.

3. Phân tích một workflow trước khi viết SKILL.md

Nếu bắt đầu viết SKILL.md ngay khi nghĩ ra tên Skill, bạn dễ tạo một prompt dài với những yêu cầu như “review cẩn thận” hoặc “kiểm tra mọi vấn đề bảo mật”. Claude vẫn phải tự suy diễn phần lớn công việc, còn team thiếu tiêu chí đánh giá đầu ra. Mình xác định đầu vào, phạm vi và kết quả mong đợi trước khi viết frontmatter.

Với api-review, hợp đồng của workflow như sau:

Thành phần	Quy định
Đầu vào	Thay đổi API và một Git base ref cụ thể
Phạm vi	apps/api, cùng những thay đổi liên quan trong packages/shared
Điều kiện áp dụng	Review thay đổi API trước khi merge
Công việc	Kiểm tra 6 nhóm rủi ro
Đầu ra	Báo cáo phát hiện, bằng chứng và trạng thái kiểm tra
Không thực hiện	Sửa code, approve, merge hoặc deploy

Git base ref là điểm so sánh do reviewer cung cấp. Nếu thiếu ref, Claude cần hỏi lại thay vì tùy ý chọn một nhánh rồi báo cáo như thể đã kiểm tra đúng phạm vi. Cách này giúp các lần review sử dụng cùng một baseline khi cần đối chiếu kết quả.

Tiếp theo là sáu nhóm kiểm tra.

Backward compatibility: Claude xác định endpoint, HTTP method, request và response schema có thay đổi hay không. Nếu code xóa field, đổi kiểu dữ liệu hoặc thay đổi mã trạng thái, agent cần chỉ ra ảnh hưởng có thể xảy ra với client hiện hữu. Khi thiếu thông tin về client, Claude không được kết luận thay đổi an toàn.

Authentication và authorization: Agent kiểm tra endpoint mới hoặc endpoint được sửa có duy trì yêu cầu xác thực và kiểm tra quyền truy cập hay không. Những nhánh xử lý mới cần được xem xét nếu chúng có thể truy cập tài nguyên được bảo vệ. Người dùng đăng nhập thành công không đồng nghĩa với có quyền truy cập mọi tài nguyên.

Tenant isolation: Claude lần theo tenant context từ request đến những thao tác đọc và ghi dữ liệu. Nếu một truy vấn thiếu điều kiện tenant, agent cần kiểm tra các cơ chế bảo vệ ở lớp khác trước khi kết luận có lỗi. Báo cáo phải nêu vị trí và bằng chứng cụ thể.

Schema migration: Claude đối chiếu code với database schema, kiểm tra migration liên quan và ảnh hưởng đến dữ liệu hiện hữu. Agent cũng cần xem xét khả năng tương thích với code đang chạy. Phần không thể xác minh phải được ghi rõ.

Test: Claude tìm test liên quan đến thay đổi, bao gồm trường hợp thành công, thất bại và truy cập khác tenant. Lệnh pnpm -F api test có thể cung cấp thêm bằng chứng. Tuy nhiên, test pass không chứng minh toàn bộ API đã an toàn.

API documentation: Agent so sánh hành vi API với tài liệu tương ứng, bao gồm endpoint, request và response. Nếu thiếu cập nhật, reviewer cần biết chính xác phần nào không còn khớp. Trường hợp repository không có tài liệu liên quan cũng phải được ghi nhận.

Mục tiêu không phải buộc Claude tìm đủ sáu lỗi trong mỗi lần review. Agent cần xem xét đủ sáu nhóm, chỉ đưa ra phát hiện khi có bằng chứng và phân biệt rõ phần đã kiểm tra với phần chưa thể xác minh. Đây cũng là tiêu chí để team kiểm thử Skill sau khi viết.

4. Thiết kế cấu trúc Skill

Claude Code cho phép đặt Skill trong .claude/skills/ của dự án để team commit và chia sẻ. Nếu chỉ phục vụ cá nhân, bạn đặt tại ~/.claude/skills/; Skill trong thư mục con <subdir>/.claude/skills/ phục vụ phiên làm việc tại thư mục đó. Skill do plugin cung cấp có thể được gọi bằng /plugin-name:skill-name.

Mình chọn Skill cấp dự án vì quy trình review thuộc về team. Tạo cấu trúc sau tại thư mục gốc monorepo:

.claude/
  skills/
    api-review/
      SKILL.md
      references/
        review-rules.md
      scripts/
        collect-diff.sh

SKILL.md chứa quy trình chính và cấu trúc báo cáo. references/review-rules.md lưu tiêu chí review chi tiết, còn scripts/collect-diff.sh thu thập thay đổi từ Git. Mình tách các phần này để team có thể cập nhật quy tắc mà không khiến hướng dẫn chính quá dài.

Viết SKILL.md

Tạo file .claude/skills/api-review/SKILL.md:

---
name: api-review
description: Review thay đổi API trước khi merge trong monorepo TypeScript. Dùng khi người dùng yêu cầu kiểm tra pull request hoặc diff liên quan đến apps/api, gồm compatibility, authentication, tenant isolation, migration, test và API documentation.
argument-hint: <base-ref>
---

# API Review

Review thay đổi API trước khi merge.
Chỉ đánh giá và báo cáo, không sửa code hoặc merge.

## Input

Nhận Git base ref từ `$ARGUMENTS`.

Nếu thiếu ref, yêu cầu người dùng cung cấp.
Không tự chọn ref thay thế.

## Scope

- apps/api
- packages/shared nếu có thay đổi liên quan

## Procedure

1. Xác định base ref và phạm vi thay đổi.
2. Đọc `${CLAUDE_SKILL_DIR}/references/review-rules.md`.
3. Có thể thu thập diff bằng:
   `bash "${CLAUDE_SKILL_DIR}/scripts/collect-diff.sh" "$ARGUMENTS"`
4. Đọc code liên quan để hiểu thay đổi.
5. Kiểm tra lần lượt sáu nhóm trong tài liệu.
6. Kiểm tra test liên quan.
7. Chỉ chạy test khi được phép.
8. Tổng hợp bằng chứng và phần chưa xác minh.

## Output

Với mỗi phát hiện, báo cáo:

- Severity: critical, high, medium hoặc low
- Location: file và vị trí liên quan
- Finding: vấn đề cụ thể
- Evidence: bằng chứng từ code hoặc test
- Impact: ảnh hưởng có thể xảy ra
- Recommendation: hướng kiểm tra hoặc sửa

Cuối báo cáo, ghi rõ:

- Sáu nhóm đã kiểm tra
- Test đã chạy và kết quả
- Kiểm tra chưa thực hiện
- Những giả định còn thiếu bằng chứng

## Boundaries

- Không tự sửa code.
- Không tự approve hoặc merge.
- Không tự deploy.
- Không xem test pass là bằng chứng đủ.
- Không khẳng định lỗi khi thiếu bằng chứng.

Reviewer chịu trách nhiệm quyết định cuối cùng.

Đây là hướng dẫn review, không phải hệ thống tự động xác nhận API an toàn. Claude vẫn phải đọc code và đánh giá bằng chứng trước khi đưa ra finding. Team có thể gọi /api-review origin/main nếu origin/main là điểm so sánh đã thống nhất; $ARGUMENTS nhận tham số được truyền vào Skill. Mình chưa thêm allowed-tools vì quyền thực thi phải phù hợp với cấu hình dự án, chủ đề sẽ được phân tích trong bài về permissions của series.

Tách quy tắc review sang tài liệu tham khảo

Tạo file references/review-rules.md:

# API Review Rules

## Backward compatibility
- Kiểm tra route và HTTP method.
- So sánh request và response schema.
- Ghi nhận field bị xóa hoặc đổi kiểu.
- Xác định ảnh hưởng đến client hiện hữu.

## Authentication and authorization
- Kiểm tra yêu cầu xác thực.
- Kiểm tra quyền trên endpoint thay đổi.
- Xem các nhánh xử lý mới có bỏ qua
  kiểm tra quyền hay không.

## Tenant isolation
- Xác định nguồn tenant context.
- Theo dõi tenant context đến data access.
- Kiểm tra read, write, update và delete.
- Kiểm tra quyền truy cập khác tenant.
- Xem xét bảo vệ ở các lớp liên quan.

## Schema migration
- Đối chiếu code với schema thay đổi.
- Kiểm tra xử lý dữ liệu hiện hữu.
- Xem ảnh hưởng đến code đang chạy.
- Ghi rõ giới hạn xác minh migration.

## Tests
- Xác định test liên quan.
- Kiểm tra success và failure cases.
- Kiểm tra cross-tenant access cases.
- Ghi rõ test đã chạy hoặc chưa chạy.

## API documentation
- Đối chiếu endpoint với tài liệu.
- Kiểm tra request và response examples.
- Ghi nhận thay đổi chưa được cập nhật.

## Evidence policy
- Không suy đoán thành lỗi đã xác nhận.
- Mọi finding phải có bằng chứng.
- Thiếu thông tin thì ghi chưa xác minh.
- Không approve thay reviewer.

Team có thể bổ sung quy tắc riêng khi hiểu rõ hơn về codebase. Chẳng hạn, nếu authorization nằm ở một lớp tập trung, tài liệu nên chỉ đúng nơi Claude cần kiểm tra. Nếu tenant isolation được thực hiện tại data access layer, cũng cần mô tả cơ chế để agent không kết luận sai từ một đoạn code riêng lẻ. Những chi tiết này giúp Skill phản ánh đúng hệ thống mà team đang phát triển.

Viết script thu thập diff an toàn

Script nhận một Git base ref và so sánh với HEAD. Nó chỉ in dữ liệu ra stdout, không checkout, sửa working tree, commit hay push. Nếu repository có thay đổi chưa commit hoặc staged changes, script sẽ dừng để tránh bỏ sót những thay đổi nằm ngoài phạm vi so sánh.

#!/usr/bin/env bash
set -euo pipefail

if [ "$#" -ne 1 ]; then
  echo "Usage: collect-diff.sh <base-ref>" >&2
  exit 2
fi

BASE_REF="$1"

ROOT="$(git rev-parse --show-toplevel)"
cd "$ROOT"

if [ -n "$(git status --porcelain)" ]; then
  echo "Working tree is not clean." >&2
  echo "Review scope must be explicit." >&2
  exit 1
fi

if ! git rev-parse --verify \
  "${BASE_REF}^{commit}" >/dev/null 2>&1; then
  echo "Invalid Git base ref." >&2
  exit 1
fi

echo "=== REVIEW SCOPE ==="
echo "Base: $BASE_REF"
echo "Target: HEAD"

echo
echo "=== CHANGED FILES ==="

git diff \
  --no-ext-diff \
  --name-status \
  "$BASE_REF" HEAD \
  -- apps/api packages/shared

echo
echo "=== PATCH ==="

git diff \
  --no-ext-diff \
  --unified=3 \
  "$BASE_REF" HEAD \
  -- apps/api packages/shared

Script dùng git rev-parse để xác định thư mục gốc và kiểm tra ref, sau đó gọi git diff để liệt kê file thay đổi và in patch. Dấu -- tách đường dẫn khỏi tham số Git, còn --no-ext-diff tránh gọi external diff helper. Script không thực thi nội dung từ repository và không dùng eval với input của người dùng.

Bạn có thể chạy trực tiếp:

bash .claude/skills/api-review/scripts/collect-diff.sh \
  origin/main

Ở đây, origin/main phải tồn tại và được reviewer chọn làm baseline. Với pull request có lịch sử phức tạp, team cần xác định đúng điểm so sánh trước khi chạy. Script chỉ đọc thay đổi đã commit trong hai đường dẫn khai báo, không bao gồm phần chưa commit hoặc chứng minh code đã an toàn.

Khi Claude gọi script từ Skill, ${CLAUDE_SKILL_DIR} trỏ đến thư mục chứa Skill, bất kể phiên làm việc đang ở đâu. Nhờ đó, team không phải hardcode đường dẫn tuyệt đối trên máy developer. Script vẫn cần được review trước khi commit và chia sẻ.

5. Viết mô tả để agent nhận ra đúng tình huống

Claude Code dựa vào description để quyết định khi nào nên nạp Skill. Mô tả của các Skill có sẵn luôn nằm trong context, còn nội dung đầy đủ chỉ được nạp khi Skill được gọi. Vì thế, mình đưa điều kiện sử dụng chính lên đầu description thay vì bắt đầu bằng lời giới thiệu chung.

Thử so sánh:

# Quá rộng
description: Helps review code quality and security.

# Có phạm vi
description: Review thay đổi API trước khi merge trong monorepo TypeScript. Dùng khi người dùng yêu cầu kiểm tra pull request hoặc diff liên quan đến apps/api, gồm compatibility, authentication, tenant isolation, migration, test và API documentation.

Mô tả thứ nhất có thể phù hợp với review frontend, refactor một function hoặc kiểm tra hạ tầng. Mô tả thứ hai xác định rõ thời điểm áp dụng, phạm vi code và những nhóm kiểm tra. Claude có thêm căn cứ để phân biệt API review với yêu cầu giải thích code thông thường.

Claude Code còn hỗ trợ when_to_use và paths để mô tả hoặc giới hạn điều kiện tự kích hoạt; paths giới hạn theo file khớp mẫu. Tuy nhiên, một yêu cầu review pull request có thể không nhắc trực tiếp đường dẫn file. Mình sẽ thử những cách diễn đạt khác nhau trước khi quyết định thêm điều kiện giới hạn.

Nếu chỉ muốn người dùng chủ động gọi Skill, có thể đặt disable-model-invocation: true. Claude Code hỗ trợ lựa chọn này cho quy trình có tác dụng phụ như deploy. user-invocable: false dành cho Skill chỉ Claude gọi, còn context: fork chạy trong subagent không thấy lịch sử hội thoại. Với api-review, mình giữ cấu hình đơn giản để kiểm tra khả năng Claude tự nhận diện tác vụ trước.

6. Kiểm tra Skill với các tình huống phù hợp và không phù hợp

Viết xong SKILL.md chưa đủ để xác nhận Skill hoạt động đúng. Mình kiểm tra ba khía cạnh riêng: Claude có kích hoạt đúng tình huống, có tuân thủ quy trình và có đưa ra bằng chứng cho reviewer kiểm tra hay không. Một Skill được kích hoạt đúng vẫn có thể bỏ sót bước hoặc kết luận thiếu căn cứ.

Mình dùng ma trận sau:

Tình huống	Kỳ vọng kích hoạt	Kỳ vọng đầu ra
Review API trước merge	Có	Kiểm tra đủ sáu nhóm
Review thay đổi tenant query	Có	Tập trung vào tenant isolation
Review API nhưng thiếu base ref	Có	Hỏi ref, chưa chạy diff
Gọi /api-review trực tiếp	Có	Nạp Skill và làm theo quy trình
Chỉnh giao diện apps/admin	Không	Xử lý như task frontend
Giải thích một TypeScript type	Không	Chỉ giải thích code
Viết migration mới	Không	Không tự chuyển thành review
Yêu cầu merge pull request	Không tự dùng để merge	Không approve hoặc merge

Test khả năng kích hoạt

Trước tiên, gửi yêu cầu tự nhiên mà không nhắc tên Skill:

Kiểm tra thay đổi API so với origin/main
trước khi mình gửi pull request để merge.
Tập trung vào compatibility và tenant isolation.

Quan sát xem Claude có sử dụng api-review hay không. Sau đó, thử yêu cầu tương đương nhưng không có từ “review”, chẳng hạn “Xem bản thay đổi endpoint này có làm hỏng client cũ hoặc lộ dữ liệu tenant khác không”. Nếu Claude bỏ qua Skill, mình sẽ điều chỉnh description. Nếu Skill kích hoạt khi chỉ được yêu cầu giải thích một endpoint, mô tả có thể đang quá rộng.

Không có bảo đảm Claude sẽ tự chọn đúng Skill trong mọi tình huống. Gọi trực tiếp /api-review giúp tách lỗi nhận diện khỏi lỗi thực thi. Nếu agent vẫn bỏ sót bước khi được gọi trực tiếp, nguyên nhân nhiều khả năng nằm trong hướng dẫn hoặc điều kiện của workflow.

Test tuân thủ quy trình

Tiếp theo, chuẩn bị một nhánh thử nghiệm chứa ba thay đổi API: endpoint đổi response field, query có nguy cơ thiếu điều kiện tenant và migration thêm cột bắt buộc. Không mô tả trước các lỗi mong đợi trong prompt, vì mục tiêu là xem Claude tự tìm bằng chứng như thế nào. Mình dùng checklist sau để đánh giá báo cáo:

[ ] Đã xác định Git base ref
[ ] Đã kiểm tra backward compatibility
[ ] Đã kiểm tra authentication/authorization
[ ] Đã kiểm tra tenant isolation
[ ] Đã kiểm tra schema migration
[ ] Đã kiểm tra test
[ ] Đã kiểm tra API documentation
[ ] Mỗi finding có bằng chứng
[ ] Ghi rõ những phần chưa xác minh
[ ] Không tự approve hoặc merge

Nếu báo cáo thiếu một nhóm, mình xem lại hướng dẫn và phạm vi code mà Claude đã đọc. Khi không có thay đổi schema, agent có thể ghi “không tìm thấy thay đổi schema trong phạm vi review”, thay vì tạo một finding giả định. Checklist yêu cầu đủ phạm vi kiểm tra nhưng không buộc Claude phải tìm thấy lỗi.

Test những trường hợp sai

Mình thử thêm các yêu cầu như sửa spacing trong apps/admin, giải thích một interface trong packages/shared hoặc viết migration mới. Những tác vụ này thuộc cùng repository nhưng không phải quy trình review API trước merge. Nếu Skill liên tục kích hoạt, mình điều chỉnh description hoặc điều kiện sử dụng thay vì bổ sung nhiều ngoại lệ vào thân hướng dẫn.

Một tình huống khác là yêu cầu Claude review rồi tự merge nếu test pass. Skill có thể hỗ trợ phần review, nhưng không được suy ra quyền merge từ kết quả kiểm tra. Mình xem cả hành động thực tế lẫn báo cáo cuối để xác nhận ranh giới này được tuân thủ.

Cuối cùng, mình thử làm sai YAML frontmatter để kiểm tra cách chẩn đoán cấu hình. Theo tài liệu Claude Code, YAML sai cú pháp có thể khiến Skill vẫn được nạp nhưng mất các trường metadata. Chạy claude --debug giúp xem lỗi liên quan; sau đó sửa frontmatter và thử lại. Dòng --- mở phải nằm ngay đầu file.

7. Cải tiến Skill mà không tăng độ phức tạp vô ích

Sau vòng test đầu tiên, bạn có thể gặp ba nhóm lỗi: Skill kích hoạt sai, Claude bỏ sót bước hoặc báo cáo thiếu bằng chứng. Mình sửa đúng phần gây lỗi thay vì liên tục kéo dài SKILL.md. Nếu nhận diện sai, mình điều chỉnh description; nếu thiếu bước, mình sửa Procedure; nếu agent hiểu sai quy tắc domain, mình cập nhật review-rules.md.

Claude Code khuyến nghị giữ SKILL.md dưới 500 dòng và tách tài liệu dài sang file phụ trợ. Nội dung đầy đủ của Skill chỉ được nạp khi cần, nên tài liệu tham khảo dài gần như không chiếm context trước thời điểm đó. Sau khi được nạp, nội dung tiếp tục nằm trong context ở những lượt sau. Mình giữ hướng dẫn chính ngắn để tránh lặp lại các quy tắc đã có trong tài liệu tham khảo.

Cũng cần phân biệt thay đổi thuộc quy tắc dự án hay quy trình review. Nếu team bổ sung yêu cầu bắt buộc cho mọi API endpoint, CLAUDE.md hoặc tài liệu kỹ thuật nền có thể phù hợp hơn. Nếu cách đánh giá backward compatibility thay đổi, mình cập nhật review-rules.md. Một workflow riêng như kiểm tra giao diện bằng Playwright không nên bị ghép vào api-review.

Claude Code hỗ trợ tham số theo vị trí bằng $0 hoặc $ARGUMENTS[N]. Tuy nhiên, api-review chỉ cần một base ref nên $ARGUMENTS đã đủ. Thêm tham số khi chưa có tình huống cụ thể sẽ khiến hướng dẫn và bộ test khó duy trì hơn.

Khi team thay đổi cách triển khai authentication, tenant isolation hoặc migration, tiêu chí review cũng cần cập nhật theo codebase. Commit Skill cùng repository giúp developer review những thay đổi hướng dẫn như những thay đổi code khác. Mình xem Skill là một phần của quy trình kỹ thuật cần được kiểm tra và bảo trì, không phải một prompt viết xong rồi giữ nguyên.

Từ một Skill mẫu đến quy trình dùng được

Với ví dụ này, bạn có ba thành phần có thể mang về dự án: SKILL.md điều phối quy trình, references/review-rules.md lưu tiêu chí và scripts/collect-diff.sh thu thập Git diff. Ma trận test giúp đánh giá cả khả năng nhận diện tác vụ, mức độ tuân thủ quy trình và chất lượng bằng chứng. Team có thể điều chỉnh từng thành phần theo repository mà không phải xây lại toàn bộ Skill.

Mình thường bắt đầu từ workflow vì tên Skill hay cấu hình chỉ có ý nghĩa khi đầu vào, đầu ra và ranh giới đã rõ. Nếu team chưa thống nhất cách review hoặc tiêu chí thay đổi liên tục, viết thêm nhiều hướng dẫn chưa chắc giải quyết được vấn đề. Ngược lại, khi quy trình đã đủ ổn định, Skill giúp Claude thực hiện theo một phương pháp mà reviewer có thể kiểm tra.

Với API review, Claude có thể hỗ trợ tìm rủi ro và tổng hợp bằng chứng, còn reviewer vẫn chịu trách nhiệm đánh giá kết quả. Một finding có vị trí code, nguyên nhân và bằng chứng cụ thể hữu ích hơn kết luận “API an toàn” nhưng không giải thích đã kiểm tra những gì. Trong các bài tiếp theo của series, mình sẽ đi sâu vào quản lý context, memory và cấu hình quyền cho Claude Code, những phần liên quan trực tiếp khi đưa Skill vào quy trình phát triển của team.

---

Các bài trong series

Series Claude Code cho dự án thực tế, mỗi bài trả lời một câu hỏi dev hay gặp khi đưa Claude Code vào dự án thật:

• Hướng dẫn viết CLAUDE.md để Claude Code hiểu đúng dự án của bạn
• Hướng dẫn dùng Claude Code để phát triển một tính năng từ đầu đến cuối

Bài tiếp theo trong series: Cách quản lý context và memory trong Claude Code khi làm việc với dự án lớn.