5 mẫu thiết kế kỹ năng Agent mà mọi nhà phát triển ADK cần biết

Khi nói đến 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍, các nhà phát triển thường tập trung vào định dạng—viết YAML cho đúng, cấu trúc thư mục, và tuân theo thông số kỹ thuật. Nhưng với hơn 30 công cụ agent (như Claude Code, Gemini CLI, và Cursor) đang chuẩn hóa trên cùng một bố cục, vấn đề về định dạng gần như đã lỗi thời.

Thách thức thực sự bây giờ là thiết kế nội dung. Thông số kỹ thuật giải thích cách đóng gói một kỹ năng, nhưng không hướng dẫn cách cấu trúc logic bên trong nó. Ví dụ, một kỹ năng bao bọc các quy ước FastAPI hoạt động hoàn toàn khác với một pipeline tài liệu bốn bước, mặc dù các tệp 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 của chúng trông giống hệt nhau bên ngoài.

Bằng cách nghiên cứu cách các kỹ năng được xây dựng trên toàn hệ sinh thái—từ kho lưu trữ của Anthropic đến hướng dẫn nội bộ của Vercel và Google—có năm mẫu thiết kế lặp đi lặp lại có thể giúp các nhà phát triển xây dựng agent.

Bởi @Saboo_Shubham_ và @lavinigam

Bài viết này đề cập đến từng mẫu với mã ADK hoạt động:

• Tool Wrapper: Biến agent của bạn thành chuyên gia tức thì trên bất kỳ thư viện nào
• Generator: Tạo tài liệu có cấu trúc từ một mẫu có thể tái sử dụng
• Reviewer: Chấm điểm mã theo danh sách kiểm tra theo mức độ nghiêm trọng
• Inversion: Agent phỏng vấn bạn trước khi hành động
• Pipeline: Thực thi một quy trình làm việc nhiều bước nghiêm ngặt với các điểm kiểm tra

Mẫu 1: Tool Wrapper

Tool Wrapper cung cấp cho agent của bạn ngữ cảnh theo yêu cầu cho một thư viện cụ thể. Thay vì mã hóa cứng các quy ước API vào system prompt của bạn, bạn đóng gói chúng thành một kỹ năng. Agent của bạn chỉ tải ngữ cảnh này khi nó thực sự làm việc với công nghệ đó.

Đây là mẫu dễ triển khai nhất. Tệp 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 lắng nghe các từ khóa thư viện cụ thể trong prompt của người dùng, tải động tài liệu nội bộ của bạn từ thư mục 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/, và áp dụng các quy tắc đó như chân lý tuyệt đối. Đây chính xác là cơ chế bạn sử dụng để phân phối hướng dẫn mã hóa nội bộ của nhóm hoặc các phương pháp hay nhất của framework cụ thể trực tiếp vào quy trình làm việc của các nhà phát triển.

Đây là một ví dụ về Tool Wrapper dạy agent cách viết mã FastAPI. Hãy chú ý cách các hướng dẫn yêu cầu agent tải tệp 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 chỉ khi nó bắt đầu xem xét hoặc viết mã:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: Các phương pháp hay nhất và quy ước phát triển FastAPI. Sử dụng khi xây dựng, xem xét hoặc gỡ lỗi các ứng dụng FastAPI, REST API hoặc mô hình Pydantic.
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10Bạn là chuyên gia về phát triển FastAPI. Áp dụng các quy ước này cho mã hoặc câu hỏi của người dùng.
11
12## Quy ước Cốt lõi
13
14Tải 'references/conventions.md' để có danh sách đầy đủ các phương pháp hay nhất về FastAPI.
15
16## Khi Xem xét Mã
171. Tải tài liệu tham khảo quy ước
182. Kiểm tra mã của người dùng với từng quy ước
193. Với mỗi vi phạm, trích dẫn quy tắc cụ thể và đề xuất cách sửa
20
21## Khi Viết Mã
221. Tải tài liệu tham khảo quy ước
232. Tuân theo mọi quy ước một cách chính xác
243. Thêm chú thích kiểu vào tất cả các chữ ký hàm
254. Sử dụng kiểu Annotated cho dependency injection

Mẫu 2: Generator

Trong khi Tool Wrapper áp dụng kiến thức, Generator thực thi đầu ra nhất quán. Nếu bạn gặp khó khăn với việc agent tạo ra các cấu trúc tài liệu khác nhau ở mỗi lần chạy, Generator giải quyết vấn đề này bằng cách điều phối một quy trình điền vào chỗ trống.

Nó tận dụng hai thư mục tùy chọn: 𝚊𝚜𝚜𝚎𝚝𝚜/ chứa mẫu đầu ra của bạn, và 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ chứa hướng dẫn phong cách của bạn. Các hướng dẫn hoạt động như một người quản lý dự án. Chúng yêu cầu agent tải mẫu, đọc hướng dẫn phong cách, hỏi người dùng về các biến còn thiếu, và điền vào tài liệu. Điều này thực tế để tạo tài liệu API có thể dự đoán, chuẩn hóa thông báo commit, hoặc xây dựng cấu trúc dự án.

Trong ví dụ về trình tạo báo cáo kỹ thuật này, tệp kỹ năng không chứa bố cục thực tế hoặc các quy tắc ngữ pháp. Nó chỉ đơn giản điều phối việc truy xuất các tài sản đó và buộc agent thực thi chúng từng bước một:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: Tạo các báo cáo kỹ thuật có cấu trúc ở định dạng Markdown. Sử dụng khi người dùng yêu cầu viết, tạo hoặc soạn thảo một báo cáo, tóm tắt hoặc tài liệu phân tích.
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10Bạn là một trình tạo báo cáo kỹ thuật. Thực hiện các bước sau một cách chính xác:
11
12Bước 1: Tải 'references/style-guide.md' để biết các quy tắc về giọng văn và định dạng.
13
14Bước 2: Tải 'assets/report-template.md' để biết cấu trúc đầu ra bắt buộc.
15
16Bước 3: Hỏi người dùng bất kỳ thông tin còn thiếu nào cần thiết để điền vào mẫu:
17- Chủ đề hoặc đối tượng
18- Các phát hiện chính hoặc điểm dữ liệu
19- Đối tượng mục tiêu (kỹ thuật, điều hành, chung)
20
21Bước 4: Điền mẫu theo các quy tắc của hướng dẫn phong cách. Mọi phần trong mẫu phải có mặt trong đầu ra.
22
23Bước 5: Trả về báo cáo đã hoàn thành dưới dạng một tài liệu Markdown duy nhất.

Mẫu 3: Reviewer

Mẫu Reviewer tách biệt những gì cần kiểm tra khỏi cách kiểm tra nó. Thay vì viết một system prompt dài mô tả chi tiết mọi mùi mã, bạn lưu trữ một rubric dạng mô-đun bên trong tệp 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍.

Khi người dùng gửi mã, agent tải danh sách kiểm tra này và chấm điểm bài nộp một cách có phương pháp, nhóm các phát hiện của nó theo mức độ nghiêm trọng. Nếu bạn đổi danh sách kiểm tra phong cách Python bằng danh sách kiểm tra bảo mật OWASP, bạn sẽ có một cuộc kiểm toán chuyên biệt hoàn toàn khác sử dụng cùng một cơ sở hạ tầng kỹ năng. Đây là một cách hiệu quả cao để tự động hóa các đánh giá PR hoặc phát hiện lỗ hổng trước khi con người xem xét mã.

Kỹ năng code reviewer sau đây chứng minh sự phân tách này. Các hướng dẫn vẫn giữ nguyên tĩnh, nhưng agent tải động các tiêu chí đánh giá cụ thể từ một danh sách kiểm tra bên ngoài và buộc đầu ra có cấu trúc dựa trên mức độ nghiêm trọng:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: Xem xét mã Python về chất lượng, phong cách và các lỗi phổ biến. Sử dụng khi người dùng gửi mã để xem xét, yêu cầu phản hồi về mã của họ hoặc muốn kiểm toán mã.
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10Bạn là một người xem xét mã Python. Thực hiện quy trình xem xét này một cách chính xác:
11
12Bước 1: Tải 'references/review-checklist.md' để có tiêu chí xem xét hoàn chỉnh.
13
14Bước 2: Đọc mã của người dùng một cách cẩn thận. Hiểu mục đích của nó trước khi chỉ trích.
15
16Bước 3: Áp dụng từng quy tắc từ danh sách kiểm tra vào mã. Với mỗi vi phạm được tìm thấy:
17- Ghi chú số dòng (hoặc vị trí gần đúng)
18- Phân loại mức độ nghiêm trọng: error (phải sửa), warning (nên sửa), info (cân nhắc)
19- Giải thích TẠI SAO nó là vấn đề, không chỉ CÁI GÌ sai
20- Đề xuất một cách sửa cụ thể với mã đã được hiệu chỉnh
21
22Bước 4: Tạo một đánh giá có cấu trúc với các phần sau:
23- **Tóm tắt**: Mã làm gì, đánh giá chất lượng tổng thể
24- **Phát hiện**: Nhóm theo mức độ nghiêm trọng (error trước, sau đó warning, rồi info)
25- **Điểm số**: Đánh giá 1-10 với lý do ngắn gọn
26- **3 Khuyến nghị Hàng đầu**: Những cải tiến có tác động nhất

Mẫu 4: Inversion

Agents vốn có xu hướng muốn đoán và tạo ra ngay lập tức. Mẫu Inversion đảo ngược động lực này. Thay vì người dùng điều khiển prompt và agent thực thi, agent đóng vai trò như một người phỏng vấn.

Inversion dựa trên các hướng dẫn kiểm soát rõ ràng, không thể thương lượng (như "KHÔNG được bắt đầu xây dựng cho đến khi tất cả các giai đoạn hoàn thành") để buộc agent thu thập ngữ cảnh trước. Nó đặt các câu hỏi có cấu trúc một cách tuần tự và chờ câu trả lời của bạn trước khi chuyển sang giai đoạn tiếp theo. Agent từ chối tổng hợp đầu ra cuối cùng cho đến khi nó có bức tranh toàn cảnh về các yêu cầu và ràng buộc triển khai của bạn.

Để thấy điều này trong hành động, hãy xem xét kỹ năng lập kế hoạch dự án này. Yếu tố quan trọng ở đây là các giai đoạn nghiêm ngặt và hướng dẫn kiểm soát rõ ràng ngăn agent tổng hợp kế hoạch cuối cùng cho đến khi tất cả câu trả lời của người dùng được thu thập:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: Lập kế hoạch cho một dự án phần mềm mới bằng cách thu thập yêu cầu thông qua các câu hỏi có cấu trúc trước khi đưa ra kế hoạch. Sử dụng khi người dùng nói "Tôi muốn xây dựng", "giúp tôi lên kế hoạch", "thiết kế một hệ thống" hoặc "bắt đầu một dự án mới".
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10Bạn đang tiến hành một cuộc phỏng vấn yêu cầu có cấu trúc. KHÔNG được bắt đầu xây dựng hoặc thiết kế cho đến khi tất cả các giai đoạn hoàn thành.
11
12## Giai đoạn 1 — Khám phá Vấn đề (hỏi từng câu một, chờ câu trả lời cho mỗi câu)
13
14Hỏi các câu hỏi này theo thứ tự. Không bỏ qua bất kỳ câu nào.
15
16- Q1: "Dự án này giải quyết vấn đề gì cho người dùng của nó?"
17- Q2: "Người dùng chính là ai? Trình độ kỹ thuật của họ như thế nào?"
18- Q3: "Quy mô dự kiến là gì? (người dùng mỗi ngày, khối lượng dữ liệu, tỷ lệ yêu cầu)"
19
20## Giai đoạn 2 — Ràng buộc Kỹ thuật (chỉ sau khi Giai đoạn 1 được trả lời đầy đủ)
21
22- Q4: "Bạn sẽ sử dụng môi trường triển khai nào?"
23- Q5: "Bạn có yêu cầu hoặc ưu tiên về ngăn xếp công nghệ không?"
24- Q6: "Các yêu cầu không thể thương lượng là gì? (độ trễ, thời gian hoạt động, tuân thủ, ngân sách)"
25
26## Giai đoạn 3 — Tổng hợp (chỉ sau khi tất cả các câu hỏi được trả lời)
27
281. Tải 'assets/plan-template.md' để biết định dạng đầu ra
292. Điền vào mọi phần của mẫu sử dụng các yêu cầu đã thu thập
303. Trình bày kế hoạch đã hoàn thành cho người dùng
314. Hỏi: "Kế hoạch này có nắm bắt chính xác các yêu cầu của bạn không? Bạn muốn thay đổi điều gì?"
325. Lặp lại dựa trên phản hồi cho đến khi người dùng xác nhận

Mẫu 5: Pipeline

Đối với các tác vụ phức tạp, bạn không thể chấp nhận các bước bị bỏ qua hoặc các hướng dẫn bị bỏ qua. Mẫu Pipeline thực thi một quy trình làm việc tuần tự nghiêm ngặt với các điểm kiểm tra cứng.

Các hướng dẫn tự chúng phục vụ như định nghĩa quy trình làm việc. Bằng cách triển khai các điều kiện cổng kim cương rõ ràng (chẳng hạn như yêu cầu phê duyệt của người dùng trước khi chuyển từ tạo docstring sang tổng hợp cuối cùng), Pipeline đảm bảo agent không thể bỏ qua một tác vụ phức tạp và trình bày kết quả cuối cùng chưa được xác thực.

Mẫu này sử dụng tất cả các thư mục tùy chọn, kéo các tệp tham khảo và mẫu khác nhau chỉ ở bước cụ thể nơi chúng cần thiết, giữ cho cửa sổ ngữ cảnh sạch sẽ.

Trong ví dụ về pipeline tài liệu này, hãy chú ý đến các điều kiện cổng rõ ràng. Agent bị cấm rõ ràng chuyển sang giai đoạn tổng hợp cho đến khi người dùng xác nhận các docstring đã tạo ở bước trước đó:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: Tạo tài liệu API từ mã nguồn Python thông qua một pipeline nhiều bước. Sử dụng khi người dùng yêu cầu ghi lại một mô-đun, tạo tài liệu API hoặc tạo tài liệu từ mã.
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10Bạn đang chạy một pipeline tạo tài liệu. Thực thi từng bước theo thứ tự. KHÔNG bỏ qua các bước hoặc tiếp tục nếu một bước thất bại.
11
12## Bước 1 — Phân tích & Kiểm kê
13Phân tích mã Python của người dùng để trích xuất tất cả các lớp, hàm và hằng số công khai. Trình bày kiểm kê dưới dạng danh sách kiểm tra. Hỏi: "Đây có phải là API công khai hoàn chỉnh mà bạn muốn được ghi lại không?"
14
15## Bước 2 — Tạo Docstring
16Đối với mỗi hàm thiếu docstring:
17- Tải 'references/docstring-style.md' để biết định dạng bắt buộc
18- Tạo một docstring theo hướng dẫn phong cách một cách chính xác
19- Trình bày từng docstring đã tạo để người dùng phê duyệt
20KHÔNG chuyển sang Bước 3 cho đến khi người dùng xác nhận.
21
22## Bước 3 — Tổng hợp Tài liệu
23Tải 'assets/api-doc-template.md' để biết cấu trúc đầu ra. Biên soạn tất cả các lớp, hàm và docstring thành một tài liệu tham khảo API duy nhất.
24
25## Bước 4 — Kiểm tra Chất lượng
26Xem xét dựa trên 'references/quality-checklist.md':
27- Mọi ký hiệu công khai đã được ghi lại
28- Mọi tham số có kiểu và mô tả
29- Ít nhất một ví dụ sử dụng cho mỗi hàm
30Báo cáo kết quả. Sửa lỗi trước khi trình bày tài liệu cuối cùng.

Chọn mẫu kỹ năng agent phù hợp

Mỗi mẫu trả lời một câu hỏi khác nhau. Sử dụng cây quyết định này để tìm ra mẫu phù hợp cho trường hợp sử dụng của bạn:

Và cuối cùng, các mẫu kết hợp với nhau

Các mẫu này không loại trừ lẫn nhau. Chúng kết hợp với nhau.

Một kỹ năng Pipeline có thể bao gồm một bước Reviewer ở cuối để kiểm tra lại công việc của chính nó. Một Generator có thể dựa vào Inversion ngay từ đầu để thu thập các biến cần thiết trước khi điền vào mẫu của nó. Nhờ 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 của ADK và tiết lộ dần dần, agent của bạn chỉ dùng token ngữ cảnh cho các mẫu chính xác mà nó cần tại thời điểm chạy.

Đừng cố nhồi nhét các hướng dẫn phức tạp và mong manh vào một system prompt duy nhất. Hãy chia nhỏ quy trình làm việc của bạn, áp dụng mẫu cấu trúc phù hợp, và xây dựng các agent đáng tin cậy.

Bắt đầu ngay hôm nay

Thông số kỹ thuật Agent Skills là mã nguồn mở và được hỗ trợ tự nhiên trên toàn bộ ADK. Bạn đã biết cách đóng gói định dạng. Bây giờ bạn đã biết cách thiết kế nội dung. Hãy xây dựng các agent thông minh hơn với Google Agent Development Kit.