Cách thêm hỗ trợ skill cho agent

Bài viết này sẽ hướng dẫn bạn thêm hỗ trợ Agent Skills vào một AI agent hoặc công cụ phát triển. Nó bao gồm toàn bộ vòng đời: Khám phá skill, thông báo cho mô hình về skill đó, load nội dung skill vào ngữ cảnh và duy trì hiệu quả của nội dung đó theo thời gian.

Quá trình tích hợp cốt lõi là giống nhau bất kể kiến ​​trúc của agent. Chi tiết triển khai khác nhau dựa trên hai yếu tố:

• Skill được lưu trữ ở đâu? Một agent chạy cục bộ có thể quét hệ thống file của người dùng để tìm thư mục skill. Một agent được lưu trữ trên đám mây hoặc trong môi trường sandbox sẽ cần một cơ chế khám phá thay thế - API, registry từ xa hoặc các tài sản được đóng gói.
• Mô hình truy cập nội dung skill như thế nào? Nếu mô hình có khả năng đọc file, nó có thể đọc trực tiếp các file SKILL.md. Nếu không, bạn sẽ cung cấp một công cụ chuyên dụng hoặc chèn nội dung skill vào prompt theo chương trình.

Hướng dẫn sẽ lưu ý những điểm khác biệt này quan trọng ở đâu. Bạn không cần phải hỗ trợ mọi trường hợp - hãy làm theo cách phù hợp với agent của bạn.

Điều kiện tiên quyết: Hiểu rõ thông số kỹ thuật Agent Skills, trong đó định nghĩa định dạng file SKILL.md, các trường thông tin đầu trang và quy ước thư mục.

Nguyên tắc cốt lõi: Tiết lộ thông tin từng bước

Mọi agent tương thích với skill đều tuân theo chiến lược load thông tin 3 cấp độ giống nhau:

Mô hình nhìn thấy danh mục ngay từ đầu, vì vậy nó biết những skill nào có sẵn. Khi nó quyết định một skill nào đó là phù hợp, nó sẽ load toàn bộ hướng dẫn. Nếu những hướng dẫn đó tham chiếu đến các file hỗ trợ, mô hình sẽ load chúng riêng lẻ khi cần thiết.

Điều này giúp giữ cho ngữ cảnh cơ bản nhỏ gọn trong khi vẫn cung cấp cho mô hình quyền truy cập vào kiến ​​thức chuyên biệt theo yêu cầu. Một agent với 20 skill được cài đặt không phải trả chi phí token cho 20 bộ hướng dẫn đầy đủ ngay từ đầu - chỉ trả chi phí cho những bộ hướng dẫn thực sự được sử dụng trong một cuộc hội thoại nhất định.

Bước 1: Khám phá skill

Khi bắt đầu phiên, hãy tìm tất cả các skill có sẵn và load siêu dữ liệu của chúng.

Nơi cần quét

Việc bạn quét thư mục nào phụ thuộc vào môi trường của agent. Hầu hết các agent chạy cục bộ quét ít nhất hai phạm vi:

• Cấp độ dự án (tương đối so với thư mục làm việc): Các skill cụ thể cho một dự án hoặc kho lưu trữ.
• Cấp độ người dùng (tương đối so với thư mục chính): Các skill có sẵn trên tất cả mọi dự án cho một người dùng nhất định.

Những phạm vi khác cũng có thể - ví dụ: các skill trên toàn tổ chức được triển khai bởi quản trị viên hoặc những skill được đóng gói cùng với chính agent. Tập hợp phạm vi phù hợp phụ thuộc vào mô hình triển khai của agent. Trong mỗi phạm vi, hãy xem xét việc quét cả thư mục dành riêng cho khách hàng và quy ước .agents/skills/:

Những đường dẫn .agents/skills/ đã trở thành một quy ước được áp dụng rộng rãi để chia sẻ skill giữa các client. Mặc dù thông số kỹ thuật Agent Skills không quy định vị trí đặt thư mục skill (nó chỉ định nghĩa nội dung bên trong), việc quét .agents/skills/ có nghĩa là các skill được cài đặt bởi những client tuân thủ khác sẽ tự động hiển thị cho client của bạn và ngược lại.

Cần quét gì?

Trong mỗi thư mục skill, hãy tìm các thư mục con chứa một file có tên chính xác là SKILL.md:

~/.agents/skills/
├── pdf-processing/
│   ├── SKILL.md          ← được phát hiện
│   └── scripts/
│       └── extract.py
├── data-analysis/
│   └── SKILL.md          ← được phát hiện
└── README.md             ← bị bỏ qua (không phải là thư mục skill)

Các quy tắc quét thực tế:

• Bỏ qua các thư mục không chứa skill, chẳng hạn như .git/ và node_modules/
• Tùy chọn tuân thủ .gitignore để tránh quét các artifact được build
• Đặt giới hạn hợp lý (ví dụ: độ sâu tối đa 4 - 6 cấp, tối đa 2000 thư mục) để ngăn chặn việc quét quá mức trong các cây thư mục lớn​

Xử lý xung đột tên

Khi hai skill có cùng tên, hãy áp dụng quy tắc ưu tiên xác định.

Quy ước chung trong các triển khai hiện có: Skill cấp dự án ghi đè lên skill cấp người dùng.

Trong cùng phạm vi (ví dụ: hai skill có tên code-review được tìm thấy trong cả <project>/.agents/skills/ và <project>/.<your-client>/skills/), cả skill được tìm thấy đầu tiên hoặc cuối cùng đều được chấp nhận - hãy chọn một và nhất quán. Ghi lại cảnh báo khi xảy ra xung đột để người dùng biết rằng một skill đã bị che khuất.​

Cân nhắc về độ tin cậy

Các skill cấp dự án đến từ kho lưu trữ đang được sử dụng, kho này có thể không đáng tin cậy (ví dụ: một dự án mã nguồn mở mới được sao chép). Hãy cân nhắc việc kiểm tra độ tin cậy để đảm bảo việc load các skill cấp dự án được thực hiện - chỉ load chúng nếu người dùng đã đánh dấu thư mục dự án là đáng tin cậy. Điều này ngăn chặn các kho lưu trữ không đáng tin cậy âm thầm chèn những chỉ thị vào ngữ cảnh của agent.

​Agent được host trên đám mây và trong môi trường sandbox

Nếu agent của bạn chạy trong container hoặc trên máy chủ từ xa, nó sẽ không có quyền truy cập vào hệ thống file cục bộ của người dùng. Quá trình khám phá cần hoạt động khác nhau tùy thuộc vào phạm vi skill:

• Các skill cấp dự án thường là trường hợp dễ nhất. Nếu agent hoạt động trên một kho lưu trữ được sao chép (ngay cả bên trong môi trường sandbox), các skill cấp dự án sẽ đi kèm với code và có thể được quét từ cây thư mục của kho lưu trữ.
• Các skill cấp người dùng và cấp tổ chức không tồn tại trong môi trường sandbox. Bạn cần cung cấp chúng từ một nguồn bên ngoài - ví dụ: sao chép kho lưu trữ cấu hình, chấp nhận URL skill hoặc gói thông qua cài đặt của agent, hoặc cho phép người dùng load lên thư mục skill thông qua giao diện người dùng web.
• Các skill tích hợp sẵn có thể được đóng gói dưới dạng asset tĩnh trong thành phần triển khai của agent, giúp chúng có sẵn trong mọi phiên mà không cần load về từ bên ngoài.

Sau khi các skill có sẵn cho agent, phần còn lại của vòng đời - phân tích cú pháp, tiết lộ, kích hoạt - hoạt động tương tự.

Bước 2: Phân tích cú pháp các file SKILL.md

Đối với mỗi file SKILL.md được tìm thấy, hãy trích xuất siêu dữ liệu và nội dung phần thân.

Trích xuất phần đầu file

Một file SKILL.md có hai phần: Phần đầu file YAML nằm giữa các dấu phân cách ---, và phần thân file markdown sau dấu phân cách đóng. Để phân tích cú pháp:

1. Tìm dấu --- mở ở đầu file và dấu --- đóng sau đó.
2. Phân tích cú pháp khối YAML nằm giữa chúng. Trích xuất tên và mô tả (bắt buộc), cộng với bất kỳ trường tùy chọn nào.
3. Mọi thứ sau dấu gạch ngang đóng ---, được cắt bớt, là nội dung chính của skill.

Xử lý YAML bị lỗi định dạng

Các file skill được tạo cho những client khác có thể chứa YAML không hợp lệ về mặt kỹ thuật mà trình phân tích cú pháp của chúng chấp nhận. Vấn đề phổ biến nhất là các giá trị không được trích dẫn có chứa dấu hai chấm:

# Về mặt kỹ thuật, YAML không hợp lệ — dấu hai chấm gây lỗi khi phân tích cú pháp
Mô tả: Sử dụng skill này khi: người dùng hỏi về PDF

Hãy xem xét phương án dự phòng là đặt các giá trị đó trong dấu ngoặc kép hoặc chuyển đổi chúng thành những giá trị vô hướng khối YAML trước khi thử lại. Điều này giúp cải thiện khả năng tương thích giữa các client với chi phí tối thiểu.

​Xác thực linh hoạt

Cảnh báo về các vấn đề nhưng vẫn load skill nếu có thể:

• Tên không khớp với tên thư mục cha → cảnh báo, vẫn load
• Tên vượt quá 64 ký tự → cảnh báo, vẫn load
• Mô tả bị thiếu hoặc trống → bỏ qua skill (mô tả là cần thiết để tiết lộ), ghi nhật ký lỗi
• YAML hoàn toàn không thể phân tích cú pháp → bỏ qua skill, ghi nhật ký lỗi

Ghi lại chẩn đoán để chúng có thể được hiển thị cho người dùng (trong lệnh gỡ lỗi, file nhật ký hoặc giao diện người dùng), nhưng không chặn việc load skill vì các vấn đề về hình thức.

Đặc tả định nghĩa các ràng buộc nghiêm ngặt đối với trường tên (khớp với thư mục cha, bộ ký tự, độ dài tối đa). Cách tiếp cận linh hoạt ở trên cố tình nới lỏng các ràng buộc này để cải thiện khả năng tương thích với những skill được tạo cho các client khác.

​Cần lưu trữ gì?

Tối thiểu, mỗi bản ghi skill cần 3 trường:

Lưu trữ những thông tin này trong một bản đồ bộ nhớ được khóa theo name để tra cứu nhanh chóng trong quá trình kích hoạt.

Bạn cũng có thể lưu trữ phần thân (nội dung markdown sau phần mở đầu) tại thời điểm khám phá, hoặc đọc nó từ location tại thời điểm kích hoạt. Lưu trữ giúp quá trình kích hoạt nhanh hơn; đọc nó tại thời điểm kích hoạt sử dụng ít bộ nhớ hơn và cập nhật các thay đổi đối với những file skill giữa các lần kích hoạt.

Thư mục gốc của skill (thư mục cha của location) sẽ cần thiết sau này để giải quyết các đường dẫn tương đối và liệt kê những tài nguyên được đóng gói - hãy lấy nó từ location khi cần.

Bước 3: Tiết lộ các skill có sẵn cho mô hình

Hãy cho mô hình biết những skill nào tồn tại mà không cần load toàn bộ nội dung của chúng. Đây là cấp độ 1 của việc tiết lộ dần dần.

Xây dựng danh mục skill

Đối với mỗi skill được phát hiện, hãy bao gồm tên, mô tả và tùy chọn vị trí (đường dẫn đến file SKILL.md) ở bất kỳ định dạng có cấu trúc nào phù hợp với ngăn xếp của bạn - XML, JSON hoặc danh sách gạch đầu dòng đều hoạt động:

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Trích xuất văn bản PDF, điền biểu mẫu, hợp nhất file. Sử dụng khi xử lý các file PDF.</description>
    <location>/home/user/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Phân tích tập dữ liệu, tạo biểu đồ và lập báo cáo tóm tắt.</description>
    <location>/home/user/project/.agents/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

Trường location phục vụ hai mục đích: Nó cho phép kích hoạt đọc file (xem Bước 4), và nó cung cấp cho mô hình một đường dẫn cơ sở để giải quyết các tham chiếu tương đối trong phần thân skill (như scripts/evaluate.py). Nếu công cụ kích hoạt chuyên dụng của bạn cung cấp đường dẫn thư mục skill trong kết quả của nó (xem phần Bao bọc cấu trúc trong Bước 4), bạn có thể bỏ qua vị trí khỏi danh mục. Nếu không, hãy bao gồm nó.

Mỗi skill thêm khoảng 50-100 token vào danh mục. Ngay cả khi có hàng chục skill được cài đặt, danh mục vẫn nhỏ gọn.

Vị trí đặt danh mục

Có hai cách tiếp cận phổ biến:

Phần prompt hệ thống: Thêm danh mục dưới dạng một phần được gắn nhãn trong prompt hệ thống, đi kèm với hướng dẫn ngắn gọn về cách sử dụng skill. Đây là cách tiếp cận đơn giản nhất và hoạt động với bất kỳ mô hình nào có quyền truy cập vào công cụ đọc file.

Mô tả công cụ: Nhúng danh mục vào mô tả của một công cụ kích hoạt skill chuyên dụng (xem Bước 4). Điều này giữ cho prompt hệ thống gọn gàng và kết hợp tự nhiên giữa khám phá và kích hoạt.

Cả hai cách đều hiệu quả. Đặt trong prompt hệ thống đơn giản hơn và tương thích rộng rãi hơn; nhúng trong mô tả công cụ gọn gàng hơn khi bạn có một công cụ kích hoạt chuyên dụng.

Hướng dẫn hành vi

Bao gồm một khối hướng dẫn ngắn bên cạnh danh mục, hướng dẫn mô hình cách thức và thời điểm sử dụng các skill. Cách diễn đạt phụ thuộc vào cơ chế kích hoạt mà bạn hỗ trợ (xem Bước 4):

Nếu mô hình kích hoạt skill bằng cách đọc file:

Các skill sau đây cung cấp hướng dẫn chuyên biệt cho các nhiệm vụ cụ thể.
Khi một nhiệm vụ phù hợp với mô tả của một skill, hãy sử dụng công cụ đọc file của bạn để load
file SKILL.md tại vị trí được liệt kê trước khi tiếp tục.
Khi một skill tham chiếu đến các đường dẫn tương đối, hãy giải quyết chúng dựa trên
thư mục của skill (thư mục cha của SKILL.md) và sử dụng các đường dẫn tuyệt đối trong những lệnh gọi công cụ.

Nếu mô hình kích hoạt các skill thông qua một công cụ chuyên dụng:

Các skill sau đây cung cấp hướng dẫn chuyên biệt cho các nhiệm vụ cụ thể.
Khi một nhiệm vụ phù hợp với mô tả của một skill, hãy gọi công cụ activate_skill
với tên của skill để load toàn bộ hướng dẫn của nó.

Hãy giữ cho các hướng dẫn này ngắn gọn. Mục tiêu là để cho mô hình biết rằng các skill tồn tại và cách load chúng - nội dung skill tự cung cấp những hướng dẫn chi tiết sau khi được load.

Lọc

Một số skill nên được loại trừ khỏi danh mục. Các lý do phổ biến:

• Người dùng đã vô hiệu hóa skill trong cài đặt
• Hệ thống quyền hạn từ chối truy cập vào skill
• Skill đã từ chối kích hoạt do mô hình điều khiển (ví dụ: thông qua flag disable-model-invocation)

Ẩn hoàn toàn các skill đã lọc khỏi danh mục thay vì liệt kê chúng và chặn tại thời điểm kích hoạt. Điều này ngăn mô hình lãng phí lượt xử lý khi cố gắng load các skill mà nó không thể sử dụng.

Khi không có skill nào khả dụng

Nếu không tìm thấy skill nào, hãy bỏ qua hoàn toàn danh mục và hướng dẫn hành vi. Không hiển thị block <available_skills/> trống hoặc đăng ký công cụ skill không có tùy chọn hợp lệ - điều này sẽ gây nhầm lẫn cho mô hình.

Bước 4: Kích hoạt skill

Khi mô hình hoặc người dùng chọn một skill, hãy cung cấp đầy đủ hướng dẫn vào ngữ cảnh hội thoại. Đây là cấp độ 2 của việc tiết lộ dần dần.

Kích hoạt dựa trên mô hình

Hầu hết các triển khai dựa vào phán đoán của chính mô hình làm cơ chế kích hoạt, thay vì triển khai khớp trình kích hoạt phía khung hoặc phát hiện từ khóa. Mô hình đọc danh mục (từ Bước 3), quyết định skill nào phù hợp với nhiệm vụ hiện tại và load nó.

Hai mô hình triển khai:

Kích hoạt bằng cách đọc file: Mô hình gọi công cụ đọc file tiêu chuẩn của nó với đường dẫn SKILL.md từ danh mục. Không cần cơ sở hạ tầng đặc biệt nào - khả năng đọc file hiện có của agent là đủ. Mô hình nhận nội dung file dưới dạng kết quả của công cụ. Đây là cách tiếp cận đơn giản nhất khi mô hình có quyền truy cập file.

Kích hoạt bằng công cụ chuyên dụng: Đăng ký một công cụ (ví dụ: activate_skill) nhận tên skill và trả về nội dung. Điều này là cần thiết khi mô hình không thể đọc file trực tiếp và là tùy chọn (nhưng hữu ích) ngay cả khi nó có thể. Ưu điểm so với việc đọc file thô:

• Kiểm soát nội dung được trả về - ví dụ: loại bỏ hoặc giữ lại phần frontmatter của YAML (xem phần "Những gì mô hình nhận được" bên dưới)
• Đóng gói nội dung trong các tag có cấu trúc để nhận dạng trong quá trình quản lý ngữ cảnh
• Liệt kê các tài nguyên được đóng gói (ví dụ: references/*) cùng với những hướng dẫn
• Thực thi quyền hoặc yêu cầu sự đồng ý của người dùng
• Theo dõi kích hoạt để phân tích

Kích hoạt rõ ràng bởi người dùng

Người dùng cũng có thể kích hoạt skill trực tiếp, mà không cần chờ mô hình quyết định. Mẫu phổ biến nhất là cú pháp lệnh slash hoặc đề cập (/skill-name hoặc $skill-name) mà công cụ thu thập thông tin sẽ chặn lại. Cú pháp cụ thể tùy thuộc vào bạn - ý tưởng chính là công cụ thu thập thông tin sẽ xử lý việc tìm kiếm và chèn, do đó mô hình nhận được nội dung skill mà không cần tự thực hiện hành động kích hoạt. Một tiện ích tự động hoàn thành (liệt kê các skill có sẵn khi người dùng nhập) cũng có thể giúp dễ dàng tìm thấy thông tin này.

Những gì mô hình nhận được

Khi một skill được kích hoạt, mô hình sẽ nhận được hướng dẫn của skill đó. Có hai tùy chọn về nội dung cụ thể:

Toàn bộ file: Mô hình thấy toàn bộ file SKILL.md bao gồm cả phần frontmatter YAML. Đây là kết quả tự nhiên với việc kích hoạt bằng cách đọc file, trong đó mô hình đọc file thô. Đây cũng là một lựa chọn hợp lệ cho các công cụ chuyên dụng. Phần frontmatter có thể chứa các trường hữu ích tại thời điểm kích hoạt - ví dụ: ghi chú về khả năng tương thích, yêu cầu môi trường có thể cung cấp thông tin về cách mô hình thực thi những hướng dẫn của skill.

Chỉ nội dung (đã loại bỏ frontmatter): Công cụ sẽ phân tích cú pháp và loại bỏ phần frontmatter YAML, chỉ trả về các hướng dẫn markdown. Trong số các triển khai hiện có với những công cụ kích hoạt chuyên dụng, hầu hết đều sử dụng phương pháp này - loại bỏ frontmatter sau khi trích xuất tên và mô tả trong quá trình khám phá.

Cả hai phương pháp đều hoạt động trong thực tế.

Đóng gói có cấu trúc

Nếu bạn sử dụng công cụ kích hoạt chuyên dụng, hãy cân nhắc việc đóng gói nội dung skill trong các tag nhận dạng. Ví dụ:

<skill_content name="pdf-processing">
# PDF Processing

## Khi nào nên sử dụng skill này
Hãy sử dụng kỹ năng này khi người dùng cần làm việc với các file PDF...

[rest of SKILL.md body]

Skill directory: /home/user/.agents/skills/pdf-processing
Các đường dẫn tương đối trong skill này được tính tương đối so với thư mục skill.

<skill_resources>
  <file>scripts/extract.py</file>
  <file>scripts/merge.py</file>
  <file>references/pdf-spec-summary.md</file>
</skill_resources>
</skill_content>

Điều này mang lại những lợi ích thiết thực:

• Mô hình có thể phân biệt rõ ràng các hướng dẫn skill với nội dung hội thoại khác.
• Hệ thống có thể xác định nội dung skill trong quá trình nén ngữ cảnh (Bước 5).
• Các tài nguyên được đóng gói được hiển thị cho mô hình mà không cần load trước.

Liệt kê các tài nguyên được đóng gói

Khi một công cụ kích hoạt chuyên dụng trả về nội dung skill, nó cũng có thể liệt kê các file hỗ trợ (script, tài liệu tham khảo, asset) trong thư mục skill - nhưng nó không nên đọc chúng trước. Mô hình load các file cụ thể theo yêu cầu bằng cách sử dụng những công cụ đọc file của nó khi các hướng dẫn của skill tham chiếu đến chúng.

Đối với các thư mục skill lớn, hãy xem xét giới hạn danh sách và lưu ý rằng nó có thể không đầy đủ.

Cho phép truy cập

Nếu agent của bạn có hệ thống quyền hạn kiểm soát quyền truy cập file, hãy cho phép truy cập các thư mục skill để mô hình có thể đọc những tài nguyên được đóng gói mà không kích hoạt prompt xác nhận của người dùng. Nếu không có điều này, mỗi lần tham chiếu đến một script hoặc file tham chiếu được đóng gói sẽ dẫn đến hộp thoại yêu cầu quyền, làm gián đoạn luồng công việc đối với các skill bao gồm những tài nguyên ngoài chính file SKILL.md.

Bước 5: Quản lý ngữ cảnh skill theo thời gian

Sau khi các hướng dẫn skill được đưa vào ngữ cảnh hội thoại, hãy duy trì hiệu quả của chúng trong suốt phiên.

Bảo vệ nội dung skill khỏi việc nén ngữ cảnh

Nếu agent của bạn cắt ngắn hoặc tóm tắt các tin nhắn cũ hơn khi cửa sổ ngữ cảnh đầy, hãy loại trừ nội dung skill khỏi việc cắt xén. Các chỉ dẫn skill là hướng dẫn hành vi bền vững - việc mất chúng giữa cuộc hội thoại sẽ âm thầm làm giảm hiệu suất của agent mà không có lỗi nào hiển thị. Mô hình vẫn tiếp tục hoạt động nhưng không có các hướng dẫn chuyên biệt mà skill cung cấp.

Các phương pháp phổ biến:

• Đánh dấu đầu ra của công cụ skill là được bảo vệ để thuật toán cắt xén bỏ qua chúng
• Sử dụng các tag có cấu trúc từ Bước 4 để xác định nội dung skill và bảo tồn nó trong quá trình nén

Loại bỏ các kích hoạt trùng lặp

Hãy xem xét việc theo dõi những skill nào đã được kích hoạt trong phiên hiện tại. Nếu mô hình (hoặc người dùng) cố gắng load một skill đã có trong ngữ cảnh, bạn có thể bỏ qua việc chèn lại để tránh các hướng dẫn tương tự xuất hiện nhiều lần trong cuộc hội thoại.

Ủy quyền sub-agent (tùy chọn)

Đây là một mô hình nâng cao chỉ được hỗ trợ bởi một số client. Thay vì chèn hướng dẫn skill vào cuộc hội thoại chính, skill được chạy trong một phiên sub-agent riêng biệt. Sub-agent nhận hướng dẫn skill, thực hiện nhiệm vụ và trả về bản tóm tắt công việc của nó cho cuộc hội thoại chính.

Mô hình này hữu ích khi quy trình làm việc của một skill đủ phức tạp để cần đến một phiên chuyên dụng, tập trung.