Skills: cách trang bị cho agent một kỹ năng có sẵn

Có một yêu cầu mà bạn cứ lặp đi lặp lại: xem các thay đổi, kiểm tra mấy file này, trình bày theo cách này, còn chỗ kia thì đừng động vào. Lần nào bạn cũng giải thích lại quy trình từ đầu, và mỗi lần lại hơi khác một chút.

Kết quả thay đổi theo cách diễn đạt. Hôm nay ra rất tốt, ngày mai bạn quên một nửa điều kiện, và agent làm đúng y những gì nó nghe được.

Cách chữa không nằm ở bộ nhớ của agent, mà ở một thư mục chứa hướng dẫn. Skill là một quy trình được ghi lại một lần, Claude Code có thể tự dùng đến nó hoặc dùng theo lệnh của bạn. Chúng ta sẽ xem thư mục này nằm ở đâu, làm sao chắc chắn rằng skill đã được cài đúng, và cần kiểm tra gì trước lần chạy đầu tiên.

Skill là gì

Trước khi đi vào các file và các trường, hãy nắm lấy hình dung trực quan đã.

Hãy tưởng tượng một người thợ mộc. Anh ấy đã một lần ghi lại trình tự làm việc quen thuộc của mình, chuẩn bị sẵn các ghi chú, mẫu và chương trình cho máy. Giờ chỉ cần nói ngắn gọn: "dọn hết đi, mài mũi khoan, tiếp theo là chiếc ghế cho mèo - chạy mẫu CNC". Bấm chạy - và bắt tay vào việc.

Quy trình đã ghi lại giữ cho toàn bộ công việc gắn kết với nhau:

• Dọn dẹp theo quy tắc của bạn. Dọn bàn làm việc, xếp dụng cụ - lần nào cũng như nhau, đúng như bạn đã quen.
• Tuân theo những giới hạn đã ghi lại. Lưỡi cưa còn đang quay - không thò tay vào. Phần việc an toàn thì làm ngay, không hỏi han thừa.
• Xem ghi chú khi cần. Cần mài mũi khoan - mở quy tắc mài ra. Không nhớ sẵn trong đầu, cần đến đâu lấy ra đến đó.
• Giữ sẵn mẫu cho từng loại việc. Chuyển từ bàn sang ghế - lấy ngay sơ đồ chuẩn bị có sẵn.
• Chạy việc phức tạp bằng một lệnh. Chương trình cho các đường cắt lặp lại đã nằm sẵn bên cạnh. Chỉ cần nói: "tìm mẫu Ghế cho mèo và chạy trên CNC" - máy sẽ giữ đúng khe hở và thứ tự các thao tác.

Skill cũng được tổ chức như vậy. Nó không phải là thêm một công cụ trong tay agent, mà là một quy trình đã được đóng gói. Hướng dẫn chính giữ trình tự và giới hạn, tài liệu tham khảo cung cấp chi tiết khi cần, các mẫu giữ sẵn phần khung, còn các script chạy phần việc máy móc lặp đi lặp lại. Mô tả một lần - sau đó chỉ việc gọi.

Bản thân định dạng skill không cô lập thứ gì cả. Hướng dẫn có thể giới hạn công việc trong phần giao diện, nhưng giữa CSS và logic không có bức tường kỹ thuật nào. Một skill tốt nêu rõ phạm vi làm việc; sau khi chạy, bạn xem các file đã thay đổi và kiểm tra trang hoạt động ra sao. "Chạy được" và "trông đẹp" là hai lớp khác nhau, và thứ đảm bảo là việc kiểm tra, chứ không phải định dạng.

Skill nằm ở đâu

Chẳng có phép màu nào trên đám mây ở đây cả. Skill là một thư mục trên ổ đĩa, ngay trong project của bạn:

.claude/skills/web-design/SKILL.md

Đọc đường dẫn theo từng đoạn: thư mục hệ thống .claude, bên trong là skills, bên trong nữa là thư mục của chính skill đó (tên do bạn đặt), và trong đó là file SKILL.md. Một file văn bản bình thường, mở bằng gì cũng được.

Với skill trong project và trong thư mục home, tên thư mục trở thành tên lệnh có dấu gạch chéo, trừ khi chính file đặt một tên khác (sẽ nói rõ ở phần dưới). Vì vậy hãy đặt tên ngay từ đầu, nghĩ trước xem nó sẽ trông thế nào trong khung chat.

Giờ là một điều chỉnh cho hình dung phổ biến nhất: skill không phải là một file, mà là một thư mục. Bên cạnh SKILL.md có thể đặt bất cứ thứ gì.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # file chính: mô tả và hướng dẫn
        ├── palettes.md   # tài liệu tham khảo, agent sẽ mở nếu cần
        └── scripts/
            └── check.py  # script có thể chạy

Để tự động chọn skill, agent chỉ thấy tên và mô tả ngắn của nó, không phải toàn bộ phần nội dung. SKILL.md được nạp khi skill chạy, các tài liệu tham khảo bên cạnh - khi cần. Nhờ vậy, một bản ghi chú dài không chiếm context từ trước.

Khi làm việc cục bộ thông thường, có ba nguồn skill đáng quan tâm:

Ký hiệu ~ nghĩa là thư mục home của người dùng. Trong lệnh thì cứ giữ nguyên nó; còn nếu mở thư mục bằng tay, hãy vào thư mục home của bạn.

Khác biệt giữa hai nơi đầu tiên rất đơn giản, và nên nắm ngay từ bây giờ.

Đặt thư mục vào project - skill chỉ hoạt động trong project đó. Mở project bên cạnh là không còn thấy nó nữa.

Skill trong thư mục home có mặt ở mọi project. Tiện cho những quy trình dùng chung, nhưng nó có thể bật lên ở chỗ bạn không ngờ tới. Thứ dùng chung thì để ở home, thứ riêng của project thì để trong project.

Nếu Claude Code chạy với profile học tập riêng ~/.claude-codegym/, các skill cá nhân nằm trong thư mục skills/ của profile đó. Đường dẫn project .claude/skills/ không đổi theo profile.

Description quyết định khi nào skill được dùng

Chuyện hay gặp: thư mục đã đặt, file nằm đúng chỗ, vậy mà agent vẫn làm y như trước. Không có gì hỏng cả - chỉ là nó không hiểu rằng skill này hợp với tình huống.

Hãy xem agent có gì trong tay vào lúc chọn. Nó chưa đọc phần nội dung của skill: chỉ có danh sách tên và mô tả được nạp. Nghĩa là quyết định dựa vào mô tả, ngoài ra không còn gì khác.

Hãy dựng một skill tối thiểu cho project từ đầu đến cuối. Tên của nó là web-design - đó là tên thư mục, và lệnh /web-design cũng lấy tên từ đây. Ở đây chúng ta không ghi tên trong file, thư mục đã quy định rồi:

.claude/skills/web-design/SKILL.md

Còn bên trong là thế này, không cần thêm gì nữa:

---
description: Chỉnh giao diện web cho gọn gàng - CSS hiện đại, chuyển động mượt,
  bảng màu hài hòa. Dùng khi được yêu cầu làm cho đẹp hoặc có phong cách.
---

# Thiết kế web

Dùng bóng đổ mềm, chuyển động mượt và typography được chăm chút.
Giữ bảng màu hài hòa, animation - khi di chuột và khi phần tử xuất hiện.

Ở trên, giữa hai cặp ba dấu gạch ngang, là khối thông tin hệ thống, bên dưới là văn bản hướng dẫn bình thường. Không có trường nào bắt buộc, nhưng description thì lúc nào cũng nên viết: thiếu nó, agent phải đoán công dụng của skill từ đoạn đầu tiên của phần nội dung, mà như vậy thì chẳng khác gì xổ số.

Một mô tả tốt trả lời hai câu hỏi: skill làm gì và khi nào nên dùng nó. Và dùng đúng những từ mà bạn thực sự hay viết trong yêu cầu.

# im lặng: không rõ khi nào nên dùng
description: Hỗ trợ trình bày giao diện

# được dùng: nói rõ cả làm gì lẫn khi nào
description: Chỉnh giao diện cho gọn gàng - CSS, typography, bảng màu.
  Dùng khi được yêu cầu làm cho đẹp, có phong cách hoặc sửa layout.

Mô tả quyết định khi nào skill tự bật lên. Nhưng đó không phải lối vào duy nhất: skill có tên, và có thể gọi nó bằng tay theo tên đó. Gõ /web-design - lúc này mô tả chẳng còn liên quan gì, file được đọc và thực hiện.

Trong các skill có sẵn thường gặp trường name. Với skill trong project và trong thư mục home, trường này quy định lệnh mà menu / hiển thị: skill nằm trong thư mục deploy-staging và có name: deploy sẽ được gọi bằng /deploy. Tên thư mục vẫn dùng được như cũ. Trong plugin, name có thể quy định phần cuối của lệnh, đứng sau tên plugin.

Vậy là có hai cách khởi chạy, còn mọi thứ sau đó đều giống nhau.

Nhánh bên trái là tự động: yêu cầu khớp với mô tả, agent chọn skill. Nhánh bên phải là thủ công: gõ /web-design, và skill chạy bất kể mô tả viết gì.

Skill xuất hiện trong cùng menu / với các lệnh có sẵn. File .claude/commands/deploy.md và skill .claude/skills/deploy/SKILL.md tạo ra cùng một lệnh /deploy; nếu có cả hai, skill được ưu tiên.

Cài đặt và kiểm tra

Thư mục đã đặt vào. Làm sao biết agent thực sự thấy nó, chứ không phải file chỉ nằm im trên ổ đĩa?

/skills

Lệnh này mở danh sách skill và cho biết nguồn của từng skill. Gõ vài chữ cái - danh sách sẽ được lọc. Thấy tên thư mục của mình với trạng thái on - nghĩa là Claude Code thấy skill và cho phép chạy nó.

Tên, nguồn và trạng thái on xác nhận rằng skill đã sẵn sàng

Thông thường Claude Code nhận ra file SKILL.md mới hoặc vừa sửa ngay lập tức. Nếu không thấy tên trong danh sách, hãy thử lần lượt:

Skill có trong danh sách nhưng không tự bật lên? Tải lại không giải quyết được chuyện này. Hãy kiểm tra description và trường disable-model-invocation: true - trường này chỉ cho phép gọi bằng tay. Diễn đạt lại yêu cầu hoặc gọi skill theo tên. Gọi bằng tay mà chạy - nghĩa là cài đặt không có vấn đề gì.

Cần kiểm tra gì trước khi tin dùng

Đến đây phải bớt hào hứng một chút. Skill không phải là một theme giao diện hay một bức ảnh, cứ gắn vào rồi gỡ ra. Đó là những chỉ dẫn mà agent của bạn sẽ thực hiện trong project của bạn.

Cần kiểm tra không chỉ file chính mà cả thư mục. Hãy bắt đầu với bốn thứ:

• mô tả - có khớp với điều bạn mong đợi ở skill không, và có bị kích hoạt quá rộng không;
• phần nội dung và các liên kết trong đó - skill bảo làm gì và yêu cầu mở những file nào bên cạnh;
• thư mục scripts/, nếu có, - ở đó chạy những lệnh gì, chúng động đến file nào và địa chỉ mạng nào;
• trường allowed-tools - skill cho phép trước những công cụ nào được dùng mà không cần hỏi riêng.

---
name: pre-commit-style
description: Đưa project về style chung trước khi commit
allowed-tools: Read, Write, Edit, Glob
---

Ở đây allowed-tools không mô tả kế hoạch làm việc và cũng không giới hạn toàn bộ khả năng của agent. Trường này chỉ phê duyệt trước các công cụ được liệt kê trong lượt mà skill được gọi. Các tên thì dễ hiểu:

• Read - đọc file;
• Write - tạo file mới và ghi đè toàn bộ file đã có;
• Edit - sửa bên trong một file đã có;
• Glob - tìm file theo mẫu, tức là đi khắp project và xem trong đó có gì.

Công cụ đầu và cuối chỉ để xem. Write và Edit có thể thay đổi file: nếu hướng dẫn dẫn đến thao tác như vậy, trong lượt này có thể sẽ không có câu hỏi xác nhận riêng. Nhưng có quyền không có nghĩa là agent nhất định sẽ dùng nó. Các quy tắc quyền truy cập chung của project vẫn tiếp tục có hiệu lực.

Bản thân trường này không có gì xấu: nó bỏ bớt những lần xác nhận thừa ở đúng chỗ bạn muốn. Nhưng danh sách công cụ là do tác giả skill chọn, nên đáng xem qua trước lần chạy đầu tiên.

Và điều cuối cùng, ít đáng sợ hơn nhưng gặp thường xuyên hơn nhiều. Skill định hướng cho agent, chứ không đảm bảo kết quả. Sau khi chạy, hãy xem các file đã thay đổi và kiểm tra kết quả: một skill về giao diện có thể làm trang đẹp hơn, nhưng chẳng ai thay nó xác nhận rằng nút bấm vẫn hoạt động.

Tìm skill có sẵn ở đâu

Để thử thì hoàn toàn không cần viết SKILL.md từ đầu. Thường thì skill có sẵn được tìm thấy trong các repository mở hoặc đi kèm với plugin.

Cách nhanh nhất là nhờ agent tìm một phương án phù hợp, nhưng đừng cài mù. Có thể viết như thế này:

Tìm một skill để thiết kế giao diện. Cho tôi xem nguồn, SKILL.md và các script,
giải thích nó dùng những file và công cụ nào. Đừng cài đặt gì
cho đến khi tôi xác nhận.

Đã xem nguồn và nội dung rồi - lúc đó mới nhờ đặt thư mục vào .claude/skills/ của project và kiểm tra kết quả bằng /skills.

Nếu muốn tự tìm, hãy dùng truy vấn Claude skills marketplace. Danh mục giúp tìm ra các phương án, nhưng không phải là dấu hiệu an toàn: nội dung vẫn phải được đọc trước khi cài.

SKILL.md tuân theo tiêu chuẩn mở Agent Skills, nên cấu trúc cơ bản dùng được giữa các agent khác nhau. Nhưng Claude Code có thêm các trường và cách khởi chạy riêng. Chuyển skill sang một công cụ khác - hãy kiểm tra xem ở đó thực sự hỗ trợ những khả năng nào.

Có thể cùng agent tạo skill của riêng bạn

Lúc nên tạo skill của riêng mình thì nhận ra được mà chẳng cần lý thuyết gì: bạn đang giải thích cùng một quy trình đến lần thứ ba. Không phải nhiệm vụ, mà chính là trình tự thao tác - xem cái này, kiểm tra cái kia, trình bày theo cách này, chỗ này đừng động vào. Đã lặp lại - nghĩa là đến lúc rồi.

Và đây là tin vui. Không nhất thiết phải viết SKILL.md từ trang giấy trắng. Agent có thể soạn bản nháp, còn việc của bạn là giải thích quy trình đó là gì và bạn muốn nó làm được gì. Trông giống hệt một cuộc trò chuyện bình thường:

Tạo một skill để chuẩn bị commit. Nó cần xem những gì đã thay đổi,
kiểm tra xem có file thừa nào lọt vào commit không, và viết commit message
theo mẫu của chúng ta. Tôi sẽ tự chạy nó bằng tay khi cần.
Nếu thiếu yêu cầu, hãy hỏi tôi trước.

Để ý nhé, bạn không hề nêu tên trường nào và cũng không đụng đến cấu trúc file. Yêu cầu được nói bằng lời thường, còn chuyển chúng thành các trường là việc của agent.

Nếu thiếu thông tin, agent sẽ đặt câu hỏi. Nếu không được dặn như vậy, nó có thể tự đưa ra giả định ngay, vì thế dòng cần thiết đã có sẵn trong ví dụ. Nhận được bản nháp rồi, hãy kiểm tra các file, tìm skill bằng /skills và chạy thử.

Nếu quy trình có thể làm bằng tay, hãy cùng agent làm một lượt trước khi đóng gói. Một commit làm từng bước sẽ cho thấy chỗ nào phải sửa và lời giải thích còn thiếu gì. Skill viết từ một lần chạy thật sẽ chính xác hơn skill viết theo trí nhớ.

Khi SKILL.md phình to

Skill đầu tiên của bạn gần như lúc nào cũng chỉ là một file, và như vậy là bình thường. Chật chội bắt đầu sau này: quy trình thêm dần chi tiết, bảng đối chiếu, danh sách quy tắc, ba ví dụ dài lần lượt chui vào, và một ngày bạn mở ra một file dài bốn màn hình.

Không nên dồn mọi thứ vào một chỗ, và lý do đã nói ở trên: phần nội dung được nạp toàn bộ ngay khi skill được dùng. Bốn màn hình tài liệu tham khảo sẽ bị kéo vào công việc cả những lần chỉ cần đúng một dòng trong đó.

Vì vậy, chi tiết được tách ra các file bên cạnh, còn trong SKILL.md chỉ để lại lời dẫn: gặp tình huống này - hãy mở file kia. Bạn đã thấy thư mục có palettes.md và scripts/, còn đây là bên trong trông như thế nào:

## Tài liệu tham khảo

- Bảng màu và cách phối màu - trong [palettes.md](palettes.md)
- Ví dụ markup có sẵn - trong [examples.md](examples.md)
- Kiểm tra độ tương phản: chạy scripts/check.py

Agent mở tài liệu tham khảo khi cần. Script có thể chạy mà không cần tự động nạp toàn bộ mã nguồn vào cuộc trò chuyện, nên kích thước file gần như không tốn context. Nhưng script của người khác thì vẫn phải đọc trước lần chạy đầu tiên: đó là code thực thi, và output của nó sẽ đi vào công việc của agent.

Tiện nhất là sắp xếp theo công dụng:

• SKILL.md - bản thân quy trình: làm gì, theo thứ tự nào, không được làm gì. Trước khi gọi, agent chỉ thấy phần mô tả, còn nội dung được nạp khi skill chạy;
• tài liệu tham khảo - bảng, quy tắc, ví dụ dài, tất cả những gì không cần đến trong mọi lần chạy;
• scripts/ - những việc chạy thì dễ hơn là mô tả bằng lời. Với skill của người khác, các file này phải được kiểm tra trước khi chạy;
• mẫu - các file mà skill lấy làm nền rồi chỉnh theo nhiệm vụ.

Từ đây cũng rút ra một kết luận ngược lại, lần này là về skill của người khác. SKILL.md ngắn không có nghĩa là "skill đơn giản". Hãy xem trong thư mục bên cạnh nó còn có gì.

Điều này thay đổi gì trong công việc

Tóm gọn lại trong vài dòng:

• một yêu cầu lặp đi lặp lại trở thành một thư mục. Mô tả trình tự làm việc một lần - sau đó nó được lặp lại y như vậy, trong bất kỳ phiên làm việc nào, vào bất kỳ ngày nào;
• skill của riêng bạn không cần viết từ trang giấy trắng. Bạn giải thích quy trình bằng lời, nhờ agent hỏi lại những gì còn thiếu, rồi kiểm tra bản nháp nó soạn ra;
• khi tự động khởi chạy, skill được chọn theo description, khi gọi bằng tay - theo tên có dấu gạch chéo. Nếu nó không phản hồi, trước tiên hãy xem nó có hiện trong danh sách không và có được phép tự khởi chạy không;
• /skills trả lời câu hỏi "nó đã được cài chưa". Nửa phút kiểm tra tiết kiệm nửa giờ đoán mò;
• skill của người khác phải được đọc trước khi cài và chạy, cùng với các file và script liên quan;
• skill thay đổi cách agent làm việc, nhưng không cô lập phạm vi chỉnh sửa và không thay thế việc kiểm tra kết quả.