Những điều học được khi xây dựng Claude Code: cách chúng tôi sử dụng Skills

• Trong Claude Code, Skills là một trong những điểm mở rộng được dùng nhiều nhất; bài viết chia sẻ kinh nghiệm thực chiến được đúc kết từ việc Anthropic vận hành hàng trăm skill nội bộ
• Skill không chỉ là một tệp Markdown đơn giản mà là cấu trúc thư mục gồm script, asset, dữ liệu..., ở dạng mà agent có thể khám phá và sử dụng
• Chúng được phân loại thành 9 nhóm skill như tham chiếu thư viện, kiểm chứng sản phẩm, phân tích dữ liệu, scaffolding mã, CI/CD..., và một skill tốt nên khớp gọn gàng với một nhóm duy nhất
• Khi viết skill, các mẹo thực chiến cốt lõi gồm phần Gotchas, tận dụng hệ thống tệp, công bố dần (Progressive Disclosure) và lưu trữ dữ liệu
• Khi mở rộng trong tổ chức, khuyến nghị phân phối skill qua chợ plugin nội bộ và theo dõi hiệu quả bằng các hook đo lường mức sử dụng

---

Skills là gì

• Hiểu lầm phổ biến về Skills là “chỉ là một tệp Markdown”, nhưng trên thực tế đây là một thư mục chứa script, asset, dữ liệu...
• Agent có thể duyệt thư mục này, phát hiện nội dung bên trong và thao tác với nó
• Trong Claude Code, Skills cung cấp nhiều tùy chọn cấu hình và cũng có thể đăng ký dynamic hooks
• Những skill thú vị nhất là các skill tận dụng sáng tạo chính các tùy chọn cấu hình và cấu trúc thư mục này

9 nhóm skill

• Khi phân loại toàn bộ các skill đang dùng nội bộ, chúng được gom cụm thành một vài nhóm lặp đi lặp lại
• Một skill tốt thường khớp gọn với một nhóm; skill gây rối thường trải trên nhiều nhóm

• 1. Library & API Reference

  • Skill giải thích cách dùng đúng thư viện, CLI, SDK
  • Không chỉ dành cho thư viện nội bộ mà còn cho cả các thư viện phổ biến mà Claude Code hay dùng sai
  • Thường gồm thư mục snippet mã tham chiếu và danh sách các lưu ý (gotchas)
  • Ví dụ: billing-lib(các edge case của thư viện thanh toán nội bộ), internal-platform-cli(tất cả subcommand và ví dụ sử dụng của CLI wrapper nội bộ), frontend-design(cải thiện việc áp dụng design system)

• 2. Product Verification

  • Skill mô tả cách kiểm thử và xác minh xem mã có hoạt động đúng hay không
  • Thường được dùng kết hợp với công cụ bên ngoài như Playwright, tmux
  • Rất hữu ích để đảm bảo độ chính xác đầu ra của Claude; đáng để kỹ sư đầu tư cả một tuần nhằm làm skill kiểm chứng thật tốt
  • Khuyến nghị các kỹ thuật như cho Claude ghi hình video đầu ra của mình, hoặc ép buộc assertion lập trình được về trạng thái ở từng bước
  • Ví dụ: signup-flow-driver(thực hiện đăng ký → xác minh email → onboarding bằng trình duyệt headless), checkout-verifier(chạy UI thanh toán bằng thẻ thử nghiệm Stripe rồi xác minh trạng thái hóa đơn), tmux-cli-driver(dùng để kiểm thử CLI tương tác cần TTY)

• 3. Data Fetching & Analysis

  • Skill kết nối tới stack dữ liệu và giám sát
  • Bao gồm thư viện truy xuất dữ liệu có chứa credential, ID dashboard cụ thể, hướng dẫn quy trình làm việc phổ biến...
  • Ví dụ: funnel-query(các sự kiện và bảng có canonical user_id cần cho funnel đăng ký → kích hoạt → thanh toán), cohort-compare(so sánh retention/tỷ lệ chuyển đổi của hai cohort và gắn cờ ý nghĩa thống kê), grafana(UID datasource, tên cluster, bảng tra cứu vấn đề → dashboard)

• 4. Business Process & Team Automation

  • Skill tự động hóa workflow lặp đi lặp lại chỉ bằng một lệnh
  • Phần hướng dẫn có thể tương đối đơn giản nhưng có thể phụ thuộc phức tạp vào skill khác hoặc MCP
  • Nếu lưu kết quả các lần chạy trước vào tệp log, mô hình sẽ dễ giữ tính nhất quán và phản ánh các lần thực thi trước đó hơn
  • Ví dụ: standup-post(đăng standup theo định dạng từ ticket tracker, hoạt động GitHub và Slack), create-ticket(ép schema và workflow sau khi tạo), weekly-recap(viết bài tổng kết từ PR đã merge + ticket đã đóng + các lần triển khai)

• 5. Code Scaffolding & Templates

  • Skill tạo boilerplate framework cho những chức năng cụ thể trong codebase
  • Có thể kết hợp với các script có khả năng ghép nối, đặc biệt hữu ích khi có yêu cầu ngôn ngữ tự nhiên mà chỉ riêng code không bao phủ hết
  • Ví dụ: new-framework-workflow(scaffold service/workflow/handler mới kèm annotation), new-migration(mẫu tệp migration và các lưu ý), create-app(tạo ứng dụng nội bộ mới đã nối sẵn xác thực, logging và cấu hình triển khai)

• 6. Code Quality & Review

  • Skill hỗ trợ cưỡng chế chất lượng mã trong tổ chức và hỗ trợ review code
  • Có thể bao gồm script hoặc công cụ mang tính quyết định để tăng độ vững chắc tối đa
  • Cũng có thể chạy tự động như một phần của hook hoặc GitHub Action
  • Ví dụ: adversarial-review(sub-agent với góc nhìn mới sẽ phê bình → sửa → lặp lại cho tới khi các góp ý chỉ còn ở mức nitpick), code-style(cưỡng chế style code mà Claude vốn làm chưa tốt), testing-practices(cách viết test và chỉ dẫn nên test gì)

• 7. CI/CD & Deployment

  • Skill dùng để lấy mã, đẩy mã và triển khai trong codebase
  • Có thể tham chiếu skill khác để thu thập dữ liệu
  • Ví dụ: babysit-pr(theo dõi PR → thử lại flaky CI → giải quyết xung đột merge → bật tự động merge), deploy-service(build → smoke test → rollout lưu lượng dần dần → so sánh tỷ lệ lỗi → tự động rollback nếu hồi quy), cherry-pick-prod(worktree cô lập → cherry-pick → giải quyết xung đột → tạo PR theo mẫu)

• 8. Runbooks

  • Skill nhận đầu vào là triệu chứng (thread Slack, cảnh báo, chữ ký lỗi...) để điều tra đa công cụ và tạo báo cáo có cấu trúc
  • Ví dụ: service-debugging(ánh xạ triệu chứng → công cụ → mẫu truy vấn), oncall-runner(lấy cảnh báo → kiểm tra nguyên nhân phổ biến → định dạng kết quả), log-correlator(thu thập log từ toàn bộ hệ thống liên quan bằng request ID)

• 9. Infrastructure Operations

  • Skill thực hiện quy trình vận hành và bảo trì thường nhật, đồng thời có guardrail cho các thao tác mang tính phá hủy
  • Giúp kỹ sư dễ tuân theo best practice trong những tác vụ vận hành quan trọng
  • Ví dụ: resource-orphans(tìm Pod/volume mồ côi → thông báo Slack → thời gian chờ → xác nhận của người dùng → dọn dẹp theo tầng), dependency-management(workflow phê duyệt dependency của tổ chức), cost-investigation(bucket và mẫu truy vấn để điều tra nguyên nhân tăng vọt chi phí storage/egress)

Mẹo viết skill

• Đừng viết những điều hiển nhiên

  • Claude Code đã biết khá nhiều về codebase và cũng có sẵn các quan điểm cơ bản về việc viết code
  • Nếu tạo skill thiên về tri thức, hãy tập trung vào thông tin khiến Claude lệch khỏi lối suy nghĩ mặc định của nó
  • Skill frontend-design là ví dụ tốt: nó được kỹ sư Anthropic tạo ra qua nhiều vòng lặp với khách hàng để cải thiện cảm quan thiết kế của Claude, và được cấu hình để tránh các mẫu rập khuôn như font Inter hay gradient tím

• Xây dựng phần Gotchas

  • Trong mọi skill, phần có giá trị tín hiệu cao nhất là Gotchas
  • Cần tích lũy phần này từ những điểm thất bại mà Claude thường gặp khi dùng skill
  • Lý tưởng nhất là tiếp tục cập nhật các gotcha này theo thời gian

• Tận dụng hệ thống tệp và công bố dần

  • Vì skill là một thư mục, cần tận dụng toàn bộ hệ thống tệp như phương tiện để context engineering và công bố dần
  • Nếu cho Claude biết trong skill có những tệp nào, nó sẽ đọc vào đúng thời điểm thích hợp
  • Dạng đơn giản nhất: tách chữ ký hàm chi tiết và ví dụ sử dụng sang một Markdown riêng như references/api.md
  • Nếu đầu ra cuối cùng là Markdown, có thể đặt tệp mẫu trong thư mục assets/
  • Các thư mục tham chiếu, script, ví dụ... giúp tăng hiệu quả làm việc của Claude

• Đừng ràng buộc Claude quá mức

  • Claude luôn cố tuân theo chỉ dẫn, nhưng skill có tính tái sử dụng cao nên cần cẩn trọng với chỉ dẫn quá cụ thể
  • Hãy cung cấp thông tin cần thiết nhưng vẫn chừa khoảng trống để nó thích nghi linh hoạt với bối cảnh

• Thiết kế quy trình thiết lập (Setup)

  • Một số skill cần giai đoạn thiết lập để thu thập ngữ cảnh từ người dùng
  • Ví dụ: nếu là skill đăng standup lên Slack thì cần hỏi sẽ đăng lên kênh nào
  • Mẫu tốt: lưu thông tin thiết lập vào tệp config.json trong thư mục skill; nếu chưa được thiết lập thì agent sẽ hỏi người dùng
  • Nếu muốn đưa ra câu hỏi có cấu trúc với nhiều lựa chọn, có thể chỉ định dùng công cụ AskUserQuestion

• Trường Description là dành cho mô hình

  • Khi Claude Code bắt đầu phiên làm việc, nó sẽ xây dựng danh sách description của mọi skill khả dụng
  • Claude quét danh sách này để quyết định “liệu có skill nào phù hợp với yêu cầu này không?”
  • Vì thế, trường description không phải là bản tóm tắt, mà là mô tả khi nào nên kích hoạt skill này

• Bộ nhớ và lưu trữ dữ liệu

  • Skill có thể chứa bộ nhớ theo dạng lưu dữ liệu
  • Có thể là từ tệp log văn bản đơn giản hay tệp JSON cho tới cơ sở dữ liệu SQLite
  • Ví dụ: nếu skill standup-post lưu toàn bộ lịch sử viết vào standups.log, lần chạy sau Claude có thể đọc lại lịch sử của mình và nhận ra thay đổi từ hôm qua
  • Dữ liệu lưu trong thư mục skill có thể bị xóa khi nâng cấp skill, nên cần lưu vào thư mục ổn định ${CLAUDE_PLUGIN_DATA}

• Lưu script và tạo code

  • Một trong những công cụ mạnh nhất có thể đưa cho Claude chính là bản thân mã nguồn
  • Nếu cung cấp script và thư viện, Claude có thể tập trung vào ghép nối (composition) thay vì tái dựng boilerplate
  • Ví dụ: trong skill khoa học dữ liệu, thêm thư viện hàm trợ giúp để lấy dữ liệu từ nguồn sự kiện
  • Claude có thể kết hợp các chức năng này để tạo script ngay tại chỗ, phục vụ những phân tích phức tạp như “Thứ Ba đã xảy ra chuyện gì?”

• On Demand Hooks

  • Skill có thể bao gồm các hook chỉ được kích hoạt khi skill được gọi và chỉ tồn tại trong suốt phiên
  • Phù hợp với các hook có quan điểm mạnh: quá nặng để luôn chạy nhưng rất hữu ích trong vài tình huống nhất định
  • Ví dụ:
    • /careful — chặn rm -rf, DROP TABLE, force-push, kubectl delete bằng bộ so khớp PreToolUse, chỉ bật khi thao tác trên môi trường production
    • /freeze — chặn mọi Edit/Write ngoài một thư mục cụ thể, hữu ích khi debug để tránh chỉnh sửa ngoài ý muốn

Triển khai skill

• Một trong những ưu điểm lớn của skill là có thể chia sẻ với cả nhóm
• Có hai cách chia sẻ:
  • Check in skill vào repo (dưới ./.claude/skills)
  • Đóng gói thành plugin và tải lên chợ Claude Code Plugin, để người dùng cài đặt

• Quản lý marketplace

  • Với nhóm nhỏ làm việc trên ít repo, cách check in vào repo là phù hợp
  • Skill được check in sẽ dần dần cộng thêm vào context của mô hình, nên khi quy mô tăng, chợ plugin nội bộ sẽ có lợi hơn
  • Không có đội trung tâm nào quyết định skill nào được đưa vào marketplace; các skill hữu ích nhất sẽ được phát hiện một cách tự nhiên
  • Nếu có skill muốn thử nghiệm, hãy tải lên thư mục sandbox trên GitHub và thông báo qua Slack hoặc kênh tương tự
  • Khi có đủ sức hút, chủ sở hữu skill sẽ gửi PR chuyển sang marketplace
  • Vì skill dở hoặc trùng lặp có thể dễ dàng xuất hiện, nên cơ chế kiểm tuyển trước khi phát hành là rất quan trọng

• Kết hợp skill (Composing Skills)

  • Có thể cần phụ thuộc giữa các skill (ví dụ: skill tải tệp lên + skill tạo và tải lên CSV)
  • Dù marketplace hay bản thân skill chưa có quản lý phụ thuộc gốc, nếu tham chiếu skill khác bằng tên thì mô hình sẽ gọi nó nếu đã được cài

• Đo lường skill

  • Để nắm được hiệu quả của skill, dùng hook PreToolUse để ghi log mức sử dụng skill trong công ty
  • Có thể dùng để tìm các skill phổ biến hoặc các skill được kích hoạt ít hơn kỳ vọng

Kết luận

• Skills là công cụ rất mạnh và linh hoạt cho agent, nhưng vẫn đang ở giai đoạn đầu; mọi người vẫn đang trong quá trình tìm ra cách tận dụng tốt nhất
• Bài viết này không phải hướng dẫn mang tính khẳng định tuyệt đối mà là tập hợp các mẹo đã chứng minh hiệu quả trong thực tế
• Hầu hết skill đều bắt đầu chỉ từ vài dòng và một gotcha, rồi được mọi người liên tục bổ sung và cải tiến mỗi khi Claude gặp edge case mới

[xguru]

Dạo này khi nhìn vào Anthropic, tôi có cảm giác rằng các bộ phận phụ trách phát triển đang chia sẻ tối đa những gì họ đã trải nghiệm, đồng thời khuyến khích mọi người sử dụng sản phẩm của họ tốt hơn

Có cảm giác như đây là một ví dụ sống động cho thấy “hệ sinh thái phát triển trong kỷ nguyên AI được xây dựng như thế này”.