agentleFS
Boom-VittBoom-Vitt/skills-thai/skills/productivity/writing-great-skills/SKILL.md

writing-great-skills

Skill5 starsChanged 4 months agoMITView on GitHub

อ้างอิงสำหรับการเขียนและแก้ไข skill ให้ดี — คำศัพท์และหลักการที่ทำให้ skill ทำงานได้อย่างคาดเดาได้

104 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use decision-mapping and batch-grill-me.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • FabienDehopreSkill

    decision-mapping

    Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.

    Also in 7 projects that use this

  • boyingliu01Skill

    batch-grill-me

    A relentless interview that asks every frontier question at once, round by round. Thin alias of `grilling` (#540) — upstream mattpocock/skills absorbed this protocol into grilling; XP-Gate keeps this name as the sprint-flow Phase 2 entry point so orchestration docs stay stable.

    Also in 6 projects that use this

The file

Files
SKILL.md

skill มีไว้เพื่อรีดความ deterministic ออกจากระบบที่ทำงานแบบ stochastic (สุ่มโดยธรรมชาติ) Predictability — การที่ agent เดิน_กระบวนการ_เดิมทุกครั้งที่รัน ไม่ใช่การผลิต output เหมือนเดิม — คือคุณสมบัติรากฐาน กลไกทุกตัวด้านล่างมีไว้รับใช้สิ่งนี้

คำตัวหนา มีนิยามอยู่ใน GLOSSARY.md เปิดดูที่นั่นเพื่อความหมายฉบับเต็ม

Invocation

มีให้เลือกสองแบบ แลกกันคนละต้นทุน:

  • skill แบบ model-invoked ยังเก็บ description ไว้ ทำให้ agent เรียกมันเองได้ และ skill อื่นก็เข้าถึงมันได้ (คุณยังพิมพ์ชื่อเรียกเองได้เหมือนเดิม) แต่มันเพิ่ม context load — description นั่งอยู่ใน context window ทุก turn กลไก: ไม่ต้องใส่ disable-model-invocation และเขียน description ให้ model อ่าน พร้อม trigger phrase ที่ครอบคลุม ("Use when the user wants…, mentions…")
  • skill แบบ user-invoked ตัด description ออกจากการรับรู้ของ agent: มีแค่คุณที่พิมพ์ชื่อมันเท่านั้นที่ invoke ได้ — และ skill อื่นก็เรียกไม่ได้ context load เป็นศูนย์ แต่จ่ายเป็น cognitive load แทน: คุณ คือ index ที่ต้องจำเองว่ามันมีอยู่ กลไก: ตั้ง disable-model-invocation: true แล้ว description จะกลายเป็นข้อความสำหรับคนอ่าน — สรุปหนึ่งบรรทัด ตัด trigger list ทิ้ง

เลือก model-invocation ก็ต่อเมื่อ agent ต้องเข้าถึง skill นั้นได้ด้วยตัวเอง หรือ skill อื่นต้องเรียกมัน ถ้ามันถูกเรียกด้วยมือเท่านั้น ให้ทำเป็น user-invoked แล้วไม่ต้องจ่าย context load เลย

เมื่อ user-invoked skill เพิ่มจำนวนจนเกินกว่าจะจำไหว cognitive load ที่กองสะสมนั้นแก้ได้ด้วย router skill: skill แบบ user-invoked ตัวเดียวที่บอกชื่อ skill ตัวอื่น และบอกว่าเมื่อไหร่ควรหยิบตัวไหน

การเขียน description

description แบบ model-invoked ทำงานสองอย่าง — บอกว่า skill นี้คืออะไร และไล่รายการ branch ที่ควร trigger มัน ทุกคำที่เพิ่มเข้าไปเพิ่ม context load ดังนั้น description ต้องถูก prune หนักยิ่งกว่าตัว body เสียอีก:

  • เอา leading word ของ skill ขึ้นหน้าสุด — description คือที่ที่มันทำหน้าที่ด้าน invocation
  • หนึ่ง trigger ต่อหนึ่ง branch synonym ที่แค่เรียก branch เดียวกันด้วยชื่อใหม่คือ duplication — "build features using TDD … asks for test-first development" คือ branch เดียวที่ถูกเขียนสองรอบ ยุบให้เหลืออันเดียว เก็บไว้เฉพาะ branch ที่ต่างกันจริง
  • ตัด identity ที่มีอยู่ใน body แล้วทิ้งไป ให้ description เหลือแค่ trigger บวกประโยค reach แบบ "when another skill needs…" ถ้าจำเป็น

Information hierarchy

skill ประกอบจากเนื้อหาสองชนิด — step และ reference — ที่ผสมกันได้อิสระ: skill หนึ่งอาจเป็น step ล้วน reference ล้วน หรือทั้งคู่ การตัดสินใจหลักคือจะใช้ชนิดไหน และแต่ละชิ้นควรอยู่ตรงไหนบน information hierarchy — บันไดที่จัดอันดับตามว่า agent ต้องใช้เนื้อหานั้นเร่งด่วนแค่ไหน:

  1. In-skill step — action ที่เรียงลำดับใน SKILL.md เป็นชั้นหลัก: สิ่งที่ agent ทำ ตามลำดับ แต่ละ step จบด้วย completion criterion เงื่อนไขที่บอก agent ว่างานเสร็จแล้ว ทำให้มัน_เช็คได้_ (agent แยกออกไหมว่าเสร็จหรือยังไม่เสร็จ?) และในจุดที่สำคัญ ให้มัน_ครอบคลุมถ้วนทั่ว_ ("ทุก model ที่ถูกแก้ต้องถูกไล่ครบ" ไม่ใช่ "ทำรายการการเปลี่ยนแปลงออกมา") — criterion ที่คลุมเครือเชื้อเชิญ premature completion
  2. In-skill reference — นิยาม กฎ หรือข้อเท็จจริงใน SKILL.md ที่เปิดดูเมื่อต้องใช้ บ่อยครั้งเป็นชุดเนื้อหาระนาบเดียวที่เท่ากันโดยชอบธรรม (กฎทุกข้อของ review อยู่บนขั้นเดียวกัน) — เป็นการจัดวางที่ดี ไม่ใช่กลิ่นไม่ดี skill นี้ทั้งไฟล์คือ reference
  3. External reference — reference ที่ถูกดันออกจาก SKILL.md ไปอยู่ไฟล์แยก เข้าถึงผ่าน context pointer และโหลดเฉพาะตอนที่ pointer ทำงาน (ครอบคลุมตั้งแต่ reference แบบ disclosed — ไฟล์พี่น้องอย่าง GLOSSARY.md ที่ยังเป็นส่วนหนึ่งของ skill — ไปจนถึง external reference เต็มตัวที่อยู่นอกระบบ skill และ skill ไหนก็ชี้ถึงได้)

completion criterion ที่เข้มงวดผลักดันให้เกิด legwork ที่ทั่วถึง — การขุดคุ้ยที่ agent ทำระหว่างงาน — ไม่ว่า skill จะมี step หรือไม่ เพราะ "ทุกกฎถูกใช้ครบ" ผูกมัด reference ระนาบเดียวแบบเดียวกับที่ "ทุก step ทำครบ" ผูกมัด sequence

ดันลงไปน้อยเกิน ชั้นบนก็บวม ดันลงมากเกิน ก็ซ่อนเนื้อหาที่ agent ต้องใช้จริง ความตึงนี้แหละคือทั้งหมดของการตัดสินใจ

Progressive disclosure คือการเลื่อนลงบันได — ออกจาก SKILL.md ไปยังไฟล์ที่ link ไว้ — เพื่อให้ชั้นบนยังอ่านง่าย กลไก: ไฟล์ .md ที่ link ไว้ในโฟลเดอร์ของ skill ตั้งชื่อตามสิ่งที่มันเก็บ (skill นี้ disclose นิยามฉบับเต็มของตัวเองไปไว้ที่ GLOSSARY.md) skill บางตัวถูกใช้มากกว่าหนึ่งแบบ และแต่ละแบบที่ต่างกันคือหนึ่ง branch — การรันคนละครั้งเดินคนละเส้นทางผ่าน skill branching คือ disclosure test ที่สะอาดที่สุด: inline สิ่งที่ทุก branch ต้องใช้ และดันสิ่งที่มีแค่บาง branch เข้าถึงไปไว้หลัง pointer สิ่งที่ตัดสินว่า agent จะไปถึงเนื้อหาเมื่อไหร่และแม่นแค่ไหนคือ_ถ้อยคำ_ของ context pointer ไม่ใช่เป้าหมายของมัน

ขณะที่บันไดตัดสินว่าเนื้อหาชิ้นหนึ่งควรอยู่_ลึกลงไปแค่ไหน_ co-location ตัดสินว่า_อะไรควรอยู่ข้างมัน_เมื่อไปถึงตรงนั้นแล้ว: เก็บนิยาม กฎ และข้อควรระวังของ concept หนึ่งไว้ใต้ heading เดียวกัน ไม่ใช่กระจัดกระจาย เพื่อให้การอ่านส่วนหนึ่งพาเพื่อนบ้านของมันมาด้วย

เมื่อไหร่ควร split

Granularity คือความละเอียดในการแบ่ง skill และการตัดแต่ละครั้งจ่ายด้วย load หนึ่งในสองแบบ ดังนั้น split เฉพาะเมื่อการตัดนั้นคุ้ม การตัดมีสองแบบ:

  • ตัดตาม invocation — แยก skill แบบ model-invoked ออกมาเมื่อคุณมี leading word ที่ชัดเจนพอจะ trigger มันได้ด้วยตัวเอง หรือเมื่อ skill อื่นต้องเรียกมัน คุณจ่าย context load ให้ description ตัวใหม่ที่ถูกโหลดตลอดเวลา ดังนั้นการเข้าถึงแบบอิสระนั้นต้องคุ้มค่าจริง
  • ตัดตาม sequence — แยกช่วงของ step เมื่อ step ที่รออยู่ข้างหน้า (post-completion steps ของ step หนึ่ง) ล่อให้ agent รีบปิด step ตรงหน้า (premature completion) การเก็บพวกมันให้พ้นสายตากระตุ้นให้ agent ทำ legwork กับงานตรงหน้ามากขึ้น

Pruning

เก็บแต่ละความหมายไว้ใน single source of truth: ที่ทางการที่เดียว เพื่อให้การเปลี่ยนพฤติกรรมเป็นการแก้ที่เดียวจบ

เช็คทุกบรรทัดเรื่อง relevance: มันยังเกี่ยวกับสิ่งที่ skill ทำอยู่ไหม?

จากนั้นล่า no-op ทีละประโยค ไม่ใช่แค่ทีละบรรทัด: รัน no-op test กับแต่ละประโยคแบบแยกเดี่ยว และเมื่อประโยคไหนสอบตก ให้ลบทั้งประโยคแทนที่จะเล็มคำออกจากมัน จงดุดัน — prose ส่วนใหญ่ที่สอบตกควรถูกลบทิ้ง ไม่ใช่ถูกเขียนใหม่

Leading words

leading word คือ concept อัดแน่นที่มีอยู่ใน pretraining ของ model อยู่แล้ว ซึ่ง agent ใช้คิดตามระหว่างรัน skill (เช่น lesson, fog of war, tracer bullets) เมื่อถูกใช้ซ้ำทั่วทั้งข้อความ (แม้ไม่จำเป็นเสมอไป — leading word ที่แรงพออาจต้องใช้แค่ครั้งเดียว) มันสะสมนิยามแบบกระจายและตรึงพฤติกรรมทั้งย่านไว้ด้วย token น้อยที่สุด โดยดึง prior ที่ model ถืออยู่แล้วมาใช้งาน

มันรับใช้ predictability สองต่อ ใน body มันตรึง_การ execute_: agent หยิบพฤติกรรมเดิมทุกครั้งที่คำนั้นโผล่มา ใน description มันตรึง_การ invoke_: เมื่อคำเดียวกันอยู่ทั้งใน prompt เอกสาร และ code ของคุณ agent จะโยงภาษาที่ใช้ร่วมกันนั้นเข้ากับ skill และเรียกมันได้แม่นยำขึ้น

ล่าโอกาส refactor skill ให้ใช้ leading word อยู่เสมอ ชุดคุณสมบัติสามคำที่ถูกสะกดออกมาสามจุด (duplication) description ที่เปลืองทั้งประโยคเพื่อชี้ๆ ไปที่ idea เดียว — แต่ละอันคือข้อความที่ร้องขอให้ถูก collapse เป็น token เดียว ตัวอย่างเช่น:

  • "fast, deterministic, low-overhead" -> tight — คุณสมบัติเดียวที่ถูกพูดซ้ำตลอดทั้ง phase — ยุบเป็นคำ pretrained คำเดียว (loop ที่ tight)
  • "a loop you believe in" -> red — เปลี่ยน gate ที่คลุมเครือให้เป็น state ที่สังเกตได้แบบ binary (loop จะ red กับ bug นั้น หรือไม่ก็ไม่ red)

คุณชนะสองต่อ: token น้อยลง และ ได้ hook ที่คมขึ้นให้ agent แขวนความคิด ให้ตั้งข้อสันนิษฐานว่าทุก skill กำลังแบกการพูดซ้ำที่ leading word ปลดระวางได้ — ไปหามันให้เจอ

Failure modes

ใช้รายการนี้วินิจฉัยปัญหาที่ user อาจเจอกับ skill

  • Premature completion — จบ step ก่อนที่มันจะเสร็จจริง ความสนใจไถลไปอยู่ที่_การได้เสร็จ_ วิธีป้องกันตามลำดับ: ลับ completion criterion ให้คมก่อน (ถูกและแก้เฉพาะจุด); เฉพาะเมื่อมันคลุมเครือจนลดทอนไม่ได้แล้ว และ คุณเห็นอาการรีบจริง ค่อยซ่อน post-completion steps ด้วยการ split (การตัดตาม sequence)
  • Duplication — ความหมายเดียวกันอยู่มากกว่าหนึ่งที่ เปลืองทั้ง maintenance และ token และดันความเด่นของความหมายนั้นบนบันไดให้สูงเกินอันดับจริง
  • Sediment — ชั้นตะกอนเก่าที่ทับถมเพราะการเพิ่มรู้สึกปลอดภัยแต่การลบรู้สึกเสี่ยง ชะตากรรม default ของ skill ที่ไม่มีวินัยการ prune
  • Sprawl — skill ที่ยาวเกินไปเฉยๆ แม้ทุกบรรทัดจะยังสดและไม่ซ้ำกัน ทำร้ายทั้งความอ่านง่าย ความ maintain ง่าย และเปลือง token ทางแก้คือบันได: disclose reference ไปไว้หลัง pointer และ split ตาม branch หรือ sequence เพื่อให้แต่ละเส้นทางแบกเฉพาะสิ่งที่ตัวเองต้องใช้
  • No-op — บรรทัดที่ model ทำตามอยู่แล้วโดย default คุณจึงจ่าย load เพื่อพูดสิ่งที่ไม่เปลี่ยนอะไรเลย วิธีทดสอบ: มันเปลี่ยนพฤติกรรมเทียบกับ default ไหม? leading word ที่อ่อน (be thorough ทั้งที่ agent ก็ค่อนข้าง thorough อยู่แล้ว) คือ no-op ทางแก้คือคำที่แรงกว่า (relentless) ไม่ใช่เปลี่ยนไปใช้เทคนิคอื่น
  • Negation — การบังคับทิศทางด้วยข้อห้ามให้ผลย้อนศร: don't think of an elephant เอ่ยชื่อช้างและทำให้มันเด่นขึ้นในหัว ไม่ใช่จางลง จง prompt ด้านบวก — ระบุพฤติกรรมเป้าหมายเพื่อไม่ต้องเอ่ยถึงพฤติกรรมต้องห้ามเลย เก็บข้อห้ามไว้เฉพาะกรณี guardrail แข็งๆ ที่เขียนเป็นบวกไม่ได้จริงๆ และถึงตอนนั้นก็ต้องจับคู่กับสิ่งที่ให้ทำแทนเสมอ

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.