SP-2 · เจาะ 3 skill พื้นฐานทีละตัว (อ่าน SKILL.md ให้เป็น)

บทที่แล้ว (SP-1) เราเห็น "วงจรหลัก" ของ Superpowers แบบภาพกว้างว่า brainstorm → plan → implement (TDD) → review ไปแล้ว บทนี้เราจะ "เปิดฝากระโปรง" ดูว่าแต่ละขั้นของวงจรนั้น จริง ๆ แล้วมันคือไฟล์อะไร เขียนยังไง และทำไม agent ถึง "รู้" ว่าต้องหยิบ skill ไหนมาใช้ — ทั้งหมดนี้อ่านออกมาจากไฟล์ SKILL.md จริง 3 ไฟล์ ใน repo sources/superpowers/skills/ ไม่มีการเดาเลยสักบรรทัด

ทำไมเรื่องนี้สำคัญกับงาน dev ของคุณ? เพราะถ้าคุณอยากเขียน skill ของทีมตัวเอง — เช่น "วิธี review PR ของทีม NestJS" หรือ "checklist ก่อน deploy Go service" — คุณต้องรู้โครงไฟล์นี้ให้แม่นก่อน อ่านของคนอื่นให้ออกก่อนถึงจะเขียนของตัวเองเป็น

1. กายวิภาคของไฟล์ SKILL.md

ทุก skill ใน Superpowers คือไฟล์ SKILL.md หนึ่งไฟล์ต่อโฟลเดอร์ (เช่น skills/brainstorming/SKILL.md) โครงมีแค่ 2 ส่วนหลัก:

Frontmatter (บรรทัดบนสุด คั่นด้วย ---) — มี field name (ชื่อ skill) กับ description (คำอธิบายว่า skill นี้ใช้เมื่อไร) field นี้แหละคือ trigger — Claude อ่าน description ของทุก skill ที่ติดตั้งไว้ตอนเริ่ม session แล้วใช้มันตัดสินใจว่า "งานตรงหน้านี้ควรเรียก skill ไหน"
Instructions (เนื้อหาด้านล่าง) — ขั้นตอนจริงที่ agent ต้องทำตาม อาจมี checklist, กฎเหล็ก (hard gate), ตัวอย่าง, หรือ diagram อธิบาย flow

โครง SKILL.md: frontmatter (name + description = ตัวจุดชนวนให้ auto-invoke) ต่อด้วย instructions (ขั้นตอนที่ต้องทำตามเป๊ะ)

💡

เทียบกับ NestJS ให้เห็นภาพ: description ของ SKILL.md คล้าย ๆ @Injectable() decorator ที่บอก DI container ว่า "class นี้ inject ได้เมื่อเข้าเงื่อนไขนี้" — ส่วน instructions คือ method body ที่รันจริงเมื่อถูกเรียก

2. skill ที่ 1 — `using-superpowers`: กฎว่าด้วยการ "ต้องเช็ก skill ก่อน"

นี่คือ skill ที่พิเศษที่สุดในกลุ่ม เพราะ description ของมันบอกตรง ๆ ว่า "Use when starting any conversation" — แปลว่ามัน trigger แทบทุกครั้งที่เริ่มบทสนทนาใหม่ หน้าที่ของมันไม่ใช่การทำงานเฉพาะทาง แต่เป็น "กฎแม่บท" ที่บังคับว่า ก่อนตอบหรือลงมือทำอะไรก็ตาม (รวมถึงคำถามเพื่อความชัดเจน) ต้องเช็กก่อนว่ามี skill ที่เกี่ยวข้องไหม

ข้อความในไฟล์เขียนไว้ชัดมากว่า (แปลความหมาย): "ถ้าคุณคิดว่ามีโอกาสแม้แค่ 1% ที่ skill หนึ่งจะเกี่ยวข้องกับสิ่งที่กำลังทำอยู่ คุณต้องเรียกใช้ skill นั้น ไม่ใช่ทางเลือก" และมี Skill Priority ด้วยว่า เมื่อมีหลาย skill เข้าเงื่อนไขพร้อมกัน ให้ "process skill" (เช่น brainstorming, systematic-debugging) มาก่อนเสมอ แล้วค่อยตามด้วย "implementation skill" (เช่น frontend-design) — ตัวอย่างในไฟล์เอง:

"Let's build X" → เรียก superpowers:brainstorming ก่อน แล้วค่อยตาม implementation skill
"Fix this bug" → เรียก superpowers:systematic-debugging ก่อน แล้วค่อยตาม domain skill

ส่วนที่ทรงพลังที่สุดของไฟล์นี้คือตาราง Red Flags — รวบรวม "ความคิดที่เด้งขึ้นมาในหัว agent เวลากำลังหาข้ออ้างเลี่ยงไม่ใช้ skill" คัดมาเป๊ะจากไฟล์จริง:

ความคิดที่ผุดขึ้นมา (Thought)	ความจริง (Reality)
"This is just a simple question"	คำถามก็คือ task — ต้องเช็ก skill
"I need more context first"	ต้องเช็ก skill ก่อนถามคำถามเพื่อความชัดเจนด้วยซ้ำ
"Let me explore the codebase first"	skill จะบอกวิธี explore เอง — เช็กก่อน
"I remember this skill"	skill อาจเปลี่ยนแปลงได้ — อ่านฉบับล่าสุดเสมอ
"The skill is overkill"	เรื่องง่าย ๆ มักกลายเป็นเรื่องซับซ้อนทีหลัง — ใช้มันไป
"I know what that means"	รู้ concept ไม่เท่ากับใช้ skill จริง — ต้อง invoke

⚠️

ไฟล์ยังระบุด้วยว่า user instructions (CLAUDE.md, คำสั่งตรงจากคุณ) มีความสำคัญเหนือ skill เสมอ — skill จะถูกข้ามได้ก็ต่อเมื่อคุณ (human partner) สั่งชัดเจนเท่านั้น ไม่ใช่ agent ตัดสินใจเองว่า "ข้ามดีกว่า"

3. skill ที่ 2 — `brainstorming`: คุยทีละคำถาม ก่อนลงมือ

description ของ skill นี้เขียนหนักแน่นมาก: "You MUST use this before any creative work — creating features, building components, adding functionality, or modifying behavior" นี่คือ trigger ของมัน — ทุกครั้งที่มีการ "สร้างของใหม่" ต้องผ่าน skill นี้ก่อน

ในไฟล์มี <HARD-GATE> กำกับไว้ตรง ๆ ว่า ห้าม invoke implementation skill, เขียนโค้ด, หรือ scaffold โปรเจกต์ใด ๆ จนกว่าจะ "present design" แล้วผู้ใช้ "approve" แล้วเท่านั้น — ใช้กับทุกโปรเจกต์ ไม่ว่าจะดูเรียบง่ายแค่ไหน (มี anti-pattern ชื่อ "This Is Too Simple To Need A Design" เตือนไว้ตรง ๆ)

ขั้นตอนจริงตาม Checklist ในไฟล์ (ทำเรียงตามลำดับ):

Explore project context — เช็กไฟล์ เอกสาร commit ล่าสุดก่อน
เสนอ "Visual companion" แบบ just-in-time เท่านั้น (ไม่เสนอล่วงหน้า)
Ask clarifying questions ทีละคำถาม — กฎสำคัญคือ "Only one question per message" และเลือกใช้ multiple choice ถ้าเป็นไปได้ เพื่อไม่ให้ผู้ใช้งง
Propose 2-3 approaches — พร้อม trade-off และคำแนะนำที่ agent เชียร์
Present design เป็นส่วน ๆ ตามความซับซ้อน ขอ approve ทีละส่วน
เขียน design doc ลง docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md แล้ว commit
Spec self-review (เช็ก placeholder, ความขัดแย้งในตัวเอง, scope, ความกำกวม)
ให้ user review spec ที่เขียนเสร็จอีกรอบ
Transition — เรียก skill writing-plans ต่อ (จุดจบของ brainstorming คือจุดนี้เท่านั้น)

หลักที่ไฟล์ย้ำอีกจุดคือการ "แตก spec เป็น chunk" — ถ้า request ครอบคลุม หลาย subsystem ที่เป็นอิสระจากกัน (เช่น "สร้าง platform ที่มีทั้ง chat, file storage, billing, analytics") ให้ตั้งข้อสังเกตทันทีและช่วยผู้ใช้ แตกเป็น sub-project ก่อน แล้วค่อย brainstorm ทีละ sub-project แยกกัน — ไม่ใช่ทุ่มคำถามลงไปกับโปรเจกต์ที่ยังไม่ถูกตัดแบ่งขนาด

✅

ผูกกับงานจริง: เวลาคุณคุยกับ Claude Code ว่า "ช่วยเพิ่ม endpoint สำหรับ export ข้อมูล user เป็น CSV ใน NestJS module" — ถ้า agent ทำตาม skill นี้ถูกต้อง มันจะไม่รีบเขียนโค้ด แต่จะถามก่อนว่า field ไหนบ้าง, sync หรือ async job, auth ใครเรียกได้ ทีละคำถาม แล้วค่อยเสนอ 2-3 แนวทาง (เช่น stream ตรง ๆ vs. generate ไฟล์แล้วส่ง link)

4. skill ที่ 3 — `writing-plans`: แปลง spec เป็นแผนที่ engineer มือใหม่ก็ทำตามได้

description: "Use when you have a spec or requirements for a multi-step task, before touching code" — trigger คือ "มี spec/requirements แล้ว และกำลังจะเริ่มงานหลายขั้นตอน" นี่คือจุดต่อจาก brainstorming พอดี

หลักการเขียน plan ตามไฟล์คือ ให้เขียนราวกับว่า "engineer ที่ทำตามแผนนี้ไม่มี context อะไรเกี่ยวกับ codebase เลย และมี taste ที่น่าสงสัย (questionable taste)" — ต้องเขียนละเอียดสุด ๆ: ไฟล์ไหนต้องแก้ ทำอะไร โค้ดจริง วิธีเทส ต้องอ่านเอกสารอะไรเพิ่ม

โครงของ plan ที่ดีตามไฟล์จริงมีลำดับนี้:

Plan Document Header — ต้องมี Goal (1 ประโยค), Architecture (2-3 ประโยค), Tech Stack, และ Global Constraints (ข้อจำกัดระดับโปรเจกต์ เช่น version floor, naming rule — คัดลอกจาก spec แบบคำต่อคำ)
File Structure — map ก่อนว่าไฟล์ไหนจะสร้าง/แก้ แต่ละไฟล์รับผิดชอบอะไร (ตาม principle "one clear responsibility" — คุ้นเคยกับที่คุณทำใน NestJS module/service แยกกันอยู่แล้ว)
Task ต่อ Task — แต่ละ task มี block Files (create/modify/test path ชัดเจน) และ Interfaces (Consumes = ใช้อะไรจาก task ก่อนหน้า, Produces = signature ที่ task ถัดไปจะต้องใช้ต่อ)
Bite-sized steps — แต่ละ step ทำได้ใน 2-5 นาที เช่น "เขียน failing test" → "รันดูว่า fail จริง" → "implement ขั้นต่ำให้ผ่าน" → "รันดูว่า pass" → "commit" — นี่คือ TDD loop ตรง ๆ

รูปแบบ task หนึ่งชิ้นตาม writing-plans: ระบุไฟล์ + interface ชัดเจน แล้วตามด้วย step แบบ TDD ทีละ 2-5 นาที

ไฟล์ยังมีหัวข้อ No Placeholders ที่ระบุชัดว่าอะไรคือ "plan failure" ห้ามเขียนเด็ดขาด: "TBD", "implement later", "Add appropriate error handling" (ต้องเขียนโค้ด error handling จริง), หรือ "Similar to Task N" (ต้องเขียนโค้ดซ้ำให้ครบ เพราะ engineer อาจอ่านข้าม task ไม่เรียงลำดับ)

และก่อนจบ ต้องมี Self-Review 3 จุด: (1) spec coverage — ทุก requirement ใน spec มี task รองรับไหม (2) placeholder scan — หา red flag ที่ห้ามเขียนซ้ำอีกรอบ (3) type consistency — ชื่อ function/property ที่ใช้ใน task หลัง ๆ ต้องตรงกับที่ประกาศไว้ใน task ก่อนหน้า (ตัวอย่างในไฟล์เอง: ถ้า Task 3 ประกาศ clearLayers() แต่ Task 7 เรียก clearFullLayers() นี่คือบั๊กที่ต้องจับให้ได้)

💡

เทียบกับที่คุณคุ้นเคย: Interfaces: Consumes/Produces ใน writing-plans ก็เหมือนกับตอนคุณออกแบบ DTO ระหว่าง service สอง ตัวใน NestJS หรือ struct request/response ระหว่าง handler สอง ตัวใน Go — ต้องรู้ signature ชัดเจนก่อนแยกกันเขียน ไม่งั้นต่อกันไม่ติด

5. อ่าน SKILL.md ของ repo อื่นเป็น = อ่านคู่มือ AI ของทีมเป็น

ทักษะที่อยากให้คุณติดตัวจากบทนี้ไม่ใช่แค่ "รู้ 3 skill นี้" แต่คือ เปิด SKILL.md ไฟล์ไหนก็ได้แล้วตอบได้ใน 30 วินาที ว่า:

skill นี้ trigger เมื่อไร — ดูที่ description
skill นี้ บังคับ อะไรบ้าง (hard gate, "MUST") vs. แค่ แนะนำ
skill นี้ทำงานคนเดียวจบ หรือต้องส่งต่อไป skill อื่น (เช่น brainstorming ส่งต่อ writing-plans เสมอ)

พอคุณอ่านออก คุณจะ debug ได้ทันทีเวลา agent "ไม่ทำตามที่ควรจะเป็น" — เพราะคุณสามารถเปิดไฟล์ SKILL.md ที่เกี่ยวข้องขึ้นมาเช็กได้เองว่า ไฟล์เขียนไว้ว่าไง ไม่ต้องเดา และเมื่อถึงเวลาเขียน skill ของทีมตัวเอง (SP-6 ในแทร็กนี้) คุณจะรู้ทันทีว่าโครงต้องมีอะไรบ้าง

⚠️

Pitfall ที่พบบ่อย: อ่าน SKILL.md ผ่าน ๆ แล้วคิดว่า "เข้าใจแล้ว" แต่ตาราง Red Flags ในไฟล์ using-superpowers เตือนไว้ตรง ๆ ว่า "I remember this skill" → Reality: Skills evolve. Read current version. — อย่าพึ่งความจำ เปิดไฟล์จริงเช็กทุกครั้งที่ไม่แน่ใจ

🎯 แบบฝึกหัด

เปิดไฟล์จริง sources/superpowers/skills/using-superpowers/SKILL.md แล้วเขียนคำตอบสั้น ๆ ว่า description (trigger) ของมันคืออะไร ตามด้วยศัพท์ของคุณเอง (ห้ามลอกทั้งประโยค)
ทำแบบเดียวกันกับ skills/brainstorming/SKILL.md — หา <HARD-GATE> ในไฟล์ แล้วอธิบายว่ามันห้ามอะไร จนกว่าจะเกิดเงื่อนไขไหน
ลองพิมพ์ในแชทกับ Claude ว่า "ช่วยเพิ่ม field deletedAt แบบ soft-delete ให้ entity User ใน NestJS" แล้วสังเกตว่า agent เรียก skill ไหนก่อน (ถ้าติดตั้ง Superpowers อยู่) ตรงกับที่คาดไว้ จาก using-superpowers ไหม