Hướng dẫn hoàn chỉnh để xây dựng Claude Skills

• Claude Skills là gói kiến thức workflow được thiết kế để tái sử dụng liên tục sau khi định nghĩa một lần cho các luồng công việc lặp lại
• Tài liệu PDF 33 trang do Anthropic trực tiếp biên soạn, trình bày toàn bộ quy trình từ thiết kế skill đến cấu trúc hóa, kiểm thử và triển khai theo từng bước
• Bao gồm nhiều kịch bản ứng dụng, từ tự động hóa workflow độc lập đến tăng cường tích hợp công cụ dựa trên MCP
• Được biên soạn dựa trên các mẫu đã được kiểm chứng trong môi trường vận hành thực tế và các trường hợp thất bại
• Nếu đã sắp xếp được 2–3 workflow quan trọng nhất, có thể xây dựng và kiểm thử skill đầu tiên trong vòng 15–30 phút

---

Introduction

• Hướng dẫn này nhằm xem Claude Skills như tài sản workflow có thể tái sử dụng, chứ không phải prompt dùng một lần
• Skills được định nghĩa là cấu trúc cho phép dạy Claude một lần về một tác vụ hoặc quy trình cụ thể, rồi tái sử dụng nhất quán trong mọi cuộc hội thoại về sau
• Nhờ không cần phải giải thích lại sở thích, cách làm việc hay kiến thức miền của người dùng mỗi lần, nó có thể giảm đáng kể chi phí nhận thức và vận hành

• Những tình huống Skills đặc biệt hiệu quả

  • Skills phát huy hiệu quả lớn nhất trong các tác vụ có thể lặp lại và có cấu trúc
    • Tạo thiết kế frontend dựa trên đặc tả
    • Thực hiện nghiên cứu theo một phương pháp luận nhất quán
    • Soạn tài liệu phản ánh style guide của đội ngũ
    • Điều phối các quy trình phức hợp gồm nhiều bước
  • Kết hợp tự nhiên với các chức năng tích hợp sẵn của Claude như thực thi mã, tạo tài liệu

• Phân biệt vai trò giữa MCP và Skills

  • Khi dùng tích hợp MCP, Skills được mô tả là lớp bổ sung giúp ổn định workflow, vượt xa việc chỉ kết nối công cụ đơn thuần
  • Nếu MCP cung cấp “có thể làm gì”, thì Skills đảm nhận việc cố định “phải làm như thế nào”
  • Nhờ đó có thể chuyển đổi quyền truy cập công cụ ở mức thô thành trải nghiệm tự động hóa đáng tin cậy

• Mục đích và phạm vi của hướng dẫn

  • Tài liệu này bao quát toàn bộ quy trình cần thiết để xây dựng Skills
    • Lập kế hoạch trước và thiết kế cấu trúc
    • Cách viết thực tế
    • Kiểm thử và cải tiến lặp lại
    • Triển khai và chia sẻ
  • Nhắm tới mọi phạm vi ứng dụng, từ skill cá nhân, skill tiêu chuẩn nội bộ cho đội nhóm đến skill để chia sẻ với cộng đồng
  • Tập trung vào các mẫu và ví dụ đã được kiểm chứng trong thực tế, hơn là giải thích lý thuyết

• Đối tượng độc giả

  • Nhà phát triển muốn Claude luôn thực hiện một workflow cụ thể theo cùng một cách
  • Power user muốn tự động hóa các tác vụ lặp lại
  • Các đội nhóm muốn chuẩn hóa cách sử dụng Claude ở cấp độ tổ chức
  • Builder muốn kết hợp kiến thức workflow vào các connector MCP

• Lộ trình sử dụng hướng dẫn

  • Nếu mục tiêu là xây dựng Skills độc lập:
    • Fundamentals
    • Planning and Design
    • Khuyến nghị tham khảo tập trung vào Category 1–2
  • Nếu mục tiêu là tăng cường tích hợp MCP:
    • Mục Skills + MCP
    • Khuyến nghị sử dụng tập trung vào Category 3
  • Hai lộ trình này chia sẻ các yêu cầu kỹ thuật chung và có thể chọn áp dụng chỉ những phần cần thiết

• Kết quả kỳ vọng

  • Hướng dẫn này được thiết kế để bạn có thể hoàn thành một Skill hữu ích chỉ trong một phiên làm việc nếu làm theo từng bước
  • Nếu có sẵn 2–3 workflow rõ ràng và quan trọng nhất, Skill đầu tiên có thể được xây dựng và kiểm thử trong khoảng 15–30 phút
  • Phần Introduction làm rõ góc nhìn cốt lõi mà mọi chương sau đều dựa trên, tức là
    “Skills không phải prompt mà là kiến thức công việc có thể tái sử dụng”

Chapter 1: Khái niệm cơ bản (Fundamentals)

• Giải thích nền tảng khái niệm và triết lý thiết kế để hiểu Claude Skills
• Định nghĩa Skills không phải là tập hợp prompt đơn thuần mà là đơn vị kiến thức công việc được tái sử dụng liên tục
• Đồng thời tổng hợp các nguyên tắc cốt lõi làm tiền đề cho thảo luận về thiết kế, kiểm thử và triển khai ở các chương sau

• Skill là gì

  • Skill là cấu trúc cho phép dạy Claude một lần cách thực hiện một tác vụ hoặc workflow cụ thể để có thể dùng lặp lại
  • Được thiết kế để không cần phải giải thích lại sở thích, quy trình hay kiến thức miền của người dùng mỗi lần
  • Phát huy hiệu quả lớn nhất ở các tác vụ có tính lặp lại cao
  • Ví dụ:
    • Tạo thiết kế frontend dựa trên đặc tả
    • Thực hiện nghiên cứu theo cách nhất quán
    • Soạn tài liệu tuân theo style guide của đội ngũ
    • Tự động thực thi quy trình nhiều bước

• Các thành phần cơ bản của Skill

  • Skill được tổ chức theo đơn vị một thư mục
  • Thành phần bắt buộc:
    • SKILL.md: tệp cốt lõi chứa YAML frontmatter và hướng dẫn bằng Markdown
  • Thành phần tùy chọn:
    • scripts/: mã thực thi như Python, Bash
    • references/: tài liệu và hướng dẫn được tham chiếu khi cần
    • assets/: template, tài nguyên dùng cho đầu ra
  • Cấu trúc này được thiết kế để đồng thời đáp ứng cả tính đơn giản lẫn khả năng mở rộng

• Nguyên tắc thiết kế cốt lõi 1: Progressive Disclosure

  • Skills tuân theo cấu trúc nạp thông tin 3 tầng

  • Tầng 1: YAML frontmatter

    • Luôn được nạp vào system prompt của Claude
    • Chỉ chứa lượng thông tin tối thiểu để xác định khi nào nên dùng skill
    • Có vai trò ngăn việc nạp ngữ cảnh không cần thiết

  • Tầng 2: phần thân SKILL.md

    • Được nạp khi Claude đánh giá skill là có liên quan
    • Chứa quy trình và hướng dẫn thực hiện công việc thực tế

  • Tầng 3: các tệp được liên kết

    • Như references, scripts, assets
    • Chỉ được khám phá khi Claude đánh giá là cần thiết
    • Giúp giảm thiểu lượng token sử dụng trong khi vẫn duy trì tính chuyên môn
  • Cấu trúc này đạt được sự cân bằng giữa chi phí ngữ cảnh và độ chính xác của tác vụ

• Nguyên tắc thiết kế cốt lõi 2: Composability

  • Claude có thể nạp nhiều Skills cùng lúc
  • Vì vậy, mỗi Skill:
    • Không nên giả định rằng nó sẽ luôn chạy độc lập
    • Phải được thiết kế để không xung đột với các Skill khác
  • Mặc định lấy môi trường có khả năng cộng tác giữa các skill làm tiền đề

• Nguyên tắc thiết kế cốt lõi 3: Portability

  • Skills được thiết kế để hoạt động giống nhau trong môi trường Claude.ai, Claude Code và API
  • Một Skill đã tạo có thể tái sử dụng mà không cần chỉnh sửa theo từng nền tảng
  • Tuy vậy, script hay quyền truy cập mạng vẫn chịu ràng buộc bởi giới hạn của môi trường thực thi

• Mối quan hệ giữa MCP và Skills

  • Khi sử dụng MCP, Skills đóng vai trò lớp tri thức (knowledge layer)
  • MCP cung cấp quyền truy cập vào công cụ và dữ liệu
  • Skills định nghĩa cách nên sử dụng các công cụ đó

  • Ví von nhà bếp

    • MCP: nhà bếp, nguyên liệu, dụng cụ nấu nướng
    • Skills: công thức nấu ăn
    • Khi hai thứ kết hợp, người dùng không cần tự thiết kế trực tiếp các quy trình phức tạp

• Trường hợp sử dụng không có MCP

  • Skills vẫn đủ hữu ích ngay cả khi không có MCP
  • Chỉ với các chức năng tích hợp sẵn của Claude như tạo tài liệu, thực thi mã, vẫn có thể:
    • Chuẩn hóa các tác vụ lặp lại
    • Đảm bảo tính nhất quán về chất lượng
    • Cải thiện tốc độ làm việc

• Thông điệp cốt lõi của chương này

• Skills không phải là tối ưu hóa prompt ngắn hạn mà là tài sản công việc được tích lũy liên tục
• Cốt lõi không phải là “có thể làm gì” mà là “cố định cách phải làm như thế nào”
• Các chương sau sẽ mở rộng từ khái niệm này sang các giai đoạn thiết kế và vận hành thực tế

Chương 2: Lập kế hoạch và thiết kế (Planning and Design)

• Chương này dựa trên tiền đề rằng thành bại của việc xây dựng Skills gần như được quyết định bởi chất lượng thiết kế trước giai đoạn viết

• Trước khi triển khai kỹ thuật, cần làm rõ mình sẽ giải quyết vấn đề gì và sẽ cố định luồng nào

• Một Skill được thiết kế tốt sẽ giúp việc triển khai đơn giản hơn, đồng thời giảm đáng kể chi phí kiểm thử và bảo trì

• Điểm khởi đầu: định nghĩa use case

  • Trước khi viết skill, nhất thiết phải định nghĩa 2~3 use case cụ thể
  • Use case không phải là mục tiêu trừu tượng, mà phải bao gồm cả câu người dùng thực sự sẽ nói và kết quả đầu ra

  • Các thành phần của một use case tốt

    • Mục tiêu mà người dùng muốn đạt được
    • Câu kích hoạt mà người dùng có khả năng sẽ nói
    • Các tác vụ theo từng bước cần thực hiện nội bộ
    • Công cụ được sử dụng (tính năng mặc định của Claude hoặc MCP)
    • Trạng thái kết quả cuối cùng
  • Qua ví dụ, tài liệu nhấn mạnh tầm quan trọng của việc định nghĩa rõ điều kiện bắt đầu – các bước xử lý – trạng thái hoàn tất, như trong trường hợp “lập kế hoạch sprint”

• Những câu hỏi cốt lõi cần tự hỏi trước khi thiết kế

  • Người dùng muốn hoàn thành điều gì
  • Cần workflow nhiều bước nào để đạt được kết quả đó
  • Ở bước nào thì cần công cụ nào
  • Sẽ nhúng kiến thức miền hoặc best practice đòi hỏi phán đoán của con người vào đâu
  • Nếu không thể trả lời rõ các câu hỏi này thì vẫn chưa ở trạng thái sẵn sàng để cố định thành Skill

• Các loại use case Skill chính đã được quan sát

  • Category 1: Tạo tài liệu và tài sản

    • Được dùng để tạo ra đầu ra mà chất lượng nhất quán là yếu tố quan trọng
    • Bao gồm tài liệu, bài thuyết trình, thiết kế, mã, sản phẩm UI v.v.
    • Đặc điểm:
      • Tích hợp sẵn style guide và quy tắc thương hiệu
      • Tận dụng template đầu ra
      • Bao gồm checklist kiểm tra chất lượng cuối cùng
    • Có thể hoàn tất chỉ bằng tính năng mặc định của Claude mà không cần công cụ bên ngoài

  • Category 2: Tự động hóa workflow

    • Phù hợp với các quy trình cần lặp đi lặp lại nhiều bước
    • Ví dụ: skill-creator
    • Đặc điểm:
      • Bao gồm tiến trình theo từng bước và các điểm kiểm chứng
      • Cung cấp template có cấu trúc
      • Tích hợp vòng lặp review và cải tiến ở giữa chặng
    • Được mô tả là loại hình coi trọng độ ổn định của quy trình hơn là kết quả

  • Category 3: Tăng cường MCP

    • Chuyển đổi quyền truy cập công cụ do server MCP cung cấp thành workflow thực sự có thể sử dụng
    • Đặc điểm:
      • Kết hợp tuần tự nhiều lời gọi MCP
      • Tự động bổ sung ngữ cảnh mà người dùng không cần trực tiếp nêu rõ
      • Tích hợp sẵn cách xử lý cho các tình huống lỗi MCP
    • Không chỉ là tự động hóa đơn thuần mà được định nghĩa là đóng gói cách sử dụng mang tính chuyên biệt

• Tầm quan trọng của việc định nghĩa tiêu chí thành công

  • Skill không nên được đánh giá bằng việc “trông có vẻ hoạt động tốt”, mà phải dựa trên việc nó có tạo ra hiệu quả cải thiện hay không
  • Tiêu chí thành công không phải là những con số quá chính xác, mà được đưa ra dưới dạng tiêu chí có định hướng

  • Tiêu chí định lượng

    • Tự động được kích hoạt trong phần lớn các yêu cầu dự định
    • Khi dùng skill, số lần gọi công cụ và lượng token sử dụng giảm xuống
    • Hoàn tất workflow mà không xảy ra lỗi gọi MCP

  • Tiêu chí định tính

    • Có thể tiếp tục tiến hành ngay cả khi người dùng không chỉ định bước tiếp theo
    • Khi chạy lặp lại, cấu trúc và chất lượng kết quả vẫn nhất quán
    • Ngay cả người dùng mới cũng có thể thành công ngay từ lần thử đầu
  • Tài liệu thừa nhận rằng việc đánh giá có thể bao gồm một mức độ phán đoán cảm tính (vibes) nhất định, nhưng cũng nêu rõ rằng cần giữ nguyên tiêu chuẩn so sánh

• Tổng quan yêu cầu kỹ thuật

  • Skill phải tuân theo cấu trúc thư mục cố định
  • Tệp SKILL.md là bắt buộc và tên phải khớp chính xác
  • Tên thư mục và trường name sử dụng kebab-case
  • Không đặt README.md bên trong thư mục Skill

• Vai trò của YAML frontmatter

  • Frontmatter là tín hiệu cốt lõi để Claude quyết định khi nào cần tải skill
  • Các trường tối thiểu bắt buộc:
    • name
    • description
  • Description bắt buộc phải bao gồm:
    • Skill làm gì
    • Dùng khi nào
    • Những cách diễn đạt cụ thể mà người dùng có thể sẽ nói
  • Ngôn ngữ từ góc nhìn người dùng quan trọng hơn mô tả kỹ thuật

• Nguyên tắc thiết kế frontmatter

  • Giữ trong phạm vi 1024 ký tự
  • Cấm dùng thẻ XML
  • Vì lý do bảo mật, việc dùng một số tên nhất định (claude, anthropic) bị hạn chế
  • Metadata là tùy chọn, nhưng khuyến nghị bao gồm thông tin phiên bản và tác giả

• Định hướng thiết kế phần thân SKILL.md

  • Cung cấp hướng dẫn rõ ràng và có thể thực thi theo từng bước
  • Đưa ra ví dụ cùng với kết quả kỳ vọng
  • Bao gồm các lỗi thường gặp và cách khắc phục
  • Các phần giải thích quá dài nên tách sang thư mục references

• Điểm cốt lõi của Chương 2 là Skills không nên được xem như “một gói prompt”, mà phải được xử lý như sản phẩm thiết kế workflow có chủ đích

Chương 3: Kiểm thử và cải tiến lặp lại (Testing and Iteration)

• Chương này tập trung vào quy trình nâng Skills lên mức thực sự đáng tin cậy
• Với skill, điều cốt lõi không nằm ở việc viết ra nó, mà là quy trình kiểm chứng khi nào nó được tải, cách nó được thực thi và kết quả được cải thiện ra sao
• Điều quan trọng là phải điều chỉnh cường độ kiểm thử theo phạm vi sử dụng và mức độ ảnh hưởng

• Lựa chọn mức độ kiểm thử

  • Việc kiểm thử Skills có thể được thực hiện ở các mức khác nhau tùy theo chất lượng yêu cầu và phạm vi triển khai

  • Kiểm thử thủ công (Claude.ai)

    • Nhập truy vấn trực tiếp trên Claude.ai để kiểm tra hoạt động
    • Có thể lặp lại nhanh mà không cần thiết lập riêng
    • Phù hợp để xác minh thiết kế ban đầu và sửa nhanh

  • Kiểm thử dựa trên script (Claude Code)

    • Tự động hóa các test case trong môi trường Claude Code
    • Hữu ích cho kiểm thử hồi quy khi các thay đổi được tích lũy
    • Phù hợp với skill dùng cho đội ngũ nội bộ

  • Kiểm thử chương trình dựa trên API

    • Tự động chạy bộ kiểm thử đã xác định bằng Skills API
    • Có thể so sánh định lượng và kiểm chứng có hệ thống
    • Phù hợp với triển khai quy mô lớn và môi trường doanh nghiệp
• Skill quy mô nhỏ dùng nội bộ và skill công khai ra bên ngoài không đòi hỏi cùng một tiêu chuẩn kiểm thử

• Cách tiếp cận được khuyến nghị: bắt đầu từ một tác vụ khó

  • Người tạo skill hiệu quả sẽ tập trung vào một tác vụ khó và cải tiến lặp đi lặp lại
  • Khi Claude có thể xử lý ổn định tác vụ đó, họ trích xuất cách tiếp cận vào thời điểm thành công ấy và cố định nó thành một Skill
  • So với kiểm thử diện rộng, lặp lại một trường hợp đơn lẻ có tín hiệu mạnh mang lại quá trình học nhanh hơn
  • Chỉ sau đó mới mở rộng sang kiểm thử với nhiều trường hợp khác nhau

• Các khu vực kiểm thử cốt lõi

  • 1. Kiểm thử trigger

    • Mục tiêu: xác minh liệu skill có chỉ tự động được tải trong những tình huống phù hợp hay không
    • Hạng mục bao gồm:
      • Được trigger trong các yêu cầu rõ ràng
      • Vẫn được trigger khi cách diễn đạt của yêu cầu thay đổi
      • Không được tải trong các yêu cầu không liên quan
    • Chất lượng trigger liên quan trực tiếp đến cách thiết kế trường description

  • 2. Kiểm thử chức năng

    • Mục tiêu: xác nhận skill có tạo ra chính xác kết quả như dự định hay không
    • Đối tượng kiểm chứng:
      • Độ chính xác của kết quả đầu ra
      • Việc gọi MCP có thành công hay không
      • Hành vi xử lý lỗi
      • Khả năng ứng phó với edge case
    • Không đánh giá chỉ bằng việc thành công hay thất bại đơn thuần, mà dựa trên tính hoàn chỉnh của toàn bộ workflow

  • 3. Kiểm thử so sánh hiệu năng

    • Mục tiêu: xác nhận hiệu quả cải thiện thực chất trước và sau khi dùng skill
    • Hạng mục so sánh:
      • Số lượt trao đổi tin nhắn qua lại
      • Việc gọi MCP có thất bại hay không
      • Tổng lượng token sử dụng
    • Skill không chỉ phải chứng minh là “hoạt động được”, mà còn phải chứng minh là “tốt hơn”

• Kiểm thử và cải tiến bằng skill-creator

  • skill-creator là công cụ meta hỗ trợ thiết kế và cải thiện skill
  • Các chức năng chính:
    • Tạo bản nháp skill dựa trên mô tả ngôn ngữ tự nhiên
    • Tự động tạo định dạng SKILL.md và frontmatter
    • Phát hiện rủi ro trigger quá nhiều hoặc quá ít
    • Đề xuất test case phù hợp với mục tiêu
  • Tuy vậy, nó không thay thế được kiểm thử thực thi hay đánh giá định lượng

• Cải tiến lặp lại dựa trên phản hồi

  • Skills không phải là sản phẩm đầu ra cố định mà là đối tượng cần được mài giũa liên tục

  • Dấu hiệu trigger thiếu

    • Skill không tự động được tải
    • Người dùng phải bật skill thủ công
    • Xuất hiện câu hỏi kiểu “cái này dùng khi nào?”
    • Giải pháp: thêm các cách diễn đạt và thuật ngữ cụ thể vào description

  • Dấu hiệu trigger quá mức

    • Skill được tải ngay cả với những câu hỏi không liên quan
    • Có trường hợp người dùng phải tắt skill
    • Gây ra sự nhầm lẫn về mục đích
    • Giải pháp: thu hẹp phạm vi, thêm trigger phủ định

  • Dấu hiệu vấn đề khi thực thi

    • Kết quả thiếu tính nhất quán
    • Xuất hiện lỗi MCP hoặc phải thử lại
    • Cần người dùng can thiệp để chỉnh sửa
    • Giải pháp: làm rõ hướng dẫn, tăng cường xử lý lỗi

• Thông điệp cốt lõi của giai đoạn kiểm thử

  • Kiểm thử là quá trình xác minh không chỉ độ chính xác mà còn cả độ tin cậy của skill
  • Tiêu chí “skill chạy được” là chưa đủ
  • Tiêu chí phán đoán cuối cùng là “liệu nó có hoàn thành đến cùng mà không cần người dùng đưa ra chỉ dẫn tiếp theo hay không”
• Chương 3 là giai đoạn chuyển Skills từ công cụ thử nghiệm thành tài sản workflow có thể vận hành

Chương 4: Phân phối và chia sẻ (Distribution and Sharing)

• Skills là yếu tố hoàn thiện giá trị của các connector MCP, và ngay cả với cùng một kết nối công cụ, việc đạt được giá trị nhanh hơn sẽ khả thi hơn khi đi kèm skill
• Từ góc nhìn người dùng, có xu hướng ưa chuộng connector bao gồm workflow có thể chạy ngay hơn là connector chỉ cung cấp MCP
• Chương này tóm tắt phương thức phân phối tính đến tháng 1 năm 2026, triển khai ở cấp tổ chức, cách tận dụng API và chiến lược vận hành được khuyến nghị

• Mô hình phân phối hiện tại (tính đến tháng 1 năm 2026)

  • Cách phân phối cho người dùng cá nhân

    • Tải thư mục Skill về máy cục bộ
    • Nếu cần, nén toàn bộ thư mục thành tệp zip
    • Tải lên trong Claude.ai theo đường dẫn Settings → Capabilities → Skills
    • Hoặc đặt trực tiếp vào thư mục skills trong môi trường Claude Code
    • Sau khi tải lên, người dùng phải tự kích hoạt skill

  • Phân phối ở cấp tổ chức

    • Quản trị viên có thể phân phối skill trên toàn bộ workspace
    • Tính năng phân phối ở cấp tổ chức được cung cấp từ ngày 18 tháng 12 năm 2025
    • Hỗ trợ quản lý tập trung và cập nhật tự động
    • Phù hợp để áp dụng bắt buộc hoặc duy trì nhất quán các workflow tiêu chuẩn trong tổ chức

• Skills như một tiêu chuẩn mở

  • Agent Skills được công bố là tiêu chuẩn mở giống như MCP
  • Mục tiêu là cùng một skill có thể hoạt động trên nhiều công cụ AI mà không bị phụ thuộc vào một nền tảng cụ thể
  • Một số skill có thể tận dụng mạnh các tính năng đặc thù của nền tảng; trong trường hợp đó có thể ghi rõ ràng buộc môi trường trong trường compatibility
  • Tiêu chuẩn đang tiếp tục được phát triển thông qua hợp tác với các bên tham gia trong hệ sinh thái

• Sử dụng Skills thông qua API

  • Mục đích sử dụng API

    • Phù hợp với các kịch bản sử dụng theo chương trình như ứng dụng, pipeline tự động hóa, hệ thống agent
    • Có thể điều khiển skill ở cấp hệ thống thay vì sử dụng thủ công qua UI

  • Các tính năng chính

    • Truy vấn và quản lý danh sách skill thông qua endpoint /v1/skills
    • Chỉ định skill bằng tham số container.skills khi gửi yêu cầu Messages API
    • Quản lý phiên bản và kiểm soát phân phối thông qua Claude Console
    • Có thể cấu hình agent tùy biến bằng cách tích hợp với Claude Agent SDK

  • Hướng dẫn chọn môi trường sử dụng

    • Claude.ai / Claude Code:
      • Người dùng cuối sử dụng trực tiếp
      • Kiểm thử thủ công trong quá trình phát triển và lặp lại nhanh
      • Workflow cá nhân, không diễn ra thường xuyên
    • API:
      • Tích hợp vào ứng dụng
      • Triển khai production quy mô lớn
      • Agent và pipeline tự động hóa

  • Lưu ý

    • Khi sử dụng Skills dựa trên API, cần Code Execution Tool beta
    • Giả định có môi trường thực thi được bảo mật

• Chiến lược phân phối được khuyến nghị

  • 1. Vận hành kho lưu trữ công khai trên GitHub

    • Bản thân skill được quản lý như một thư mục duy nhất
    • Ở thư mục gốc của kho lưu trữ, cung cấp README dành cho con người
    • Khuyến nghị bao gồm cách cài đặt, mục đích sử dụng và ảnh chụp màn hình ví dụ
    • Không đưa README.md vào bên trong thư mục Skill

  • 2. Liên kết với tài liệu MCP

    • Giới thiệu Skill cùng với tài liệu connector MCP
    • Giải thích rõ giá trị khi kết hợp Skill so với việc chỉ dùng MCP
    • Cung cấp hướng dẫn bắt đầu nhanh

  • 3. Cung cấp hướng dẫn cài đặt

    • Nêu rõ cách tải skill
    • Hướng dẫn từng bước để cài đặt vào Claude.ai hoặc Claude Code
    • Bao gồm quy trình xác nhận kết nối máy chủ MCP
    • Cung cấp ví dụ prompt kiểm thử đơn giản

• Nguyên tắc định vị skill

  • Giải thích theo kết quả thay vì tính năng

    • Thay vì mô tả cách triển khai nội bộ hay cấu trúc kỹ thuật, hãy nhấn mạnh kết quả người dùng nhận được
    • Đặt các hiệu quả như tiết kiệm thời gian, giảm lỗi, đảm bảo tính nhất quán lên hàng đầu

  • Sự kết hợp MCP + Skills là quan trọng

    • MCP cung cấp quyền truy cập công cụ
    • Skills cung cấp kiến thức về cách nên sử dụng công cụ đó
    • Khi hai yếu tố này kết hợp, tự động hóa dựa trên AI mới được hoàn thiện
• Phân phối và chia sẻ không chỉ là chuyển giao đơn thuần, mà là quá trình giúp người dùng hiểu được giá trị của skill và có thể tận dụng ngay lập tức

Chương 5: Mẫu và khắc phục sự cố (Patterns and Troubleshooting)

• Chương này tổng hợp các mẫu thiết kế đã nhiều lần chứng minh hiệu quả từ những người dùng Skills giai đoạn đầu và các trường hợp nội bộ, cùng với cách khắc phục các sự cố thường gặp trong quá trình vận hành thực tế
• Các mẫu được đưa ra không phải là quy phạm, mà là một tập hợp các cách tiếp cận đã được kiểm chứng, với tiền đề là lựa chọn và kết hợp chúng sao cho phù hợp với mục tiêu của từng skill
• Thông điệp cốt lõi không nằm ở “kết nối công cụ”, mà ở thiết kế luồng giải quyết vấn đề

• Lựa chọn cách tiếp cận: lấy vấn đề làm trung tâm vs lấy công cụ làm trung tâm

  • Trong thiết kế Skills, điều quan trọng là chọn một trong hai góc nhìn

  • Lấy vấn đề làm trung tâm (Problem-first)

    • Người dùng nói về kết quả họ muốn đạt được
    • Skill sẽ tự quyết định công cụ MCP phù hợp và thứ tự gọi ở bên trong
    • Ví dụ: “Hãy tạo workspace dự án cho tôi” → skill xử lý toàn bộ các lệnh gọi công cụ
    • Phù hợp với trải nghiệm hướng tới kết quả

  • Lấy công cụ làm trung tâm (Tool-first)

    • Người dùng đã biết về kết nối MCP
    • Skill cung cấp kiến thức chuyên môn về cách sử dụng tốt công cụ đó
    • Ví dụ: cách dùng Notion MCP, hướng dẫn workflow tối ưu
    • Phù hợp với người dùng chuyên gia và hướng dẫn công cụ nội bộ
• Phần lớn skill sẽ nghiêng về một trong hai hướng này nhiều hơn, và việc nhận thức rõ điều đó có ảnh hưởng quyết định đến chất lượng thiết kế

• Mẫu 1: Điều phối workflow tuần tự

  • Phù hợp khi bắt buộc phải thực hiện nhiều bước theo một thứ tự cố định
  • Mỗi bước phụ thuộc vào kết quả của bước trước
  • Có thể bao gồm xác minh theo từng bước và hướng dẫn rollback khi thất bại
  • Phù hợp với các tác vụ như onboarding, tạo tài khoản, thiết lập gói đăng ký

• Mẫu 2: Phối hợp nhiều MCP

  • Dùng khi cần sử dụng liên tiếp nhiều dịch vụ (MCP) để tạo ra một kết quả
  • Tách MCP theo từng bước và xác định rõ luồng truyền dữ liệu
  • Bắt buộc phải xác minh trước khi chuyển sang bước tiếp theo
  • Phù hợp với các workflow phức hợp như thiết kế → lưu trữ → tạo task → thông báo

• Mẫu 3: Cải tiến lặp lại (Iterative Refinement)

  • Phù hợp với những tác vụ mà chất lượng được cải thiện đáng kể thông qua lặp lại hơn là chỉ với kết quả ban đầu
  • Thiết kế rõ ràng vòng lặp tạo bản nháp → xác minh → chỉnh sửa → tái xác minh
  • Cần định nghĩa rõ tiêu chí chất lượng và điều kiện kết thúc vòng lặp
  • Hiệu quả cho việc tạo báo cáo và cải thiện chất lượng tài liệu

• Mẫu 4: Chọn công cụ dựa trên nhận thức ngữ cảnh

  • Dùng khi công cụ tối ưu thay đổi theo tình huống dù mục tiêu là như nhau
  • Cần có tiêu chí đánh giá rõ ràng như kích thước tệp, loại tệp, có cộng tác hay không
  • Giải thích lý do lựa chọn cho người dùng để đảm bảo độ tin cậy
  • Phù hợp với lưu trữ, quản lý tài liệu và luồng lưu trữ mã nguồn

• Mẫu 5: Tích hợp trí tuệ chuyên biệt theo miền

  • Skill không chỉ gọi công cụ đơn thuần mà còn nội tại hóa kiến thức chuyên môn và quy tắc
  • Bước đánh giá và xác minh trước khi thực hiện tác vụ là cốt lõi
  • Ghi lại toàn bộ quá trình ra quyết định để có thể audit trail
  • Phù hợp với các lĩnh vực rủi ro cao như tài chính, compliance, bảo mật

• Hướng dẫn khắc phục sự cố

  • Tải lên thất bại

    • Xảy ra khi tên tệp SKILL.md không chính xác
    • Nguyên nhân có thể là lỗi định dạng như thiếu dấu phân tách YAML (---), chưa đóng dấu ngoặc kép
    • Nếu trường name chứa chữ in hoa hoặc khoảng trắng thì việc tải lên sẽ bị từ chối

  • Khi skill không được kích hoạt

    • Do description quá trừu tượng hoặc không phản ánh cách diễn đạt của người dùng
    • Cần chỉnh sửa để bao gồm những cụm từ mà người dùng thực sự có thể nói
    • Có thể debug bằng cách hỏi Claude “skill này được dùng khi nào”

  • Khi skill bị kích hoạt quá mức

    • Nguyên nhân là description có phạm vi quá rộng
    • Thêm trigger phủ định (Do NOT use when…)
    • Phân biệt rõ đối tượng cần xử lý và đối tượng bị loại trừ

  • Thất bại khi gọi MCP

    • Kiểm tra trạng thái kết nối của máy chủ MCP
    • Kiểm tra thông tin xác thực (API key, OAuth token)
    • Tách nguyên nhân sự cố bằng cách gọi riêng MCP mà không dùng skill
    • Xác nhận chính xác chữ hoa chữ thường trong tên công cụ

  • Khi chỉ dẫn không được tuân thủ tốt

    • Do chỉ dẫn quá dài dòng hoặc điểm chính bị chìm đi
    • Đặt các điều kiện quan trọng lên đầu và nhấn mạnh lặp lại
    • Dùng danh sách điều kiện có thể kiểm chứng thay vì cách diễn đạt mơ hồ
    • Với các bước xác minh quan trọng, triển khai bằng script sẽ ổn định hơn

  • Suy giảm hiệu năng do ngữ cảnh quá lớn

    • Xảy ra khi SKILL.md quá lớn
    • Tách tài liệu chi tiết sang references
    • Nếu số lượng skill được kích hoạt đồng thời quá nhiều thì nên giảm bớt
    • Việc kích hoạt đồng thời từ 20~50 skill trở lên có thể gây suy giảm hiệu năng
• “Skill không phải là một artefact tạo ra một lần rồi xong, mà là đối tượng vận hành trưởng thành dần thông qua việc chọn mẫu và cải tiến lặp lại”

[kaydash]

Anthropic đúng là đỉnh thật.

[pluto]

thật sự