5 รูปแบบการออกแบบทักษะ Agent ที่นักพัฒนา ADK ทุกคนควรรู้

เมื่อพูดถึง 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 นักพัฒนามักจะหมกมุ่นอยู่กับรูปแบบ — การทำให้ YAML ถูกต้อง การจัดโครงสร้างไดเรกทอรี และการทำตามสเปก แต่ด้วยเครื่องมือเอเจนต์มากกว่า 30 ตัว (เช่น Claude Code, Gemini CLI และ Cursor) ที่ใช้รูปแบบเดียวกัน ปัญหาเรื่องรูปแบบก็แทบจะกลายเป็นเรื่องล้าสมัยไปแล้ว

ความท้าทายตอนนี้คือการออกแบบเนื้อหา สเปกอธิบายวิธีแพ็กเกจสกิล แต่ไม่ได้ให้คำแนะนำใดๆ เกี่ยวกับวิธีการจัดโครงสร้างตรรกะภายในสกิล ตัวอย่างเช่น สกิลที่ห่อหุ้มหลักปฏิบัติของ FastAPI ทำงานแตกต่างอย่างสิ้นเชิงจากไปป์ไลน์เอกสารสี่ขั้นตอน แม้ว่าไฟล์ 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 ของทั้งสองจะดูเหมือนกันจากภายนอก

จากการศึกษาวิธีสร้างสกิลในระบบนิเวศ — ตั้งแต่คลังเก็บของ Anthropic ไปจนถึงแนวทางภายในของ Vercel และ Google — มีรูปแบบการออกแบบที่เกิดขึ้นซ้ำๆ ห้ารูปแบบที่ช่วยให้นักพัฒนาสร้างเอเจนต์ได้

โดย @Saboo_Shubham_ และ @lavinigam

บทความนี้ครอบคลุมแต่ละรูปแบบพร้อมโค้ด ADK ที่ใช้งานได้:

• Tool Wrapper: ทำให้เอเจนต์ของคุณเป็นผู้เชี่ยวชาญในไลบรารีใดๆ ทันที
• Generator: สร้างเอกสารที่มีโครงสร้างจากแม่แบบที่ใช้ซ้ำได้
• Reviewer: ให้คะแนนโค้ดตามรายการตรวจสอบโดยแบ่งตามระดับความรุนแรง
• Inversion: เอเจนต์สัมภาษณ์คุณก่อนดำเนินการ
• Pipeline: บังคับใช้เวิร์กโฟลว์หลายขั้นตอนที่เข้มงวดพร้อมจุดตรวจสอบ

รูปแบบที่ 1: Tool Wrapper

Tool Wrapper มอบบริบทตามความต้องการสำหรับไลบรารีเฉพาะให้กับเอเจนต์ของคุณ แทนที่จะเขียนหลักปฏิบัติของ API ลงใน system prompt โดยตรง คุณแพ็กเกจหลักปฏิบัติเหล่านั้นลงในสกิล เอเจนต์ของคุณจะโหลดบริบทนี้เมื่อทำงานกับเทคโนโลยีนั้นเท่านั้น

เป็นรูปแบบที่ implement ง่ายที่สุด ไฟล์ 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 จะฟังคีย์เวิร์ดของไลบรารีเฉพาะในพรอมpt ของผู้ใช้ โหลดเอกสารภายในของคุณจากไดเรกทอรี 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ แบบไดนามิก และใช้กฎเหล่านั้นเป็นความจริงที่แน่นอน นี่คือกลไกเดียวกับที่คุณใช้แจกจ่ายแนวทางการเขียนโค้ดภายในทีมหรือแนวทางปฏิบัติที่ดีที่สุดของเฟรมเวิร์กเฉพาะให้กับเวิร์กโฟลว์ของนักพัฒนาโดยตรง

นี่คือตัวอย่างของ Tool Wrapper ที่สอนเอเจนต์ให้เขียนโค้ด FastAPI สังเกตว่าคำสั่งบอกให้เอเจนต์โหลดไฟล์ 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 เฉพาะเมื่อเริ่มตรวจสอบหรือเขียนโค้ด:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: แนวทางปฏิบัติที่ดีที่สุดและหลักปฏิบัติในการพัฒนา FastAPI ใช้เมื่อสร้าง ทบทวน หรือดีบักแอปพลิเคชัน FastAPI, REST API หรือโมเดล Pydantic
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10คุณคือผู้เชี่ยวชาญด้านการพัฒนา FastAPI ใช้หลักปฏิบัติเหล่านี้กับโค้ดหรือคำถามของผู้ใช้
11
12## หลักปฏิบัติหลัก
13
14โหลด 'references/conventions.md' สำหรับรายการแนวทางปฏิบัติที่ดีที่สุดของ FastAPI ทั้งหมด
15
16## เมื่อตรวจสอบโค้ด
171. โหลดเอกสารอ้างอิงหลักปฏิบัติ
182. ตรวจสอบโค้ดของผู้ใช้กับแต่ละหลักปฏิบัติ
193. สำหรับการละเมิดแต่ละครั้ง ให้อ้างอิงกฎเฉพาะและแนะนำการแก้ไข
20
21## เมื่อเขียนโค้ด
221. โหลดเอกสารอ้างอิงหลักปฏิบัติ
232. ปฏิบัติตามทุกหลักปฏิบัติอย่างเคร่งครัด
243. เพิ่ม type annotation ให้กับลายเซ็นฟังก์ชันทั้งหมด
254. ใช้สไตล์ Annotated สำหรับ dependency injection

รูปแบบที่ 2: Generator

ในขณะที่ Tool Wrapper ใช้ความรู้ Generator จะบังคับใช้ผลลัพธ์ที่สอดคล้องกัน หากคุณประสบปัญหาเอเจนต์สร้างโครงสร้างเอกสารที่แตกต่างกันในแต่ละรัน Generator จะแก้ปัญหานี้โดยการจัดกระบวนการเติมข้อมูลในช่องว่าง

มันใช้สองไดเรกทอรีที่เป็นทางเลือก: 𝚊𝚜𝚜𝚎𝚝𝚜/ เก็บแม่แบบผลลัพธ์ของคุณ และ 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ เก็บคู่มือสไตล์ของคุณ คำสั่งทำหน้าที่เป็นผู้จัดการโครงการ พวกมันบอกให้เอเจนต์โหลดแม่แบบ อ่านคู่มือสไตล์ ถามผู้ใช้สำหรับตัวแปรที่ขาดหายไป และสร้างเอกสารให้สมบูรณ์ ซึ่งมีประโยชน์สำหรับการสร้างเอกสาร API ที่คาดเดาได้ ทำให้ข้อความ commit เป็นมาตรฐาน หรือสร้างโครงสร้างโปรเจกต์

ในตัวอย่างเครื่องสร้างรายงานทางเทคนิคนี้ ไฟล์สกิลไม่มีเค้าโครงหรือกฎไวยากรณ์จริงๆ มันเพียงแค่ประสานการดึงข้อมูลสินทรัพย์เหล่านั้นและบังคับให้เอเจนต์ดำเนินการทีละขั้นตอน:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: สร้างรายงานทางเทคนิคที่มีโครงสร้างในรูปแบบ Markdown ใช้เมื่อผู้ใช้ขอให้เขียน สร้าง หรือร่างรายงาน สรุป หรือเอกสารวิเคราะห์
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10คุณคือเครื่องสร้างรายงานทางเทคนิค ปฏิบัติตามขั้นตอนเหล่านี้อย่างเคร่งครัด:
11
12ขั้นตอนที่ 1: โหลด 'references/style-guide.md' สำหรับกฎเกี่ยวกับโทนและการจัดรูปแบบ
13
14ขั้นตอนที่ 2: โหลด 'assets/report-template.md' สำหรับโครงสร้างผลลัพธ์ที่ต้องการ
15
16ขั้นตอนที่ 3: ถามผู้ใช้สำหรับข้อมูลที่ขาดหายไปที่จำเป็นในการกรอกแม่แบบ:
17- หัวข้อหรือเรื่อง
18- ผลการค้นหาหรือจุดข้อมูลสำคัญ
19- กลุ่มเป้าหมาย (ด้านเทคนิค, ผู้บริหาร, ทั่วไป)
20
21ขั้นตอนที่ 4: กรอกแม่แบบตามกฎของคู่มือสไตล์ ทุกส่วนในแม่แบบต้องอยู่ในผลลัพธ์
22
23ขั้นตอนที่ 5: ส่งคืนรายงานที่สมบูรณ์เป็นเอกสาร Markdown ไฟล์เดียว

รูปแบบที่ 3: Reviewer

รูปแบบ Reviewer แยกสิ่งที่ต้องตรวจสอบออกจากวิธีการตรวจสอบ แทนที่จะเขียน system prompt ยาวๆ ที่ระบุกลิ่นโค้ดทุกอย่าง คุณเก็บ rubrik แบบโมดูลาร์ไว้ในไฟล์ 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍

เมื่อผู้ใช้ส่งโค้ด เอเจนต์จะโหลดรายการตรวจสอบนี้และให้คะแนนการส่งอย่างเป็นระบบ โดยจัดกลุ่มผลการตรวจสอบตามระดับความรุนแรง หากคุณเปลี่ยนรายการตรวจสอบสไตล์ Python เป็นรายการตรวจสอบความปลอดภัย OWASP คุณจะได้รับการตรวจสอบเฉพาะทางที่แตกต่างไปอย่างสิ้นเชิงโดยใช้โครงสร้างพื้นฐานสกิลเดียวกัน เป็นวิธีที่มีประสิทธิภาพสูงในการตรวจสอบ PR โดยอัตโนมัติหรือตรวจจับช่องโหว่ก่อนที่มนุษย์จะดูโค้ด

สกิลตรวจสอบโค้ดต่อไปนี้แสดงให้เห็นถึงการแยกนี้ คำสั่งยังคงนิ่ง แต่เอเจนต์โหลดเกณฑ์การตรวจสอบเฉพาะจากรายการตรวจสอบภายนอกแบบไดนามิก และบังคับให้มีผลลัพธ์ที่มีโครงสร้างตามระดับความรุนแรง:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: ตรวจสอบโค้ด Python เพื่อหาคุณภาพ สไตล์ และบั๊กทั่วไป ใช้เมื่อผู้ใช้ส่งโค้ดเพื่อตรวจสอบ ขอ feedback เกี่ยวกับโค้ด หรือต้องการตรวจสอบโค้ด
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10คุณคือผู้ตรวจสอบโค้ด Python ปฏิบัติตามโปรโตคอลการตรวจสอบนี้อย่างเคร่งครัด:
11
12ขั้นตอนที่ 1: โหลด 'references/review-checklist.md' สำหรับเกณฑ์การตรวจสอบทั้งหมด
13
14ขั้นตอนที่ 2: อ่านโค้ดของผู้ใช้อย่างละเอียด เข้าใจวัตถุประสงค์ก่อนวิจารณ์
15
16ขั้นตอนที่ 3: ใช้แต่ละกฎจากรายการตรวจสอบกับโค้ด สำหรับการละเมิดแต่ละครั้งที่พบ:
17- จดหมายเลขบรรทัด (หรือตำแหน่งโดยประมาณ)
18- จำแนกระดับความรุนแรง: error (ต้องแก้ไข), warning (ควรแก้ไข), info (พิจารณา)
19- อธิบายว่าเหตุใดจึงเป็นปัญหา ไม่ใช่แค่สิ่งที่ผิด
20- แนะนำการแก้ไขเฉพาะพร้อมโค้ดที่แก้ไขแล้ว
21
22ขั้นตอนที่ 4: สร้างผลการตรวจสอบที่มีโครงสร้างพร้อมส่วนเหล่านี้:
23- **สรุป**: โค้ดทำอะไร, การประเมินคุณภาพโดยรวม
24- **ผลการตรวจสอบ**: จัดกลุ่มตามระดับความรุนแรง (error ก่อน, ตามด้วย warning, แล้ว info)
25- **คะแนน**: ให้คะแนน 1-10 พร้อมเหตุผลสั้นๆ
26- **ข้อแนะนำ 3 อันดับแรก**: การปรับปรุงที่มีผลกระทบมากที่สุด

รูปแบบที่ 4: Inversion

เอเจนต์มักจะอยากเดาและสร้างทันที รูปแบบ Inversion จะพลิกไดนามิกนี้ แทนที่ผู้ใช้จะเป็นผู้ขับเคลื่อนพรอมpt และเอเจนต์จะดำเนินการ เอเจนต์จะทำหน้าที่เป็นผู้สัมภาษณ์

Inversion อาศัยคำสั่งกั้นที่ชัดเจนและไม่สามารถต่อรองได้ (เช่น "อย่าเริ่มสร้างจนกว่าทุกเฟสจะเสร็จสมบูรณ์") เพื่อบังคับให้เอเจนต์รวบรวมบริบทก่อน มันถามคำถามที่มีโครงสร้างตามลำดับและรอคำตอบของคุณก่อนที่จะย้ายไปยังเฟสถัดไป เอเจนต์จะปฏิเสธที่จะสังเคราะห์ผลลัพธ์สุดท้ายจนกว่าจะมีภาพรวมที่สมบูรณ์ของข้อกำหนดและข้อจำกัดในการปรับใช้

หากต้องการดูการทำงานนี้ ให้ดูสกิลวางแผนโปรเจกต์นี้ องค์ประกอบที่สำคัญที่นี่คือการแบ่งเฟสที่เข้มงวดและพรอมptกั้นที่ชัดเจนซึ่งหยุดเอเจนต์จากการสังเคราะห์แผนสุดท้ายจนกว่าจะรวบรวมคำตอบของผู้ใช้ทั้งหมด:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: วางแผนโปรเจกต์ซอฟต์แวร์ใหม่โดยรวบรวมข้อกำหนดผ่านคำถามที่มีโครงสร้างก่อนสร้างแผน ใช้เมื่อผู้ใช้พูดว่า "ฉันต้องการสร้าง", "ช่วยฉันวางแผน", "ออกแบบระบบ" หรือ "เริ่มโปรเจกต์ใหม่"
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10คุณกำลังดำเนินการสัมภาษณ์ข้อกำหนดที่มีโครงสร้าง อย่าเริ่มสร้างหรือออกแบบจนกว่าทุกเฟสจะเสร็จสมบูรณ์
11
12## เฟส 1 — การค้นพบปัญหา (ถามทีละคำถาม รอคำตอบแต่ละข้อ)
13
14ถามคำถามเหล่านี้ตามลำดับ อย่าข้ามคำถามใดๆ
15
16- Q1: "โปรเจกต์นี้แก้ปัญหาอะไรให้กับผู้ใช้?"
17- Q2: "ใครคือผู้ใช้หลัก? ระดับความเชี่ยวชาญด้านเทคนิคของพวกเขาคืออะไร?"
18- Q3: "คาดว่าสเกลจะเป็นเท่าใด? (ผู้ใช้ต่อวัน, ปริมาณข้อมูล, อัตราคำขอ)"
19
20## เฟส 2 — ข้อจำกัดทางเทคนิค (หลังจากเฟส 1 ได้รับคำตอบครบถ้วนเท่านั้น)
21
22- Q4: "คุณจะใช้สภาพแวดล้อมการปรับใช้อะไร?"
23- Q5: "คุณมีข้อกำหนดหรือความชอบเกี่ยวกับสแต็กเทคโนโลยีหรือไม่?"
24- Q6: "ข้อกำหนดที่ไม่สามารถต่อรองได้คืออะไร? (เวลาแฝง, อัปไทม์, การปฏิบัติตามข้อกำหนด, งบประมาณ)"
25
26## เฟส 3 — การสังเคราะห์ (หลังจากคำถามทั้งหมดได้รับคำตอบเท่านั้น)
27
281. โหลด 'assets/plan-template.md' สำหรับรูปแบบผลลัพธ์
292. กรอกทุกส่วนของแม่แบบโดยใช้ข้อกำหนดที่รวบรวมได้
303. นำเสนอแผนที่สมบูรณ์ให้ผู้ใช้
314. ถาม: "แผนนี้ครอบคลุมข้อกำหนดของคุณอย่างถูกต้องหรือไม่? คุณต้องการเปลี่ยนแปลงอะไร?"
325. ปรับตาม feedback จนกว่าผู้ใช้จะยืนยัน

รูปแบบที่ 5: Pipeline

สำหรับงานที่ซับซ้อน คุณไม่สามารถปล่อยให้ข้ามขั้นตอนหรือไม่สนใจคำสั่งได้ รูปแบบ Pipeline บังคับใช้เวิร์กโฟลว์ตามลำดับที่เข้มงวดพร้อมจุดตรวจสอบที่แข็ง

คำสั่งเองทำหน้าที่เป็นนิยามเวิร์กโฟลว์ โดยใช้เงื่อนไขกั้นแบบไดมอนด์ที่ชัดเจน (เช่น ต้องให้ผู้ใช้อนุมัติก่อนย้ายจากการสร้าง docstring ไปยังการประกอบขั้นสุดท้าย) Pipeline ทำให้แน่ใจว่าเอเจนต์ไม่สามารถข้ามงานที่ซับซ้อนและนำเสนอผลลัพธ์สุดท้ายที่ไม่ผ่านการตรวจสอบได้

รูปแบบนี้ใช้ไดเรกทอรีที่เป็นทางเลือกทั้งหมด โดยดึงไฟล์อ้างอิงและแม่แบบต่างๆ เฉพาะในขั้นตอนที่จำเป็นเท่านั้น ทำให้หน้าต่างบริบทสะอาด

ในตัวอย่างไปป์ไลน์เอกสารนี้ ให้สังเกตเงื่อนไขกั้นที่ชัดเจน เอเจนต์ถูกห้ามไม่ให้ย้ายไปยังเฟสประกอบจนกว่าผู้ใช้จะยืนยัน docstring ที่สร้างขึ้นในขั้นตอนก่อนหน้า:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: สร้างเอกสาร API จากซอร์สโค้ด Python ผ่านไปป์ไลน์หลายขั้นตอน ใช้เมื่อผู้ใช้ขอให้ทำเอกสารโมดูล สร้างเอกสาร API หรือสร้างเอกสารจากโค้ด
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10คุณกำลังรันไปป์ไลน์การสร้างเอกสาร ดำเนินการแต่ละขั้นตอนตามลำดับ อย่าข้ามขั้นตอนหรือดำเนินการต่อหากขั้นตอนล้มเหลว
11
12## ขั้นตอนที่ 1 — แยกวิเคราะห์และทำรายการสินค้า
13วิเคราะห์โค้ด Python ของผู้ใช้เพื่อแยกคลาส ฟังก์ชัน และค่าคงที่สาธารณะทั้งหมด นำเสนอรายการสินค้าเป็น checklist ถาม: "นี่คือ API สาธารณะทั้งหมดที่คุณต้องการให้ทำเอกสารหรือไม่?"
14
15## ขั้นตอนที่ 2 — สร้าง Docstrings
16สำหรับแต่ละฟังก์ชันที่ไม่มี docstring:
17- โหลด 'references/docstring-style.md' สำหรับรูปแบบที่ต้องการ
18- สร้าง docstring ตามคู่มือสไตล์อย่างเคร่งครัด
19- นำเสนอ docstring แต่ละรายการเพื่อขออนุมัติจากผู้ใช้
20อย่าดำเนินการต่อในขั้นตอนที่ 3 จนกว่าผู้ใช้จะยืนยัน
21
22## ขั้นตอนที่ 3 — ประกอบเอกสาร
23โหลด 'assets/api-doc-template.md' สำหรับโครงสร้างผลลัพธ์ รวบรวมคลาส ฟังก์ชัน และ docstrings ทั้งหมดเป็นเอกสารอ้างอิง API ไฟล์เดียว
24
25## ขั้นตอนที่ 4 — ตรวจสอบคุณภาพ
26ตรวจสอบกับ 'references/quality-checklist.md':
27- ทุกสัญลักษณ์สาธารณะได้รับการทำเอกสาร
28- ทุกพารามิเตอร์มีประเภทและคำอธิบาย
29- ตัวอย่างการใช้งานอย่างน้อยหนึ่งตัวอย่างต่อฟังก์ชัน
30รายงานผลลัพธ์ แก้ไขปัญหาก่อนนำเสนอเอกสารสุดท้าย

การเลือกรูปแบบสกิลเอเจนต์ที่เหมาะสม

แต่ละรูปแบบตอบคำถามที่แตกต่างกัน ใช้แผนผังการตัดสินใจนี้เพื่อค้นหารูปแบบที่เหมาะสมกับกรณีการใช้งานของคุณ:

และสุดท้าย รูปแบบต่างๆ สามารถประกอบกันได้

รูปแบบเหล่านี้ไม่ใช่แบบเอกสิทธิ์ซึ่งกันและกัน พวกมันประกอบกันได้

สกิล Pipeline สามารถรวมขั้นตอน Reviewer ไว้ตอนท้ายเพื่อตรวจสอบงานของตัวเองอีกครั้ง Generator สามารถพึ่งพา Inversion ในตอนเริ่มต้นเพื่อรวบรวมตัวแปรที่จำเป็นก่อนกรอกแม่แบบ ต้องขอบคุณ 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 และการเปิดเผยแบบค่อยเป็นค่อยไปของ ADK เอเจนต์ของคุณจึงใช้ context tokens เฉพาะกับรูปแบบที่ต้องการในขณะทำงานเท่านั้น

หยุดพยายามยัดเยียดคำสั่งที่ซับซ้อนและเปราะบางลงใน system prompt เดียวกัน แบ่งเวิร์กโฟลว์ของคุณออก ใช้รูปแบบโครงสร้างที่เหมาะสม แล้วสร้างเอเจนต์ที่เชื่อถือได้

เริ่มต้นวันนี้

สเปก Agent Skills เป็นโอเพนซอร์สและรองรับโดยตรงบน ADK คุณรู้วิธีแพ็กเกจรูปแบบแล้ว ตอนนี้คุณรู้วิธีออกแบบเนื้อหาแล้ว ไปสร้างเอเจนต์ที่ชาญฉลาดยิ่งขึ้นด้วย Google Agent Development Kit