Bài học từ quá trình xây dựng Claude Code: Cách chúng tôi dùng skill

Tác giả bài gốc: Thariq Shihipar (Member of Technical Staff). Đăng ngày 03/06/2026 trên claude.dev.

Skill đã trở thành một trong những điểm mở rộng được dùng nhiều nhất trong Claude Code. Chúng linh hoạt, dễ tạo và dễ phân phối.

Nhưng chính sự linh hoạt này cũng khiến bạn khó biết cách nào hiệu quả nhất. Loại skill nào đáng để tạo? Bạn nên tổ chức một skill ra sao? Khi nào nên chia sẻ chúng với người khác?

Tại Anthropic, chúng tôi sử dụng skill rất nhiều trong Claude Code, với hàng trăm skill đang được dùng thường xuyên. Dưới đây là những bài học chúng tôi rút ra khi dùng skill để đẩy nhanh quá trình phát triển.

Skill là gì?

Skill là các thư mục chứa hướng dẫn, script và tài nguyên mà agent có thể khám phá và sử dụng để làm việc chính xác, hiệu quả hơn. Bài viết này giả định bạn đã nắm kiến thức cơ bản về skill; nếu mới bắt đầu, hãy học khóa Giới thiệu về agent skill của chúng tôi trên Skilljar.

Một hiểu lầm phổ biến mà chúng tôi thường nghe là skill “chỉ là các file Markdown”. Thực ra, chúng là những thư mục có thể chứa script, tài nguyên, dữ liệu, v.v. để agent khám phá, tìm hiểu và thao tác.

Trong Claude Code, skill còn có rất nhiều tùy chọn cấu hình, bao gồm đăng ký hook động.

Chúng tôi nhận thấy một số skill hiệu quả nhất trong Claude Code tận dụng tốt những tùy chọn cấu hình và cấu trúc thư mục này.

Các loại skill

Sau khi thống kê toàn bộ skill nội bộ tại Anthropic, chúng tôi nhận thấy chúng tập trung vào chín nhóm. Những skill tốt nhất thuộc hẳn về một nhóm; những skill cố làm quá nhiều việc lại trải rộng qua nhiều nhóm và khiến agent bối rối. Đây không phải danh sách đầy đủ nhất, nhưng là một khung tham chiếu hữu ích để tìm những gì còn thiếu trong thư viện skill của bạn.

Lưới ba hàng, ba cột liệt kê các nhóm skill cùng tên skill ví dụ: Tài liệu tham khảo thư viện và API, Kiểm chứng sản phẩm, Dữ liệu và phân tích, Tự động hóa nghiệp vụ, Code khung và template, Chất lượng code và review, CI/CD và deploy, Runbook xử lý sự cố, Vận hành hạ tầng.

Nhóm Claude Code đã phân loại các skill nội bộ và nhận thấy chúng có thể được chia thành chín nhóm riêng biệt.

1. Tài liệu tham khảo thư viện và API

Đây là những skill giải thích cách dùng đúng một thư viện, CLI hoặc SDK. Chúng có thể dành cho thư viện nội bộ hoặc các thư viện phổ biến mà Claude Code đôi khi gặp khó khăn khi sử dụng. Những skill này thường có một thư mục chứa các đoạn code tham khảo và danh sách những điểm dễ mắc lỗi (gotchas) để Claude tránh khi viết script.

Ví dụ:

billing-lib — thư viện thanh toán nội bộ của bạn: trường hợp biên, những chỗ dễ gây lỗi khi dùng, v.v.
internal-platform-cli — mọi lệnh con trong lớp bọc CLI nội bộ của bạn, kèm ví dụ về lúc nên dùng.
sandbox-proxy — cấu hình gateway cho lưu lượng đi ra ngoài của tổ chức để phục vụ công việc phát triển: những host nào truy cập được, cách debug lỗi “connection refused”, cách thêm một mục vào allowlist.

2. Kiểm chứng sản phẩm

Đây là những skill mô tả cách kiểm thử hoặc xác minh rằng code của bạn hoạt động đúng. Chúng thường được dùng cùng playwright, tmux hoặc những tool bên ngoài khác để kiểm chứng.

Trong nội bộ, các skill kiểm chứng có tác động dễ đo lường nhất đến chất lượng đầu ra của Claude. Việc dành hẳn một tuần làm việc của một kỹ sư để xây dựng skill kiểm chứng thật tốt có thể rất đáng giá.

Hãy cân nhắc những cách như để Claude quay video đầu ra của nó, giúp bạn thấy chính xác nó đã kiểm thử những gì, hoặc bắt buộc kiểm tra trạng thái bằng assertion trong chương trình ở từng bước. Những việc này thường được thực hiện bằng cách đưa nhiều script khác nhau vào skill.

Ví dụ:

signup-flow-driver — chạy qua luồng đăng ký → xác minh email → onboarding trong trình duyệt headless, với hook để kiểm tra trạng thái ở từng bước
checkout-verifier — thao tác với UI thanh toán bằng thẻ thử nghiệm của Stripe, xác minh rằng hóa đơn thực sự chuyển sang đúng trạng thái
tmux-cli-driver — phục vụ kiểm thử CLI tương tác khi đối tượng cần kiểm chứng đòi hỏi TTY

3. Lấy và phân tích dữ liệu

Đây là những skill kết nối với hệ thống dữ liệu và giám sát của bạn. Chúng có thể bao gồm thư viện lấy dữ liệu bằng thông tin xác thực, ID của những dashboard cụ thể, v.v., cùng hướng dẫn về các workflow phổ biến hoặc cách lấy dữ liệu.

Ví dụ:

funnel-query — “cần join những sự kiện nào để xem luồng đăng ký → kích hoạt → trả phí”, cùng bảng thực sự chứa user_id chuẩn
cohort-compare — so sánh tỷ lệ giữ chân hoặc chuyển đổi của hai nhóm người dùng (cohort), đánh dấu chênh lệch có ý nghĩa thống kê, liên kết đến định nghĩa của từng phân khúc
grafana — UID của datasource, tên cluster, bảng tra từ vấn đề → dashboard
datadog — tài liệu tham khảo các trường (@request_id so với trace_id), danh sách service, quy ước tiền tố metric

4. Tự động hóa quy trình nghiệp vụ và công việc của nhóm

Đây là những skill tự động hóa các workflow lặp đi lặp lại thành một lệnh. Hướng dẫn của chúng thường khá đơn giản nhưng có thể có những phụ thuộc phức tạp hơn vào skill khác hoặc MCP. Với các skill này, lưu kết quả trước đó trong file log có thể giúp model giữ tính nhất quán và xem lại những lần thực hiện workflow trước.

Ví dụ:

standup-post — tổng hợp hệ thống theo dõi ticket, hoạt động GitHub và nội dung Slack trước đó → bản cập nhật standup được định dạng, chỉ gồm những thay đổi
create-<ticket-system>-ticket — áp dụng schema bắt buộc (giá trị enum hợp lệ, trường bắt buộc) cùng workflow sau khi tạo (nhắc reviewer, gửi liên kết lên Slack)
weekly-recap — các PR đã merge + ticket đã đóng + những lần deploy → bài tổng kết được định dạng

5. Code khung và template

Đây là những skill tạo code khung (boilerplate) của framework cho một chức năng cụ thể trong codebase. Bạn có thể kết hợp chúng với những script có thể ghép nối với nhau. Chúng đặc biệt hữu ích khi code khung của bạn có yêu cầu bằng ngôn ngữ tự nhiên mà chỉ riêng code không thể bao quát hết.

Ví dụ:

new-<framework>-workflow — tạo khung cho service/workflow/handler mới kèm các annotation của bạn
new-migration — template file migration của bạn cùng những điểm dễ mắc lỗi thường gặp
create-app — app nội bộ mới được tích hợp sẵn xác thực, logging và cấu hình deploy của bạn

6. Chất lượng code và review

Đây là những skill đảm bảo tiêu chuẩn chất lượng code trong tổ chức và hỗ trợ review code. Chúng có thể bao gồm các script hoặc tool có hành vi xác định để đạt độ tin cậy cao nhất. Bạn có thể muốn chạy chúng tự động thông qua hook hoặc trong một GitHub Action.

adversarial-review — tạo một subagent với góc nhìn mới để phản biện, sửa các vấn đề, lặp lại cho đến khi những phát hiện chỉ còn là góp ý vụn vặt
code-style — áp dụng quy chuẩn code style, đặc biệt là những phong cách mà mặc định Claude chưa làm tốt.
testing-practices — hướng dẫn cách viết test và cần test những gì.

7. CI/CD và deploy

Đây là những skill giúp bạn fetch, push và deploy code trong codebase. Chúng có thể tham chiếu đến skill khác để thu thập dữ liệu.

Ví dụ:

babysit-pr — theo dõi PR → chạy lại CI không ổn định → giải quyết xung đột merge → bật auto-merge
deploy-<service> — build → smoke test → triển khai dần lưu lượng kèm so sánh tỷ lệ lỗi → tự động rollback khi có vấn đề phát sinh
cherry-pick-prod — worktree riêng biệt → cherry-pick → giải quyết xung đột → PR theo template

8. Runbook

Đây là những skill tiếp nhận dấu hiệu của vấn đề (chẳng hạn một chuỗi trao đổi trên Slack, cảnh báo hoặc mẫu lỗi đặc trưng), thực hiện điều tra qua nhiều tool và tạo báo cáo có cấu trúc.

Ví dụ:

<service>-debugging — ánh xạ dấu hiệu → tool → mẫu query cho những service có lưu lượng cao nhất của bạn
oncall-runner — lấy cảnh báo → kiểm tra những nguyên nhân thường gặp → trình bày kết quả phát hiện
log-correlator — nhận một request ID rồi lấy log tương ứng từ mọi hệ thống có thể đã xử lý request đó

9. Vận hành hạ tầng

Đây là những skill thực hiện các thủ tục bảo trì và vận hành thường xuyên, trong đó một số có thao tác phá hủy dữ liệu nên sẽ hữu ích khi có cơ chế bảo vệ. Chúng giúp kỹ sư dễ tuân thủ best practice hơn trong những hoạt động quan trọng.

Ví dụ:

<resource>-orphans — tìm pod/volume mồ côi → đăng lên Slack → giai đoạn chờ theo dõi → người dùng xác nhận → dọn dẹp dây chuyền
dependency-management — workflow phê duyệt dependency của tổ chức bạn
cost-investigation — “tại sao hóa đơn lưu trữ/lưu lượng đi ra của chúng ta tăng vọt”, kèm những bucket và mẫu query cụ thể

Mẹo tạo skill

Sau khi quyết định sẽ tạo skill nào, bạn nên viết nó ra sao? Dưới đây là một số best practice, mẹo và thủ thuật tạo skill của nhóm Claude Code.

Đừng nhắc lại điều hiển nhiên

Claude đã biết lập trình và có thể đọc codebase của bạn. Một skill nhắc lại những gì mặc định Claude sẽ làm chỉ thêm context mà không thêm giá trị. Nếu bạn công bố một skill chủ yếu cung cấp kiến thức, hãy tập trung vào thông tin giúp Claude thoát khỏi lối suy nghĩ thông thường của nó.

Skill thiết kế frontend là một ví dụ rất tốt; một kỹ sư tại Anthropic đã xây dựng nó bằng cách liên tục làm việc với khách hàng để cải thiện gu thiết kế của Claude, tránh những mẫu quen thuộc như font Inter và gradient màu tím.

Xây dựng mục những điểm dễ mắc lỗi

Cùng một file skill Billing Lib vào ngày 1, tuần 2 và tháng 3. Mục Gotchas xuất hiện rồi tăng từ một dòng (làm tròn xuống khi tính phí theo tỷ lệ) lên bốn dòng.

Nội dung có giá trị nhất trong bất kỳ skill nào là mục Gotchas. Bạn nên xây dựng mục này từ những điểm Claude thường gặp lỗi khi dùng skill. Lý tưởng nhất là bạn cập nhật skill theo thời gian để ghi nhận những điểm dễ mắc lỗi ấy.

Ví dụ:

“Bảng subscriptions chỉ cho phép thêm dữ liệu. Hàng bạn cần là hàng có phiên bản cao nhất, không phải hàng có created_at gần đây nhất.”
“Trường này có tên là @request_id trong API gateway và trace_id trong service thanh toán. Chúng có cùng giá trị.”
“Staging trả về 200 ngay cả khi webhook Stripe chưa thực sự được xử lý. Hãy kiểm tra payment_events để biết trạng thái thật.”

Sử dụng hệ thống file và tiết lộ dần

Thư mục skill queue-debugging với SKILL.md ở trung tâm, còn stuck-jobs.md, dead-letters.md, retry-storms.md và consumer-lag.md là các nhánh. SKILL.md chứa bảng ánh xạ từ dấu hiệu sang file, cho Claude biết cần đọc file nào.

File SKILL.md trỏ đến một số file khác mà Claude có thể tham khảo trong những tình huống cụ thể. Ví dụ, nếu một job đang chờ xử lý, nó nên tham khảo stuck-jobs.md.

Như đã nói ở trên, skill là một thư mục, không chỉ là một file Markdown. Bạn nên xem toàn bộ hệ thống file là một cách thiết kế context (context engineering) và tiết lộ dần (progressive disclosure). Hãy cho Claude biết skill có những file nào, rồi nó sẽ đọc chúng vào thời điểm phù hợp.

Hình thức tiết lộ dần đơn giản nhất là trỏ đến các file Markdown khác để Claude sử dụng. Ví dụ, bạn có thể tách chữ ký hàm chi tiết và ví dụ sử dụng sang references/api.md.

Một ví dụ khác: nếu đầu ra cuối cùng là file Markdown, bạn có thể đặt một file template trong assets/ để sao chép và sử dụng.

Bạn có thể có các thư mục chứa tài liệu tham khảo, script, ví dụ, v.v. để giúp Claude làm việc hiệu quả hơn.

Tránh ép Claude đi theo một lộ trình cứng nhắc

Claude nhìn chung sẽ cố bám sát hướng dẫn của bạn, và vì skill có thể tái sử dụng rất nhiều, bạn cần cẩn thận để hướng dẫn không quá cụ thể. Hãy cung cấp thông tin Claude cần, nhưng vẫn để nó linh hoạt thích ứng với tình huống.

Ví dụ:

Hai phiên bản hướng dẫn cherry-pick. Quá cứng nhắc: sáu bước đánh số ghi rõ từng lệnh git. Tốt hơn: “Cherry-pick commit lên một nhánh sạch. Giải quyết xung đột nhưng giữ nguyên ý định ban đầu. Nếu không thể áp dụng gọn gàng, hãy giải thích lý do.”

Nêu mục tiêu và các ràng buộc, không phải từng bước thực hiện.

Suy nghĩ kỹ về bước thiết lập

SKILL.md của standup-post có mục “Cấu hình của bạn” chạy lệnh shell đọc config.json và in NOT_CONFIGURED nếu file không tồn tại; hướng dẫn yêu cầu Claude hỏi kênh Slack và một bản standup mẫu khi chưa cấu hình, rồi lưu các câu trả lời.

Skill ở trên được viết để hỏi người dùng nếu cấu hình chưa có kênh Slack.

Một số skill có thể cần thiết lập với context từ người dùng. Ví dụ, nếu tạo skill đăng bản cập nhật standup lên Slack, bạn có thể muốn Claude hỏi nên đăng vào kênh Slack nào.

Một cách hay để làm việc này là lưu thông tin thiết lập trong file config.json ở thư mục skill như ví dụ trên. Nếu chưa có cấu hình, agent có thể hỏi người dùng để lấy thông tin.

Nếu muốn agent đưa ra câu hỏi có cấu trúc với nhiều lựa chọn, bạn có thể hướng dẫn Claude dùng tool AskUserQuestion.

Viết mô tả cho model, không phải cho con người

Khi Claude Code bắt đầu một session, nó lập danh sách tất cả skill có sẵn kèm mô tả. Claude đọc danh sách này để quyết định “có skill nào dành cho yêu cầu này không?”. Điều đó có nghĩa trường mô tả không phải là bản tóm tắt, mà là phần mô tả khi nào nên kích hoạt skill.

Hai mô tả SKILL.md cho babysit-pr. Bên trái: “Một tool toàn diện để theo dõi trạng thái pull request trong suốt vòng đời phát triển.” Bên phải: “Theo dõi PR cho đến khi được merge. Kích hoạt khi gặp ‘babysit’, ‘watch CI’, ‘make sure this lands’.”

Đưa những từ kích hoạt skill, chẳng hạn “babysit”, vào mô tả sẽ rất hữu ích.

Giúp Claude ghi nhớ

File ~/.claude/standups.log có các mục ghi ngày cho ba ngày liên tiếp; chuỗi trao đổi về thiết kế lại onboarding được tô nổi bật trong cả ba mục.

File log văn bản này giúp Claude nhớ những sự kiện trước đó, chẳng hạn việc review PR xác thực của Sarah.

Một số skill có thể có dạng bộ nhớ bằng cách lưu dữ liệu bên trong chúng. Bạn có thể lưu dữ liệu theo cách đơn giản như file log văn bản chỉ thêm vào cuối hoặc file JSON, hay phức tạp hơn như cơ sở dữ liệu SQLite.

Ví dụ, skill standup-post có thể lưu standups.log chứa mọi bài đăng nó đã viết. Nhờ vậy, lần tiếp theo bạn chạy skill, Claude đọc lịch sử của chính nó và biết điều gì đã thay đổi so với hôm qua.

Bạn có thể dùng biến môi trường ${CLAUDE_PLUGIN_DATA} để lấy một thư mục ổn định nhằm lưu dữ liệu. Đọc thêm về việc lưu dữ liệu bền vững trong skill tại đây: https://code.claude.com/docs/en/plugins-reference#persistent-data-directory.

Lưu script và tạo code

Một trong những công cụ mạnh mẽ nhất bạn có thể cung cấp cho Claude chính là code. Khi có script và thư viện, Claude có thể dành các lượt làm việc để kết hợp chúng, quyết định nên làm gì tiếp theo thay vì dựng lại code khung.

Ví dụ, trong skill data-science, bạn có thể có một thư viện hàm lấy dữ liệu từ nguồn sự kiện. Để Claude thực hiện phân tích phức tạp, bạn có thể cung cấp một bộ hàm hỗ trợ như sau:

lib/signups.py có ba hàm hỗ trợ, fetch, by_referrer và by_landing_page, với docstring ghi những điểm dễ mắc lỗi về dữ liệu, chẳng hạn user_id là null cho đến sau khi đăng ký.

Cung cấp cho Claude một thư viện nhỏ gồm các hàm hỗ trợ, với những điểm dễ mắc lỗi được ghi trong docstring.

Sau đó, Claude có thể tạo script ngay khi cần để kết hợp các chức năng này, thực hiện những phân tích nâng cao hơn cho các prompt như “Chuyện gì đã xảy ra vào thứ Ba?”.

investigate.py do Claude tạo, import những hàm hỗ trợ đó để so sánh lượt đăng ký vào thứ Hai và thứ Ba theo nguồn giới thiệu và trang đích, rồi kết luận có gì đó bị hỏng trên trang chủ vào thứ Ba.

Claude kết hợp các hàm hỗ trợ thành một script dùng riêng cho câu hỏi đang cần giải đáp.

Sử dụng hook theo nhu cầu

Skill có thể bao gồm những hook chỉ được kích hoạt khi gọi skill và chỉ tồn tại trong thời gian của session. Hãy dùng cách này cho những hook áp đặt quy tắc cụ thể mà bạn không muốn chạy mọi lúc, nhưng đôi khi lại vô cùng hữu ích.

Ví dụ:

/careful — chặn rm -rf, DROP TABLE, force-push, kubectl delete thông qua matcher PreToolUse trên Bash. Bạn chỉ muốn bật nó khi biết mình đang động vào prod — bật suốt sẽ khiến bạn phát điên.
/freeze — chặn mọi Edit/Write không nằm trong một thư mục cụ thể. Hữu ích khi debug: “Mình muốn thêm log nhưng cứ vô tình ‘sửa’ cả code không liên quan.”

Phân phối skill

Một trong những lợi ích lớn nhất của skill là bạn có thể chia sẻ chúng với những người còn lại trong nhóm.

Có hai cách bạn có thể muốn dùng để chia sẻ skill:

đưa skill vào repo (trong ./.claude/skills)
tạo một plugin và có một marketplace plugin Claude Code để người dùng tải lên và cài đặt plugin (đọc thêm trong tài liệu tại đây)

Với những nhóm nhỏ làm việc trên tương đối ít repo, đưa skill vào repo là cách hiệu quả. Nhưng mỗi skill được đưa vào cũng làm tăng context của model một chút. Khi quy mô lớn hơn, marketplace plugin nội bộ cho phép bạn phân phối skill và để nhóm tự quyết định cài những skill nào, đồng thời có thể kèm quy trình thiết lập.

Quản lý marketplace skill

Làm sao để quyết định skill nào được đưa vào marketplace? Mọi người gửi skill lên bằng cách nào?

Tại Anthropic, chúng tôi không có một nhóm tập trung đưa ra quyết định này; thay vào đó, chúng tôi cố tìm những skill hữu ích nhất qua quá trình sử dụng tự nhiên. Nếu ai đó có skill muốn mọi người thử, họ có thể tải nó lên một thư mục sandbox trên GitHub và giới thiệu với mọi người trên Slack hoặc các diễn đàn khác.

Khi skill đã được nhiều người dùng đón nhận (do người sở hữu skill tự đánh giá), họ có thể tạo PR để chuyển nó vào marketplace.

Kết hợp skill

Bạn có thể muốn có những skill phụ thuộc lẫn nhau. Ví dụ, bạn có một skill tải file lên, và một skill tạo CSV rồi tải file CSV đó lên. Hiện marketplace hay skill chưa có sẵn cơ chế quản lý kiểu phụ thuộc này, nhưng bạn có thể tham chiếu skill khác bằng tên, rồi model sẽ gọi chúng nếu đã được cài đặt.

Đo lường skill

Để hiểu một skill đang hoạt động ra sao, chúng tôi dùng hook PreToolUse cho phép ghi log việc sử dụng skill trong công ty (code ví dụ tại đây). Nhờ vậy, chúng tôi có thể tìm những skill phổ biến hoặc được kích hoạt ít hơn so với kỳ vọng.

Bắt đầu

Best practice về skill vẫn đang phát triển. Hầu hết những skill tốt nhất của chúng tôi bắt đầu từ vài dòng và một điểm dễ mắc lỗi, rồi dần tốt lên vì mọi người liên tục bổ sung khi Claude gặp những trường hợp biên mới.

Cách tốt nhất để hiểu skill là bắt tay vào làm, thử nghiệm và xem điều gì phù hợp với bạn.

Bài viết này do Thariq Shihipar, thành viên đội ngũ kỹ thuật tại Anthropic đang làm việc trên Claude Code, thực hiện.