# Skill0 Writer

> ข้อตกลงการเขียนสำหรับเอกสาร skill0 — โครงสร้างพีระมิด ข้อจำกัดจำนวนบรรทัด และกฎการจัดวาง

- Skill: `x-cmd/skill0-writer-17` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add x-cmd/skill0-writer-17`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/skill0-writer-17/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/x-cmd/skill0-writer-17

---


# skill0-writer

เอกสาร skill0 ใช้ **หลักการพีระมิด**: agent อาจอ่านแค่ 10–30 บรรทัดแรกเท่านั้น ข้อมูลสำคัญที่สุดจึงต้องมาก่อน รายละเอียดหลังบรรทัดที่ 30 เป็นของแถม ไม่ใช่ภาระที่ต้องแบกรับ

## สิ่งที่ไม่มีกฎใดจับได้

- **ชัดเจนสำคัญกว่าสั้น** เอกสารสั้นที่ตอบผิดแย่กว่าเอกสารยาวที่ตอบถูก
- **คำเตือนด้านความปลอดภัย/ความเสี่ยง ต้องเขียนให้ชัดเจน** — ใช้ MUST, NEVER, DO NOT เขียนข้อควรระวังเป็นประโยคเต็ม ไม่ใช่วงในวงเล็บ
- **อย่าอธิบายสิ่งที่เป็นความรู้สามัญเกินจำเป็น** ถ้าคำที่บอกข้อตกลงแล้วบวกประโยคหนึ่งสองประโยคก็สื่อครบแล้ว ให้หยุด ผู้อ่านรู้อยู่แล้วว่า YAML, git และ cache คืออะไร ใช้บริบทกับสิ่งที่เฉพาะเจาะจง repo นี้แทน เหตุผลของกฎมักเป็นตัวกระทำผิดที่พบบ่อยที่สุด — ให้เหตุผลของกฎเฉพาะเมื่อมันดูผิดไปหากไม่มีเหตุผล (`sw-1200`)
- **ใช้ตารางเฉพาะเมื่อเป็นเมทริกซ์จริง** ต้องมี 3 คอลัมน์ขึ้นไปและแต่ละแถวต้องอ่านเทียบกัน ตารางสองคอลัมน์คือรายการที่สวมไว้ด้วยไวยากรณ์ตาราง — เขียนเป็นรายการแทน ชุดข้อมูลควรอยู่ในไฟล์ `.tsv` ภายนอกข้าง ๆ เอกสาร แล้วลิงก์เข้ามา เพื่อให้ `x tsv` ค้นหาได้ (`sw-1250`)

## YFM — เฉพาะ `SKILL.md`

```yaml
---
name: <slug>                  # ต้องเหมือนชื่อไดเรกทอรี
description: <สรุป 1-2 ประโยคที่ agent ใช้ตัดสินว่าจะโหลดหรือไม่>
---
```

`name` และ `description` คือส่วนที่สำคัญ ส่วนที่เหลือซ้อนอยู่ในบล็อก `metadata:` ตามข้อตกลงของ [yfm](../yfm/SKILL.md) เป็นสเกลาร์คั่นด้วยจุลภาค — ไม่บังคับ และเพิ่มโครงสร้างสำหรับการทำดัชนี การค้นพบ และจุดเชื่อมต่อ ontology

**ไฟล์ย่อยไม่ต้องมี YFM** เฉพาะ `SKILL.md` เท่านั้นที่ loader กรอง ดังนั้นเฉพาะไฟล์นี้ที่ต้องมี front matter ไฟล์อื่นทุกไฟล์ (`references/*`, `usecase/*`, `EXAMPLE.md`, `*.report.md` …) ถูกอ่านโดยตรงจาก agent ที่ตัดสินใจเปิดมันแล้ว — YFM ในไฟล์เหล่านั้นเป็นต้นทุนโทเคนล้วน ๆ ที่บอกวัตถุประสงค์ซ้ำกับสิ่งที่ชื่อเรื่องและบรรทัดแรกบอกอยู่แล้ว ให้ไฟล์เหล่านั้นเริ่มที่หัวข้อ `#` การฝ่าฝืนต้องระบุเหตุผลไว้ในตัวไฟล์

สำหรับเวอร์ชันภาษาจีน ให้ใช้ `SKILL.cn.md` คู่ขนานกัน (หนึ่งไฟล์ต่อหนึ่งสกิล) ห้ามผสมภาษาในไฟล์เดียวกัน

## การตรวจสอบเชิงกล

อยู่ใน [skill0-writer.rule.yml](skill0-writer.rule.yml) รัน `x rule lint skill0-writer.rule.yml` และ `x rule check -r skill0-writer.rule.yml lib/skill0/` ความครอบคลุม: การมี YFM + ฟิลด์ name/description รูปแบบของ name จำนวนบรรทัด ≤ 100 (เหมาะสมคือ 50) ลำดับหัวข้อ install → usage → advanced → links ภาษาอังกฤษเท่านั้น ไม่มีคำแนะนำนำ/ไม่มีบทสรุป/ไม่มีการซ้ำซาก ไม่มีไฟล์กำพร้า

## การตรวจสอบความปลอดภัยจากการตัดบรรทัด

หลังเขียนเสร็จ ให้ทบทวนที่บรรทัดที่ 30: agent ที่หยุดอ่านตรงนี้จะเข้าใจผิดหรือไม่?

ถ้าผิด ให้ย้ายข้อกำกัดที่สำคัญขึ้นมาก่อน 30 บรรทัดต้องให้แบบจำลองทางจิตที่ถูกต้อง (แม้ไม่ครบถ้วน) หลังบรรทัดที่ 30 ค่อยขยายด้วยรายละเอียด — พีระมิดแก้ตัวเองได้

## การโหลดสองชั้น: description สำหรับจับคู่ เนื้อหาสำหรับอ้างอิง

ตัวโหลดสกิล (Claude Code, Cursor, Continue ฯลฯ) โหลด SKILL.md เป็นสองจังหวะ:

  1. **`description:` ใน YFM** — โหลดเข้าแคตตาล็อกของ agent โดยอัตโนมัติ
     เพื่อการจับคู่ agent อ่านคำอธิบายเพื่อตัดสินว่าจะโหลด
     สกิลหรือไม่
  2. **เนื้อหา** — โหลดตามต้องการหลังจับคู่ได้ เป็นสาระอ้างอิง

ผลที่ตามมา:

- **description** = *คืออะไร + เมื่อไรควรโหลด* — ใส่คำสำคัญเต็ม เป็นตัวกระตุ้น กระชับ
- **เนื้อหา** = *ใช้อย่างไร + สาระอ้างอิง* — ตัวอย่าง schema กรณีเฉพาะ ลิงก์ไปยังเอกสารลึก

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

การทดสอบในทางปฏิบัติ: ถ้าลบ description ทิ้งทั้งหมดแล้วอ่านเฉพาะ 30 บรรทัดแรกของเนื้อหา agent ก็ยังควรเห็นว่าสกิลนี้ทำอะไรและควรโหลดเมื่อไร ถ้าข้อมูลนั้นมีอยู่แค่ใน description เนื้อหาก็ไม่มีอะไรมาเพิ่มไว้ด้านบน — ให้ย้ายคำอธิบายเข้าเนื้อหาและปล่อยให้ description ถือพาดหัว

## สกิลคือชุดความรู้ ไม่ใช่บทเรียน

เนื้อหาของสกิลคือ **การบรรยายสภาพให้ LLM** ไม่ใช่หลักสูตรสำหรับมือใหม่

- **ความสามารถ** อยู่ที่ LLM เนื้อหาไม่สอน
- **ความรู้** อยู่ที่เครื่องมือข้อมูลของ x-cmd (`x wkp` / `x rfc` / `x cve`, NVD / MITRE / GHSA) และแหล่งภายนอก เนื้อหาทำหน้าที่ชี้ แล้วให้ agent ดึงข้อมูลใหม่เอง
- **การตีกรอบ** คือหน้าที่ของสกิล: ระบุรูปร่างของปัญหา ข้อตกลง รูปแบบผลลัพธ์ที่มีโครงสร้าง และเครื่องมือ x-cmd ที่จะใช้

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

เมื่อรายละเอียดละเอียดเกินไปหรือเปลี่ยนเร็วเกินไป ให้ย้ายไปไฟล์แนบแยก (`references/`, `ANALYTICS.md`) หรือเอกสารภายนอกที่อัปเดตเสมอ

## ลิงก์ภายนอก

รวบรวมสองประเภท: **ลิงก์ราก** (จุดเข้า เช่น `llms.txt`, ดัชนีเอกสาร) และ **ลิงก์ที่มีประโยชน์** (ลิงก์เจาะจงสำหรับ 20% ของเอกสารที่ครอบคลุม 80% ของกรณีใช้งาน) เรียงลิงก์รากก่อน แล้วค่อยลิงก์ที่มีประโยชน์ — AI เข้าใจลำดับ **ห้ามทำซ้ำ** เว้นแต่จุดที่ต้องเน้นเป็นพิเศษ

## ข้อควรระวังแบบอ่อน (เรื่องที่ต้องตัดสินใจเอง)

- **ไฟล์ย่อย (CLEANUP.md, references/*)** ยาวได้มากกว่า SKILL.md แต่ 20 บรรทัดแรกก็ยังต้องแบกของหลักได้ (พีระมิดเหมือนกัน)
- **ต้อง** ลิงก์ไปยังไฟล์ย่อยทุกไฟล์จาก SKILL.md แม่ของมัน (ต้องมี forward link) การลิงก์ย้อนกลับจากไฟล์ย่อยไปยัง SKILL.md เป็น **ไม่บังคับ** — ไฟล์ usecase อ้างอิงแม่โดยอ้อมทางเส้นทางอยู่แล้ว บังคับใช้โดย `sw-1000-no-orphan-docs` ใน [skill0-writer.rule.yml](skill0-writer.rule.yml)
- **การคาดเดา** — ถ้าบอกข้อเท็จจริงที่ทดสอบแล้ว ให้บอกได้ ถ้าไม่ ให้ติดป้ายว่า "ยังไม่ได้ทดสอบ"
- **อีโมจิ** เว้นแต่หัวข้อของสกิลจำเป็นต้องใช้

## ที่เกี่ยวข้อง

- [yfm](../yfm/SKILL.md) — ข้อตกลง YFM ที่ skill0-writer บังคับใช้เป็นชั้นที่ 1
- [naming](../naming/SKILL.md) — การตั้งชื่อก็ตามกฎของผู้เขียนเหมือนกัน
- [skill0-writer.rule.yml](skill0-writer.rule.yml) — การบังคับใช้เชิงกล
