Hướng dẫn chính thức về Kỹ năng Agent của Anthropic: Ghi chú toàn diện cho khóa học 6 bài

Anthropic cuối cùng cũng đã phát hành một video hướng dẫn chính thức về Agent Skills, bao gồm 6 bài học với tổng thời lượng 22 phút. Video bao quát toàn bộ vòng đời của Skills, từ khái niệm cơ bản đến cách tạo, cấu hình đa tệp, phân biệt với các tính năng khác, chia sẻ và khắc phục sự cố.

Giá trị lớn nhất của hướng dẫn này không chỉ là dạy bạn cách viết một Skill, mà còn giải thích triết lý thiết kế và cơ chế hoạt động cốt lõi của Skills. Nhiều vấn đề mà mọi người gặp phải khi sử dụng Skills bắt nguồn từ việc hiểu chưa đầy đủ về các cơ chế này.

Skills Giải Quyết Vấn Đề Gì?

Mỗi lần bạn giải thích các tiêu chuẩn code của nhóm mình cho Claude, bạn đang lặp lại chính mình. Mỗi lần review PR, bạn phải mô tả lại cách bạn muốn phản hồi được sắp xếp. Mỗi lần viết commit message, bạn phải nhắc Claude về định dạng ưa thích của mình.

Skills được thiết kế để loại bỏ sự lặp lại này. Một Skill là một tệp Markdown dạy Claude cách làm một việc gì đó một lần, và Claude sẽ tự động áp dụng kiến thức đó trong các tình huống liên quan.

Chính xác hơn, một Agent Skill là một thư mục chứa các hướng dẫn, tập lệnh và tài nguyên. Claude có thể tự động khám phá và sử dụng chúng để hoàn thành công việc một cách chính xác và hiệu quả hơn.

Cơ chế cốt lõi là trường description. Khi Claude khởi động, nó tải tên và mô tả của tất cả Skills. Khi bạn đưa ra yêu cầu, Claude thực hiện so khớp ngữ nghĩa giữa yêu cầu của bạn và mô tả của tất cả Skills có sẵn để tìm và kích hoạt Skill phù hợp. Chỉ khi được kích hoạt, toàn bộ nội dung Skill mới được tải vào cửa sổ ngữ cảnh.

Điều này về cơ bản khác với claude.md. Nội dung của claude.md được tải trong mọi cuộc trò chuyện, bất kể bạn đang làm gì. Một Skill chỉ được tải khi cần thiết; danh sách kiểm tra PR của bạn không cần phải có trong ngữ cảnh khi đang gỡ lỗi, nó chỉ xuất hiện khi bạn thực sự yêu cầu review.

Khi nào bạn nên sử dụng một Skill? Nếu bạn thấy mình liên tục giải thích cùng một điều cho Claude, đó là một Skill đang chờ được phát triển.

Tạo Skill Đầu Tiên Từ Đầu

Tạo một Skill chỉ cần hai bước: tạo một thư mục và viết một tệp.

Bước một: Tạo một thư mục đặt theo tên Skill bên trong ~/.claude/skills/. Đặt ở đây có nghĩa đây là Skill cấp cá nhân, có sẵn trên tất cả các dự án.

Bước hai: Tạo một tệp SKILL.md trong thư mục đó. Tệp được chia làm hai phần, ngăn cách bởi ba dấu gạch ngang. Phần trên cùng là siêu dữ liệu YAML chứa name và description. Phần dưới cùng chứa các hướng dẫn cụ thể để Claude làm theo.

Khi Claude Code khởi động, nó quét bốn vị trí để tìm Skills: đường dẫn doanh nghiệp, thư mục Skills cá nhân, thư mục Skills dự án và các plugin đã cài đặt. Nó chỉ tải tên và mô tả của mỗi Skill, không phải toàn bộ nội dung.

Khi bạn gửi một yêu cầu, Claude so sánh yêu cầu với tất cả các mô tả Skill. Nếu ý định khớp, nó sẽ trước tiên hỏi bạn xác nhận có muốn tải Skill hay không. Chỉ sau khi xác nhận, nó mới đọc toàn bộ tệp và thực thi các hướng dẫn. Bước xác nhận này giúp bạn luôn biết Claude đang sử dụng ngữ cảnh nào.

Nếu tồn tại các Skills trùng tên, thứ tự ưu tiên từ cao đến thấp là: Cấp doanh nghiệp (managed-settings.json), Cấp cá nhân (~/.claude/skills), Cấp dự án (project/.claude/skills) và Cấp plugin (project/.claude-plugins/skills).

Điều này có nghĩa là một công ty có thể thực thi các tiêu chuẩn thông qua Skills cấp doanh nghiệp, đồng thời cho phép cá nhân tùy chỉnh thông qua các Skills có tên khác. Nếu công ty bạn có một Skill review mã nguồn cấp doanh nghiệp, bạn có thể tạo một Skill cá nhân tên là front-end-pr-review để bổ sung thay vì ghi đè lên nó.

Cấu Hình Nâng Cao: Trường Siêu Dữ Liệu và Tiết Lộ Dần Dần

Skills cơ bản chỉ cần name và description, nhưng một số cấu hình nâng cao có thể làm cho Skills mạnh mẽ hơn.

Trường allowed-tools có thể giới hạn các công cụ Claude được phép sử dụng khi Skill đang hoạt động. Ví dụ: nếu bạn có một Skill phân tích chỉ đọc, bạn có thể cấm các lệnh chỉnh sửa, viết và Bash. Nếu trường này bị bỏ qua, Skill không áp đặt hạn chế nào và Claude sử dụng mô hình quyền bình thường.

Trường model có thể chỉ định phiên bản mô hình Claude nào sẽ được sử dụng.

Cách viết description quyết định trực tiếp liệu một Skill có thể được kích hoạt chính xác hay không. Một mô tả tốt nên trả lời hai câu hỏi: Skill này làm gì? Khi nào Claude nên sử dụng nó? Nếu một Skill không kích hoạt, hãy thêm các từ khóa phù hợp với cách diễn đạt trong yêu cầu của bạn.

Khái niệm nâng cao quan trọng nhất là tiết lộ dần dần. Skills chia sẻ cửa sổ ngữ cảnh với cuộc trò chuyện của bạn. Nếu bạn nhồi nhét mọi thứ vào một tệp SKILL.md dài 20.000 dòng, nó sẽ tiêu tốn một lượng lớn không gian ngữ cảnh.

Cách tiếp cận đúng là: đặt các hướng dẫn thiết yếu trong SKILL.md và các tài liệu tham khảo chi tiết trong các tệp riêng biệt, Claude sẽ chỉ đọc chúng khi cần. Cấu trúc thư mục được khuyến nghị cho các tiêu chuẩn mở là: thư mục scripts cho mã thực thi, references cho tài liệu tham khảo và resources cho các tệp dữ liệu như hình ảnh và mẫu. Sử dụng các liên kết trong SKILL.md để tham chiếu đến các tệp này.

Quy tắc chính: SKILL.md không được vượt quá 500 dòng. Nếu vượt quá, nó nên được chia nhỏ. Các tập lệnh có thể được thực thi trực tiếp mà không cần tải nội dung của chúng vào ngữ cảnh; chỉ đầu ra mới tiêu tốn token. Vì vậy, hãy bảo Claude chạy tập lệnh thay vì đọc nó. Điều này đặc biệt hữu ích cho việc xác thực môi trường và chuyển đổi dữ liệu, vì mã tập lệnh đã được kiểm thử đáng tin cậy hơn so với việc tạo mã ngay lập tức.

Sự Khác Biệt Giữa Skills và Các Tính Năng Khác Của Claude Code

Skills vs. claude.md: claude.md luôn được tải vào mọi cuộc trò chuyện cho các tiêu chuẩn và quy tắc dự án luôn được áp dụng, chẳng hạn như "Dự án này sử dụng chế độ nghiêm ngặt của TypeScript." Skills được tải theo yêu cầu, chỉ được kích hoạt khi Claude khớp với một yêu cầu.

Skills vs. Sub Agents: Skills thêm kiến thức vào cuộc trò chuyện hiện tại; khi được kích hoạt, các hướng dẫn được thêm vào ngữ cảnh hiện có. Sub Agents chạy trong một ngữ cảnh độc lập, hoàn thành nhiệm vụ và gửi kết quả riêng biệt, hoàn toàn cách ly với cuộc trò chuyện chính.

Skills vs. Hooks: Hooks được điều khiển bởi sự kiện, kích hoạt khi các sự kiện cụ thể xảy ra, chẳng hạn như Claude chạy một trình Linter mỗi khi một tệp được lưu. Skills được điều khiển bởi yêu cầu, kích hoạt dựa trên các câu hỏi bạn đặt ra.

Skills vs. MCP: MCP cung cấp các kết nối công cụ bên ngoài, cho phép Claude gọi các dịch vụ như Gmail hoặc Notion. Skills cung cấp kiến thức và quy trình làm việc, hướng dẫn Claude cách sử dụng các công cụ đó để hoàn thành các nhiệm vụ cụ thể.

Tóm tắt trong một câu: claude.md chứa các hướng dẫn luôn bật, Skills chứa kiến thức chuyên môn tự động so khớp, Sub Agents chạy các tác vụ được ủy quyền trong các ngữ cảnh biệt lập, Hooks phản hồi các sự kiện và MCP kết nối với các công cụ bên ngoài. Chúng có thể được sử dụng kết hợp.

Chia Sẻ Skills: Từ Cá Nhân Đến Nhóm Đến Tổ Chức

Giá trị của Skills nằm ở việc chia sẻ. Một Skill review PR chỉ bạn tự dùng thì hữu ích, nhưng một Skill được cả nhóm chia sẻ có thể chuẩn hóa việc review code và mang lại trải nghiệm nhất quán.

Ba cách để chia sẻ:

Đầu tiên là thư mục dự án. Cam kết (commit) Skill vào thư mục .claude/skills của kho mã nguồn. Bất kỳ ai clone kho đều tự động nhận được các Skills này mà không cần cài đặt thêm. Các bản cập nhật sẽ được nhận trong lần kéo (pull) tiếp theo. Cách này phù hợp cho các tiêu chuẩn code của nhóm và quy trình làm việc cụ thể của dự án.

Thứ hai là plugin. Hãy nghĩ về plugin như một cách để phân phối Skills trên nhiều dự án. Sau khi được tải lên một cửa hàng ứng dụng, những người dùng khác có thể tải xuống và cài đặt chúng. Nếu Skill của bạn mang tính tổng quát và không dành riêng cho một dự án nào, đây là lựa chọn tốt nhất cho các thành viên trong cộng đồng.

Thứ ba là triển khai doanh nghiệp. Quản trị viên đẩy (push) Skills đến toàn bộ tổ chức thông qua các cài đặt được quản lý. Skills cấp doanh nghiệp có mức ưu tiên cao nhất và sẽ ghi đè lên Skills cá nhân và dự án có cùng tên. Điều này được sử dụng cho các tiêu chuẩn bắt buộc, yêu cầu bảo mật và quy trình tuân thủ.

Một lưu ý quan trọng: Sub Agents không tự động kế thừa Skills của bạn. Khi bạn ủy quyền một nhiệm vụ cho một sub-agent, nó sẽ bắt đầu với một ngữ cảnh mới. Các agent tích hợp sẵn (Explorer, Plan, Verify) hoàn toàn không thể truy cập Skills; chỉ các sub-agent tùy chỉnh do bạn định nghĩa mới có thể sử dụng chúng và chúng phải được liệt kê rõ ràng trong agent.md.

Để tạo một sub-agent tùy chỉnh với Skills, hãy tạo một tệp agent.md trong thư mục .claude/agents và thêm trường skills liệt kê các tên Skill cần thiết. Chỉ liệt kê các Skills luôn liên quan đến mục tiêu của sub-agent, vì các Skills này sẽ được tải khi sub-agent khởi động.

Hướng Dẫn Khắc Phục Sự Cố: Sáu Lý Do Khiến Skills Thất Bại và Giải Pháp

Các vấn đề về Skill thường rơi vào sáu loại:

1. Skill không kích hoạt: Nguyên nhân hầu như luôn là do description được viết kém. Claude sử dụng so khớp ngữ nghĩa; yêu cầu của bạn cần phải phù hợp với ý nghĩa của mô tả. Nếu không có đủ sự trùng lặp, nó sẽ không khớp. Giải pháp: So sánh mô tả với cách diễn đạt yêu cầu của bạn và thêm các cụm từ kích hoạt mà người dùng thực sự nói, như "giúp tôi phân tích," "tại sao cái này chậm," hoặc "tăng tốc nó lên."

1. Skill không tải được: Kiểm tra đường dẫn và tên tệp. SKILL.md phải nằm bên trong một thư mục đã đặt tên, không được nằm trực tiếp trong thư mục gốc skills. Tên tệp phải chính xác là SKILL.md viết hoa toàn bộ. Chạy claude --debug để xem lỗi tải.

1. Claude sử dụng sai Skill: Điều này có nghĩa là bạn có nhiều Skills với mô tả quá giống nhau, khiến Claude không thể phân biệt chúng. Giải pháp: Làm cho mỗi mô tả cụ thể nhất có thể để giúp Claude quyết định khi nào nên sử dụng cái nào.

1. Skill cá nhân bị bỏ qua: Một Skill có mức ưu tiên cao hơn (ví dụ: cấp doanh nghiệp) có cùng tên có thể đang ghi đè lên nó. Hãy kiểm tra bốn cấp độ ưu tiên. Giải pháp: Đổi tên Skill của bạn thành một cái gì đó độc đáo hơn.

1. Plugin đã cài đặt nhưng Skill không hiển thị: Xóa bộ nhớ đệm bằng rm ~/.claude/plugins/cache, khởi động lại Claude Code và cài đặt lại. Nếu vẫn không hoạt động, cấu trúc thư mục của plugin có thể bị sai; sử dụng công cụ xác thực skills-ref validate để kiểm tra.

1. Skill đã tải nhưng thất bại trong quá trình thực thi: Nếu Skill sử dụng các gói bên ngoài, hãy đảm bảo chúng đã được cài đặt. Thêm thông tin về phụ thuộc vào mô tả của Skill.

Anthropic cũng cung cấp một công cụ xác thực có tên skills-ref để kiểm tra xem cấu trúc tệp và cú pháp YAML của Skill có chính xác hay không. Nên cài đặt nó qua uv để có phương pháp nhanh nhất.