บทที่ 4: Commands & Skills¶
สองอย่างนี้หน้าตาคล้ายกัน (Markdown + frontmatter) แต่ คนละบทบาทโดยสิ้นเชิง
| Commands | Skills | |
|---|---|---|
| ใครเรียก | คุณ พิมพ์ /review |
โมเดล เรียกเองเมื่อเห็นว่าเกี่ยว |
| เก็บที่ | commands/<name>.md |
skills/<id>/SKILL.md |
| เนื้อหา | prompt template (แทนที่ด้วย argument) | คำสั่ง/ขั้นตอนทำงาน + ไฟล์ประกอบ |
| โหลดเมื่อ | ตอนคุณเรียก | ตอนโมเดลขอ (skill tool) |
| ใช้ทำ | งานที่ทำซ้ำและอยากเรียกสั้น ๆ | องค์ความรู้ที่อยากให้โผล่เมื่อจำเป็น |
จำง่าย ๆ: command = ทางลัดของคน / skill = ความรู้ของ agent
ส่วนที่ 1: Commands¶
1.1 ของที่มีอยู่จริงบนเครื่องนี้¶
3 commands
- init | guided AGENTS.md setup
- review | review changes [commit|branch|pr], defaults to uncommitted
- goal | keep working until an objective is met [pause|resume|clear]
ทั้งสามเป็น built-in — ถ้าคุณสร้าง ~/.config/opencode/commands/review.md จะ ทับ built-in ตัวนั้นทันที
1.2 รูปแบบ Markdown (แนะนำ)¶
<!-- ~/.config/opencode/commands/review.md -->
---
description: ตรวจโค้ดที่แก้ล่าสุด
agent: plan
---
ตรวจ $ARGUMENTS หาบั๊กและ test ที่ขาด รายงานบั๊กก่อน
- body = template (ห้ามใส่
templateใน frontmatter) - วางที่
~/.config/opencode/commands/(global) หรือ.opencode/commands/(โปรเจกต์) - path ซ้อน → ชื่อมี
/:.opencode/commands/team/review.md→/team/review - โฟลเดอร์
command/(เอกพจน์) ยังถูกค้นหา แต่ใช้commands/สำหรับไฟล์ใหม่
1.3 Arguments 4 แบบ¶
| แบบ | ตัวอย่าง invocation | ผลลัพธ์ |
|---|---|---|
$ARGUMENTS |
/review src/auth.ts |
ทั้งสตริงดิบ src/auth.ts |
$1, $2 |
/check src/auth.ts "error handling" |
src/auth.ts / error handling (quote ถูกถอด) |
| position สูงสุด | /compare api stable branch (template Compare $1 with $2) |
Compare api with stable branch |
| ไม่มี placeholder | /explain src/cache.ts |
ต่อท้ายหลังบรรทัดว่างให้อัตโนมัติ |
รายละเอียดสำคัญ: position สูงสุดกิน arguments ที่เหลือทั้งหมด และ position ที่ไม่มีจะกลายเป็นสตริงว่าง
1.4 Shell block — ทรงพลังและอันตราย¶
! + backtick = รันคำสั่ง shell แล้วแทรก output ก่อนส่ง prompt (argument ถูกแทนก่อน shell รัน)
⚠️ อันตราย: shell block รัน นอก permission flow ของ agent — คือ ไม่ถาม ตามกฎ
shellที่เราตั้งในบทที่ 2 และ ห้ามใส่ argument ที่ไม่น่าเชื่อถือลงใน shell block (/history $1กับgit log -$1= command injection)
1.5 Fields ทั้งหมด¶
| Field | ค่า | หมายเหตุ |
|---|---|---|
description |
string | โชว์ในรายการ command |
agent |
agent id | สลับ agent ก่อน ส่ง prompt เช่น plan |
model |
provider/model#variant |
ทับทุกอย่าง (ดูกฎข้อ 1.7) |
subagent |
true/false |
true = รันใน child session เบื้องหลัง |
subtask |
— | deprecated alias ของ subagent (ถ้าใส่ทั้งคู่ subagent ชนะ) |
ใน JSON config ใช้ commands.<name> และ ต้องมี template:
{
"commands": {
"audit": {
"template": "Audit $ARGUMENTS.",
"agent": "general",
"subagent": true
}
}
}
1.6 Background (subagent: true)¶
| ค่า | พฤติกรรม |
|---|---|
true |
ใช้ child เสมอ แม้ agent นั้นเป็น primary |
false |
ใช้ session ปัจจุบันเสมอ แม้ agent เป็น subagent |
| ไม่ระบุ | ใช้ child เฉพาะเมื่อ agent ที่เลือกมี mode: subagent |
โมเดลของ child: command.model → agent.model → parent.model
1.7 กฎการเลือกโมเดล (เรียงตามสิทธิ์)¶
modelของ command ชนะทุกอย่าง- ถ้าไม่มี → โมเดลของ agent ที่ command เลือก
- ถ้าไม่มีอีก → โมเดลของ session ปัจจุบัน
1.8 กับดัก¶
@pathใน template ไม่ถูกขยาย — มันเป็นข้อความธรรมดา ต้องแนบไฟล์ผ่าน composer ตอนเรียก- โปรเจกต์ทับ global และไฟล์ที่ใกล้กว่าทับไฟล์ที่ไกลกว่า
- แก้ไฟล์แล้วมีผลทันที ไม่ต้อง restart
ส่วนที่ 2: Skills¶
2.1 ของจริงบนเครื่องนี้¶
opencode api get /api/skill
# 18 skills — opencode, report, brainstorming, systematic-debugging, ...
สังเกตว่า 14 ตัวมาจาก ปลั๊กอิน Superpowers ที่เราเพิ่งติดตั้ง ไม่ได้อยู่ใน ~/.config/opencode/skills เลย — นี่คือบทเรียนสำคัญ: skill มาจากได้ 3 ทาง คือ ไฟล์ / config skills / plugin
2.2 โครงสร้าง¶
.opencode/skills/
└── git-release/
├── SKILL.md
├── scripts/changelog.ts
└── references/release-policy.md
---
name: Git Release
description: Prepare release notes, version bumps, and GitHub releases
---
## Workflow
1. อ่าน `references/release-policy.md`
2. สรุปการเปลี่ยนแปลงตั้งแต่ tag ก่อนหน้า
3. เสนอ version bump ก่อนแก้ไฟล์
- path ที่เขียนใน skill relative กับโฟลเดอร์ของ
SKILL.md - รองรับ 2 แบบ:
skills/review.md(flat) หรือskills/<id>/SKILL.md(directory — แนะนำ เพราะมี base dir ให้ไฟล์ประกอบ) - ชื่อไฟล์ต้องเป็น
SKILL.mdเป๊ะ ๆ และ ไม่ค้นลึกเข้าไปในโฟลเดอร์ที่มีSKILL.mdแล้ว
2.3 ค้นหาอัตโนมัติจากที่ไหน¶
| Scope | ที่อยู่ |
|---|---|
| Global | ~/.config/opencode/skills |
| Global (compat) | ~/.claude/skills, ~/.agents/skills |
| Project | .opencode/skills |
| Project (compat) | .claude/skills, .agents/skills |
Project scope ไล่จาก cwd ขึ้นไปถึง project root, ข้าม hidden/node_modules, ลึกสุด 6 ชั้น
2.4 ID มาจาก path ไม่ใช่ name¶
| ไฟล์ | ID |
|---|---|
<source>/git-release.md |
git-release |
<source>/git-release/SKILL.md |
git-release |
<source>/teams/release/SKILL.md |
release |
ID case-sensitive และควรเป็น kebab-case — ถ้า skill "ไม่เจอ" ให้สงสัยข้อนี้ก่อนเสมอ (เช่น name: Git Release แต่ ID คือ release)
2.5 Frontmatter ที่มีผลจริง¶
| Field | ผล |
|---|---|
description |
ใช้โชว์ให้โมเดลเห็น — ไม่มี description = ไม่ถูกโฆษณา |
name |
แค่ชื่อแสดงผล |
metadata.opencode/autoinvoke: false |
ซ่อนจากรายการของโมเดล แต่ยังโหลดด้วย ID ได้ |
disable-model-invocation: true |
ผลเดียวกับข้างบน (ถ้าใส่ทั้งคู่ ตัวบนชนะ) |
2.6 ลำดับความสำคัญ (ต่ำ → สูง)¶
1. built-in skills
2. .claude/skills
3. .agents/skills
4. ~/.config/opencode/skills
5. project .opencode/skills (ใกล้ cwd ชนะ)
6. skills ที่ประกาศใน config (ตามลำดับ array)
2.7 กลไกโหลด (เข้าใจแล้วจะ debug ง่ายมาก)¶
ทุก step ของโมเดล:
OpenCode ส่งรายการ skill ที่อนุญาต → แค่ [ID, name, description]
(ไม่ส่งเนื้อหา!)
โมเดลเห็นว่าเกี่ยว → เรียก skill tool { id: "..." }
→ ตรวจ permission action "skill"
→ แทรก body (ตัด frontmatter)
→ ให้ base dir + path ของไฟล์ประกอบสูงสุด 10 ไฟล์
ไฟล์ประกอบ ไม่ถูกโหลดอัตโนมัติ — agent ต้อง read เองตามที่ skill สั่ง
คุณโหลดเองได้ด้วยการพิมพ์ @skill-id ใน prompt
2.8 Permission ของ skill (ต่อจากบทที่ 2)¶
{
"permissions": [
{ "action": "skill", "resource": "*", "effect": "allow" },
{ "action": "skill", "resource": "internal-*", "effect": "deny" },
{ "action": "skill", "resource": "experimental-*", "effect": "ask" }
]
}
| Effect | ผล |
|---|---|
allow |
โฆษณา + โหลดได้เลย |
ask |
โฆษณา แต่ถามก่อนโหลด |
deny |
ซ่อนจากโมเดล + ปฏิเสธการโหลด |
2.9 กับดัก¶
- ชื่อโฟลเดอร์ ≠ ID ถ้าใช้
SKILL.md— ID คือชื่อโฟลเดอร์ ไม่ใช่nameใน frontmatter - ไม่มี description = มองไม่เห็น (แต่ยังโหลดด้วย
@idได้) SKILL.mdต้องตัวพิมพ์ใหญ่เป๊ะ —skill.mdไม่ถูกค้น- ID ซ้ำ = ตัวหลังชนะ — ระวังตอนติดตั้ง plugin ที่มี skill ชื่อชนของเดิม
- HTTP catalog ต้องมี
index.jsonและเพิ่มversionเมื่อไฟล์เปลี่ยน ไม่งั้น cache ค้าง
แบบฝึกหัด 3 ข้อ¶
# 1) ดู command ที่ลงทะเบียนอยู่ (ก่อน/หลังสร้างไฟล์)
opencode api get /api/command
# 2) สร้าง command ง่าย ๆ แล้วดูว่ามันโผล่ทันที
mkdir -p ~/.config/opencode/commands
printf -- '---\ndescription: อธิบายโค้ดสั้น ๆ\n---\n\nอธิบาย $ARGUMENTS แบบสั้น กระชับ\n' \
> ~/.config/opencode/commands/explain.md
opencode api get /api/command | grep -o '"explain"'
# 3) ดูว่า skill แต่ละตัวมี description ไหม (ตัวไม่มี = โมเดลมองไม่เห็น)
opencode api get /api/skill | python3 -c '
import json,sys
for s in json.load(sys.stdin)["data"]:
print(("OK " if s.get("description") else "NO ") + s["id"])
'