Bài học từ việc xây dựng Claude Code: Cách chúng tôi sử dụng Skills (Vietnamese translation)

2026-03-28 - Bai hoc tu viec xay dung Claude Code Cach chung toi su dung Skills.md

title	Bài học từ việc xây dựng Claude Code: Cách chúng tôi sử dụng Skills
date	2026-03-28
tags	translation AI/Agents Claude
source	https://x.com/trq212/status/2033949937936085378
author	[[Thariq]]

2026-03-28 – Bài học từ việc xây dựng Claude Code: Cách chúng tôi sử dụng Skills

[!info] Nguồn gốc Bài viết được dịch từ: Lessons from Building Claude Code: How We Use Skills bởi [[Thariq]].

[!abstract] Executive Summary & Action Items

• Skills không chỉ là text: Chúng là các thư mục chứa scripts, assets, data và config giúp Claude làm việc hiệu quả và chính xác hơn.
• Phân loại Skills rõ ràng: Có 9 loại skill phổ biến như Library & API Reference, Product Verification, Data Fetching, Business Process Automation, v.v. Việc phân loại giúp xác định tổ chức đang thiếu loại skill nào.
• Best Practices khi tạo Skills: Đừng viết những thứ hiển nhiên, hãy tập trung vào phần "Gotchas" (những lỗi thường gặp), sử dụng File System để tối ưu context (Progressive Disclosure), và có thể lưu trữ trạng thái/memory.

Action Items:

• Review lại các context/prompts hiện tại xem có thể đóng gói thành Skills theo 9 phân loại không.
• Cấu trúc lại các thư mục Skills hiện có, tách các function signatures và example ra các file riêng (ví dụ: references/api.md) để áp dụng Progressive Disclosure.
• Thêm phần "Gotchas" vào các skill hiện tại và liên tục cập nhật dựa trên lỗi Claude thường gặp.

Skills đã trở thành một trong những điểm mở rộng (extension points) được sử dụng nhiều nhất trong Claude Code. Chúng linh hoạt, dễ tạo và đơn giản để phân phối.

Nhưng chính sự linh hoạt này cũng khiến việc biết được điều gì hoạt động tốt nhất trở nên khó khăn. Loại skill nào thì đáng để tạo? Bí quyết để viết một skill tốt là gì? Khi nào thì bạn chia sẻ chúng với người khác?

Chúng tôi đã sử dụng skills trong Claude Code một cách rộng rãi tại Anthropic với hàng trăm skill đang được sử dụng thực tế. Dưới đây là những bài học chúng tôi đã rút ra được về cách sử dụng skills để tăng tốc độ phát triển của mình.

Skills là gì? (What are Skills?)

Nếu bạn mới làm quen với skills, tôi khuyên bạn nên đọc tài liệu của chúng tôi hoặc xem khóa học mới nhất của chúng tôi trên new Skilljar on Agent Skills, bài viết này sẽ giả định rằng bạn đã có một chút hiểu biết cơ bản về skills.

Một quan niệm sai lầm phổ biến mà chúng tôi thường nghe về skills là chúng "chỉ là các file markdown", nhưng phần thú vị nhất của skills là chúng không chỉ là các file text. Chúng là các thư mục có thể bao gồm scripts, assets, data, v.v. mà agent có thể khám phá, tìm hiểu và thao tác.

Trong Claude Code, skills cũng có rất nhiều tùy chọn cấu hình bao gồm cả việc đăng ký các dynamic hooks.

Chúng tôi nhận thấy rằng một số skills thú vị nhất trong Claude Code sử dụng các tùy chọn cấu hình và cấu trúc thư mục này một cách rất sáng tạo.

Các loại Skills (Types of Skills)

Sau khi phân loại tất cả các skills của mình, chúng tôi nhận thấy chúng tập trung vào một vài danh mục lặp đi lặp lại. Những skills tốt nhất sẽ nằm gọn gàng trong một danh mục; những skills khó hiểu hơn thì thường trải dài qua vài danh mục. Đây không phải là một danh sách chốt hạ, nhưng nó là một cách tốt để bạn suy nghĩ xem liệu tổ chức của mình có đang thiếu sót phần nào không.

![[claude-code-skills-types.jpg]]

1. Tham chiếu Thư viện & API (Library & API Reference)

Đây là các skills giải thích cách sử dụng chính xác một thư viện, CLI, hoặc SDKs. Chúng có thể dành cho các 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 dùng. Những skills này thường bao gồm một thư mục chứa các đoạn code mẫu (reference code snippets) và một danh sách các "gotchas" (lỗi dễ mắc phải) để Claude tránh khi viết script.

Ví dụ:

• billing-lib — thư viện thanh toán nội bộ của bạn: các edge cases, footguns (những lỗi có thể tự bắn vào chân mình), v.v.
• internal-platform-cli — mọi subcommand của CLI wrapper nội bộ cùng với các ví dụ về thời điểm sử dụng chúng.
• frontend-design — làm cho Claude hiểu rõ hơn về design system của bạn.

2. Xác minh Sản phẩm (Product Verification)

Các skills mô tả cách test hoặc xác minh rằng code của bạn đang hoạt động đúng. Chúng thường được ghép nối với một công cụ bên ngoài như playwright, tmux, v.v. để thực hiện việc xác minh.

Các verification skills cực kỳ hữu ích để đảm bảo output của Claude là chính xác. Việc để một kỹ sư dành ra hẳn một tuần chỉ để làm cho các verification skills của bạn trở nên xuất sắc là hoàn toàn xứng đáng.

Hãy cân nhắc các kỹ thuật như việc yêu cầu Claude quay lại video về quá trình output để bạn có thể thấy chính xác những gì nó đã test, hoặc thực thi các programmatic assertions (kiểm tra trạng thái bằng code) ở mỗi bước. Điều này thường được thực hiện bằng cách đưa nhiều loại scripts khác nhau vào trong skill.

Ví dụ:

• signup-flow-driver — chạy qua luồng signup → xác minh email → onboarding trong headless browser, có các hooks để assert state ở từng bước.
• checkout-verifier — điều khiển UI checkout bằng các thẻ test của Stripe, xác minh xem hóa đơn có thực sự rơi vào đúng trạng thái mong muốn hay không.
• tmux-cli-driver — dùng cho việc test CLI tương tác, khi thứ mà bạn đang xác minh cần một môi trường TTY.

3. Lấy dữ liệu & Phân tích (Data Fetching & Analysis)

Các skills kết nối với data và monitoring stacks của bạn. Những skills này có thể bao gồm các thư viện để lấy data của bạn bằng credentials, specific dashboard ids (ID của dashboard cụ thể), v.v. cũng như các hướng dẫn về những workflow phổ biến hoặc cách lấy dữ liệu.

Ví dụ:

• funnel-query — "tôi cần join những events nào để xem luồng signup → activation → paid" kèm theo tên bảng chứa user_id chuẩn (canonical).
• cohort-compare — so sánh retention (tỷ lệ giữ chân) hoặc conversion (tỷ lệ chuyển đổi) của hai cohorts, đánh dấu các sai số có ý nghĩa thống kê, link tới các định nghĩa segment.
• grafana — datasource UIDs, cluster names, bảng tra cứu vấn đề → dashboard.

4. Tự động hóa Quy trình Doanh nghiệp & Team (Business Process & Team Automation)

Các skills tự động hóa các workflow lặp đi lặp lại thành một câu lệnh duy nhất. Những skills này thường có hướng dẫn khá đơn giản nhưng lại có thể có các dependencies phức tạp hơn vào các skills hoặc MCPs khác. Đối với những skills này, việc lưu lại kết quả trước đó vào các log files có thể giúp model duy trì tính nhất quán và phản ánh lại những lần chạy workflow trước đó.

Ví dụ:

• standup-post — tổng hợp ticket tracker, GitHub activity, và nội dung Slack trước đó của bạn → tạo bài post standup được format sẵn, chỉ chứa những thay đổi (delta-only).
• create-<ticket-system>-ticket — ép schema (các giá trị enum hợp lệ, các trường bắt buộc) cộng thêm workflow sau khi tạo (ping reviewer, thả link vào Slack).
• weekly-recap — merged PRs + closed tickets + deploys → bài post recap hàng tuần được format đẹp đẽ.

5. Sinh mã & Template (Code Scaffolding & Templates)

Các skills sinh ra framework boilerplate cho một function cụ thể trong codebase. Bạn có thể kết hợp các skills này với các scripts có khả năng tái tổ hợp (composed). Chúng đặc biệt hữu ích khi việc scaffolding của bạn có các yêu cầu bằng ngôn ngữ tự nhiên mà không thể chỉ cover được bằng code.

Ví dụ:

• new-<framework>-workflow — scaffold ra một service/workflow/handler mới kèm theo những chú thích của bạn.
• new-migration — template cho file migration của bạn cộng với các lỗi thường gặp (common gotchas).
• create-app — app nội bộ mới đã được nối sẵn auth, logging và config deploy.

6. Chất lượng Code & Review (Code Quality & Review)

Các skills thực thi tiêu chuẩn chất lượng code trong nội bộ tổ chức và giúp review code. Chúng có thể bao gồm các deterministic scripts (script có kết quả tất định) hoặc các tools để đạt được độ tin cậy tối đa. Bạn có thể muốn chạy những skills này một cách tự động như một phần của hooks hoặc bên trong một GitHub Action.

Ví dụ:

• adversarial-review — spawn ra một subagent với "con mắt mới mẻ" (fresh-eyes) để nhận xét, implement các fix, và lặp lại cho đến khi các lỗi chỉ còn là những điều lặt vặt (nitpicks).
• code-style — thực thi code style, đặc biệt là những style mà mặc định Claude làm không tốt lắm.
• testing-practices — các hướng dẫn về cách viết test và nên test những gì.

7. CI/CD & Triển khai (CI/CD & Deployment)

Các skills giúp bạn lấy (fetch), đẩy (push), và deploy code bên trong codebase của mình. Các skills này có thể tham chiếu đến những skills khác để thu thập dữ liệu.

Ví dụ:

• babysit-pr — theo dõi một PR → retry lại các flaky CI → resolve merge conflicts → bật auto-merge.
• deploy-<service> — build → smoke test → rollout traffic từ từ với việc so sánh error-rate → tự động rollback nếu bị regression.
• cherry-pick-prod — tạo worktree độc lập → cherry-pick → resolve conflict → mở PR với template.

8. Sổ tay vận hành (Runbooks)

Các skills nhận vào một triệu chứng (chẳng hạn như một thread trên Slack, cảnh báo alert, hoặc một error signature), lướt qua quá trình điều tra bằng multi-tool, và sản xuất ra một báo cáo có cấu trúc.

Ví dụ:

• <service>-debugging — map các triệu chứng → tools → mẫu truy vấn cho các services có traffic cao nhất của bạn.
• oncall-runner — fetch cái alert → kiểm tra các nguyên nhân thường gặp → format lại kết quả tìm được.
• log-correlator — từ một request ID đưa vào, kéo các log khớp nối từ mọi system có thể đã chạm vào request đó.

9. Vận hành Hạ tầng (Infrastructure Operations)

Các skills thực hiện việc bảo trì định kỳ và các thủ tục vận hành — một số trong đó liên quan đến các hành động mang tính phá hủy (destructive) rất cần có guardrails bảo vệ. Chúng giúp các kỹ sư tuân thủ best practices trong các chiến dịch vận hành quan trọng dễ dàng hơn.

Ví dụ:

• <resource>-orphans — tìm các pods/volumes bị mồ côi → báo lên Slack → khoảng thời gian chờ (soak period) → user xác nhận → dọn dẹp hàng loạt (cascading cleanup).
• dependency-management — workflow phê duyệt dependency của tổ chức bạn.
• cost-investigation — "tại sao chi phí storage/egress của chúng ta lại tăng đột biến" kiểm tra các buckets và các query patterns cụ thể.

Các Mẹo khi tạo Skills (Tips for Making Skills)

![[claude-code-skills-tips.jpg]]

Khi bạn đã quyết định được skill cần tạo, làm thế nào để viết nó? Dưới đây là một số best practices, tips, và tricks mà chúng tôi đã tìm ra.

Gần đây chúng tôi cũng đã phát hành Skill Creator để giúp việc tạo skills trong Claude Code dễ dàng hơn.

Đừng nói những điều hiển nhiên (Don’t State the Obvious)

Claude Code đã biết rất nhiều về codebase của bạn, và Claude cũng biết rất nhiều về lập trình, bao gồm nhiều quan điểm mặc định. Nếu bạn đang publish một skill chủ yếu là về knowledge, hãy cố gắng tập trung vào những thông tin đẩy Claude ra khỏi lối tư duy thông thường của nó.

Skill frontend design là một ví dụ tuyệt vời — nó được xây dựng bởi một kỹ sư tại Anthropic bằng cách liên tục iteration với khách hàng để cải thiện gu thiết kế (design taste) của Claude, tránh các pattern cổ điển như dùng font Inter và gradient màu tím.

Xây dựng phần "Gotchas" (Build a Gotchas Section)

![[claude-code-skills-gotchas.jpg]]

Nội dung có "tín hiệu cao" (highest-signal content) nhất trong bất kỳ skill nào chính là phần Gotchas. Những phần này nên được đúc kết từ các failure points (điểm lỗi) phổ biến mà Claude hay gặp phải khi sử dụng skill của bạn. Lý tưởng nhất, bạn sẽ cập nhật skill của mình qua thời gian để bổ sung các gotchas này.

Sử dụng File System & Phân bổ thông tin lũy tiến (Use the File System & Progressive Disclosure)

![[claude-code-skills-fs.jpg]]

Như chúng tôi đã nói ở trên, một skill là một thư mục, không phải chỉ là một file markdown. Bạn nên coi toàn bộ file system như một hình thức của context engineering và progressive disclosure (tiết lộ thông tin lũy tiến). Hãy nói cho Claude biết có những file gì trong skill của bạn, và nó sẽ đọc chúng vào những thời điểm thích hợp.

Hình thức đơn giản nhất của progressive disclosure là trỏ tới các file markdown khác để Claude sử dụng. Ví dụ, bạn có thể tách các function signatures chi tiết và cách dùng (usage examples) vào file references/api.md.

Một ví dụ khác: nếu output cuối cùng của bạn là một file markdown, bạn có thể đặt một file template cho nó vào trong thư mục assets/ để copy và dùng.

Bạn có thể tạo các thư mục chứa references, scripts, examples, v.v., những thứ này sẽ giúp Claude hoạt động hiệu quả hơn.

Tránh gò ép Claude (Avoid Railroading Claude)

Claude nhìn chung sẽ cố gắng bám sát vào hướng dẫn của bạn, và bởi vì Skills có tính tái sử dụng cao nên bạn cần cẩn thận không được quá cứng nhắc/chi tiết trong các hướng dẫn của mình. Hãy cung cấp cho Claude những thông tin cần thiết, nhưng vẫn để cho nó sự linh hoạt để thích ứng với tình huống. Ví dụ:

![[claude-code-skills-railroad.jpg]]

Nghĩ kỹ về phần Thiết lập (Think through the Setup)

![[claude-code-skills-setup.jpg]]

Một số skills có thể cần phải được setup dựa trên ngữ cảnh từ user. Ví dụ, nếu bạn đang tạo một skill post nội dung standup lên Slack, bạn có thể muốn Claude hỏi xem nên post vào channel Slack nào.

Một pattern tốt để làm việc này là lưu trữ thông tin setup vào file config.json bên trong thư mục skill giống như ví dụ trên. Nếu config chưa được thiết lập, agent lúc đó có thể hỏi người dùng để lấy thông tin.

Nếu bạn muốn agent hiển thị ra các câu hỏi trắc nghiệm có cấu trúc, bạn có thể hướng dẫn Claude dùng tool AskUserQuestion.

Trường Mô tả (Description) là dành cho Model

Khi Claude Code bắt đầu một session, nó sẽ build ra một danh sách chứa mọi skill hiện có cùng với phần mô tả (description) của chúng. Danh sách này chính là thứ mà Claude dùng để quét và quyết định "liệu có skill nào phù hợp cho request này không?". Điều đó có nghĩa là trường description không phải là một đoạn tóm tắt (summary) — nó là một bản mô tả về khi nào thì nên trigger (kích hoạt) skill này.

![[claude-code-skills-desc.jpg]]

Memory & Lưu trữ Dữ liệu (Memory & Storing Data)

![[claude-code-skills-memory.jpg]]

Một số skills có thể sở hữu một dạng "trí nhớ" bằng cách lưu trữ dữ liệu bên trong chúng. Bạn có thể lưu trữ dữ liệu vào bất cứ thứ gì, từ một text log file chỉ dùng để append, một file JSON, cho tới một SQLite database phức tạp.

Ví dụ, một skill standup-post có thể giữ một file standups.log lưu mọi bài post mà nó từng viết, nghĩa là ở lần chạy tiếp theo, Claude có thể tự đọc lịch sử của chính mình và biết được điều gì đã thay đổi so với ngày hôm qua.

Dữ liệu được lưu trong thư mục skill có thể sẽ bị xóa đi khi bạn upgrade skill, nên bạn cần lưu cái này ở một thư mục ổn định (stable folder). Hiện tại, chúng tôi cung cấp biến môi trường ${CLAUDE_PLUGIN_DATA} đóng vai trò là thư mục ổn định cho mỗi plugin để lưu dữ liệu.

Lưu trữ Scripts & Sinh Code (Store Scripts & Generate Code)

Một trong những công cụ mạnh mẽ nhất mà bạn có thể cung cấp cho Claude chính là code. Việc cung cấp cho Claude các scripts và thư viện sẽ giúp nó dành số turns của mình vào việc tổ hợp (composition), ra quyết định xem bước tiếp theo cần làm gì thay vì ngồi gõ lại các mã boilerplate.

Ví dụ, trong data science skill của bạn, bạn có thể có một thư viện các hàm để fetch data từ event source của mình. Để Claude có thể thực hiện các phân tích phức tạp, bạn có thể đưa cho nó một tập hợp các helper functions như sau:

![[claude-code-skills-store1.jpg]]

Sau đó Claude có thể tự động generate các scripts on the fly để kết hợp những chức năng này lại và làm các phân tích chuyên sâu hơn, ứng với các prompt dạng "Có chuyện gì xảy ra vào thứ Ba tuần trước?"

![[claude-code-skills-store2.jpg]]

Các Hooks theo yêu cầu (On Demand Hooks)

Skills có thể bao gồm các hooks chỉ được kích hoạt khi skill đó được gọi, và kéo dài trong suốt thời gian của session đó. Hãy dùng cái này cho những hooks có tính áp đặt cao (opinionated) mà bạn không muốn chúng chạy mọi lúc, nhưng thi thoảng lại cực kỳ hữu ích.

Ví dụ:

• /**careful** — chặn rm -rf, DROP TABLE, force-push, kubectl delete thông qua PreToolUse matcher trên Bash. Bạn chỉ muốn bật cái này lên khi bạn biết mình đang đụng vào môi trường prod — việc lúc nào cũng bật nó sẽ khiến bạn phát điên.
• /**freeze** — chặn bất kỳ thao tác Edit/Write nào không thuộc về một thư mục cụ thể. Rất hữu ích khi debugging: "Tôi muốn thêm logs nhưng tôi cứ vô tình 'sửa' nhầm phần khác."

Phân phối Skills (Distributing Skills)

Một trong những lợi ích lớn nhất của Skills là bạn có thể chia sẻ chúng với các thành viên khác trong team của mình.

Có hai cách để bạn chia sẻ skills với người khác:

• commit trực tiếp skills của bạn vào repo (dưới thư mục ./.claude/skills).
• đóng gói thành một plugin và tạo một Claude Code Plugin marketplace nơi mà user có thể upload và cài đặt các plugins (đọc thêm trên tài liệu tại đây).

Đối với các team nhỏ làm việc với một vài repo, việc check in skills vào repo hoạt động rất tốt. Nhưng mỗi skill được check in cũng tốn thêm một chút context của model. Khi bạn mở rộng (scale), một plugin marketplace nội bộ sẽ cho phép bạn phân phối các skills và để tự team của bạn quyết định xem họ muốn cài đặt cái nào.

Quản lý Marketplace (Managing a Marketplace)

Làm sao bạn quyết định được skill nào sẽ được đưa vào marketplace? Mọi người submit chúng bằng cách nào?

Chúng tôi không có một team tập trung nào đứng ra quyết định việc này; thay vào đó, chúng tôi cố gắng tìm ra những skills hữu ích nhất một cách tự nhiên (organically). Nếu bạn có một skill mà bạn muốn mọi người dùng thử, bạn có thể upload nó lên một thư mục sandbox trên GitHub và thả link cho mọi người trong Slack hoặc các forums khác.

Một khi skill đó bắt đầu có "độ phủ" (điều này do chủ sở hữu skill tự đánh giá), họ có thể mở một PR để chuyển nó vào marketplace.

Có một cảnh báo nhỏ, việc tạo ra các skills tồi hoặc bị lặp (redundant) là khá dễ, vậy nên đảm bảo bạn có một phương pháp chọn lọc (curation) trước khi release là điều rất quan trọng.

Kết hợp Skills (Composing Skills)

Bạn có thể muốn có những skills phụ thuộc vào nhau. Ví dụ, bạn có thể có một skill upload file để up file lên, và một skill tạo CSV để sinh ra file CSV rồi upload nó. Kiểu quản lý dependency này hiện tại chưa được support native bên trong marketplace hay skills, nhưng bạn có thể tham chiếu các skills khác thông qua tên của chúng, và model sẽ tự động gọi chúng lên nếu chúng đã được cài đặt.

Đo lường Skills (Measuring Skills)

Để hiểu xem một skill đang hoạt động như thế nào, chúng tôi dùng một PreToolUse hook cho phép chúng tôi ghi log lại mức độ sử dụng skill trong nội bộ công ty (code mẫu tại đây). Điều này có nghĩa là chúng tôi có thể tìm ra được những skills nào đang phổ biến hoặc những skills nào đang ít được gọi (undertriggering) so với kỳ vọng của mình.

Kết luận (Conclusion)

Skills là những công cụ vô cùng mạnh mẽ, linh hoạt dành cho các agents, nhưng hiện tại vẫn còn rất sớm và tất cả chúng ta đều đang tìm hiểu xem làm thế nào để sử dụng chúng tốt nhất.

Hãy coi bài viết này như một chiếc túi gom nhặt những mẹo hữu ích mà chúng tôi đã thấy hiệu quả hơn là một cuốn cẩm nang chốt hạ. Cách tốt nhất để hiểu về skills là bắt tay vào làm, thử nghiệm, và xem điều gì hoạt động tốt cho bạn. Hầu hết các skills của chúng tôi đều bắt đầu từ một vài dòng code và một cái gotcha duy nhất, rồi dần dần tốt lên vì mọi người liên tục bổ sung vào đó mỗi khi Claude đụng phải những edge cases mới.

Tôi hy vọng bài viết này hữu ích, hãy cho tôi biết nếu bạn có bất kỳ câu hỏi nào.