Quản trị Skill như Software Dependency

Lựa chọn và quản trị skill như các dependency

Ưu tiên các skill chính hãng (first-party) cho các hệ thống của riêng vendor, cố định phiên bản (pin version) và kiểm toán mọi package được tiếp nhận về chỉ dẫn, script, dependency, phân quyền cũng như quyền truy cập dữ liệu. Skill là một đầu vào chuỗi cung ứng có thể thực thi, chứ không phải là tài liệu hướng dẫn vô hại.

Áp dụng các mức độ tin cậy mặc định khác nhau: các skill từ vendor chính hãng có thể được tin tưởng nhưng vẫn phải cố định phiên bản; các skill do tổ chức biên soạn cần kiểm duyệt PR nội bộ; các skill từ cộng đồng yêu cầu kiểm toán toàn bộ và cố định phiên bản một cách nghiêm ngặt. Độ phổ biến, thứ hạng trên marketplace hay một file README bóng bẩy không phải là bằng chứng về khả năng bảo trì hay độ an toàn.

Quy mô khiến việc đánh giá bằng cảm tính thủ công không còn khả thi: tài liệu gốc cho biết các marketplace công khai đã vượt quá 40.000 bản ghi vào đầu năm 2026. Hãy coi đó là ngữ cảnh cho quy trình lựa chọn, chứ không phải là tín hiệu chất lượng. Danh mục cần có phân loại nguồn, người bảo trì, lần kiểm duyệt gần nhất, phiên bản cố định, phân quyền, trạng thái chồng lấn và bằng chứng đánh giá trước khi một skill được phép hoạt động.

Quyết định lựa chọn phải tạo ra một hồ sơ tiếp nhận (adoption record) gồm nguồn và phiên bản, chủ sở hữu, runtime được hỗ trợ, phạm vi phân quyền, các skill chồng lấn, đường dẫn bộ đánh giá và phương án rollback. Nếu hai skill cùng nhận xử lý một yêu cầu, hãy giải quyết ranh giới trước khi cài đặt thay vì trông chờ model tự ứng biến.

Cần chú ý tới các dấu hiệu kém chất lượng (quality smells):

• Phần body dài hơn khoảng 5.000 token hoặc liên tục phình ra với các phần xử lý trường hợp ngoại lệ.
• Hai team chuyên môn đều có vẻ có thể sở hữu nó, hoặc phần mô tả nối các công việc không liên quan bằng từ “và.”
• Team không thể viết được ba trường hợp đánh giá cụ thể.
• Phần mô tả bắt đầu bằng “một skill hữu ích cho” thay vì nêu rõ điểm kích hoạt, đầu vào, đầu ra và khi nào không nên dùng.
• Logic cố định được viết thành các lời cảnh báo lặp đi lặp lại thay vì các script hoặc cổng kiểm soát.
• Skill lặp lại một kết nối MCP, cố định đường dẫn (hard-code path) hoặc secret, hoặc có phần body dài mà không tham chiếu tới tài nguyên nào.

Quyền sở hữu phải đi theo quy tắc kinh doanh. Team sản phẩm và team nền tảng sở hữu định dạng, hệ thống đánh giá, khả năng quan sát cùng quy trình phát hành; team chuyên môn thay đổi chính sách nền tảng sẽ sở hữu nội dung skill và phê duyệt phát hành. Mỗi skill cần đúng một chủ sở hữu chịu trách nhiệm, kể cả khi có nhiều team cùng đóng góp.

Hợp đồng xây dựng và triển khai thực tế

Một file SKILL.md tối thiểu cần mở ra name, phần description bắt đầu bằng động từ có hướng dẫn khi nào dùng và khi nào không dùng, phiên bản, giấy phép, allowed-tools tùy chọn cùng metadata tác giả. Phần body phải định nghĩa khi nào dùng, khi nào không dùng, quy trình có thứ tự, các trường hợp ngoại lệ được tham chiếu, ví dụ, định dạng đầu ra và các phản mẫu cần tránh (anti-patterns). Frontmatter là một giao diện: hãy validate nó trong CI và coi mọi sự bổ sung phân quyền là một thay đổi về bảo mật.

---
name: refund-duplicate-charge
description: Investigate duplicate charges for a known order and draft a resolution. Use for billed-twice requests. Do NOT use for declined cards, delivery status, or executing refunds.
version: 1.0.0
allowed-tools: [lookup_order, check_duplicate_charge]
metadata:
  owner: payments-operations
---
 
# Refund duplicate charge
## When to use
- The user identifies or can provide an order with two suspected charges.
## When NOT to use
- A payment was declined, delivery is late, or the user asks only for refund status.
## Workflow
1. Resolve the order ID; ask if it is missing.
2. Retrieve the order and suspected charges.
3. Check duplicate-charge eligibility using the referenced market policy.
4. Return an evidence-backed draft; never execute a refund in this tier.
## Output format
- Order, evidence, eligibility, proposed next step, and unresolved questions.

Hãy đọc ví dụ này như một hợp đồng. Phần mô tả sở hữu việc định tuyến; allowed-tools ngăn chặn quyền ghi vô tình; quy trình giải thích thứ tự và hành vi dừng; hình dáng đầu ra giúp viết bài đánh giá. Chi tiết chính sách vẫn thuộc về references/, còn việc chuẩn hóa cố định vẫn thuộc về scripts/. Một chỉ dẫn mơ hồ như “hỗ trợ xử lý hoàn tiền một cách hữu ích” không cung cấp được bất kỳ cơ chế kiểm soát nào trong số này.

Sử dụng tên dễ đoán: snake_case cho thư mục, kebab-case và ưu tiên danh động từ (gerund) cho tên skill; tránh utils, helper, tools, tiền tố vendor và thuật ngữ nội bộ. Giới hạn phần mô tả khác nhau tùy theo runtime, vì vậy cần viết cụ thể và tiết kiệm: một công việc, các cụm từ kích hoạt, đầu vào, đầu ra mong đợi và ranh giới không hợp lệ.

Giới hạn thực tế trong tài liệu gốc là tối đa 200 ký tự cho mô tả API và 1.024 ký tự trong YAML, với nhiều tác giả nhắm tới khoảng 50 từ. Hãy coi schema thực tế của runtime là chuẩn mực, validate giới hạn một cách tự động và tuyệt đối không rút gọn bằng cách xóa đi ranh giới không hợp lệ.

Trước khi triển khai, bắt buộc phải có checklist này:

• Linter frontmatter vượt qua; không cố định đường dẫn, secret hay dependency không tin cậy.
• Các script cố định có kiểm thử đơn vị; bài đánh giá skill chạy trong CI với ngưỡng vượt qua tối thiểu.
• Phần mô tả được kiểm duyệt bởi một người không phải tác giả.
• Các trường hợp hợp lệ, không hợp lệ, thực thi, suy thoái và tải token với 5–15 skill đều vượt qua.
• Quét phân quyền và an ninh sạch sẻ; các đường dẫn hành vi có bằng chứng cho phê duyệt, tính lặp lại và rollback.
• Các đường dẫn cài đặt trên nhiều công cụ và hành vi kích hoạt được kiểm thử cho mọi runtime được hỗ trợ.
• Bản ghi cấp phát admin/registry cấp tổ chức cùng bản ghi chủ sở hữu/trực sự cố được cập nhật.

Các nguyên tắc chất lượng tốt giúp giữ cho package nhỏ gọn: tự chạy tác vụ thủ công trước khi mã hóa nó; giải thích lý do tại sao quy tắc tồn tại thay vì xếp chồng các từ ALWAYS; làm cho mọi chỉ dẫn có thể kiểm chứng được; đóng gói các công việc tính toán cố định lặp đi lặp lại; và chia tách ngay khi nguyên tắc “một skill, một công việc” không còn đúng. Thành phẩm triển khai là một bản ghi phát hành được ký xác nhận liên kết tới package được cố định phiên bản, ma trận bao phủ, các phê duyệt, ma trận runtime, phiên bản rollback và bảng điều khiển giám sát.