SNNN-011/skill-authoring

Skill Authoring

Panduan membuat skill yang benar-benar mengubah perilaku agent, bukan dokumen yang tidak pernah dibaca.

Prinsip utama: skill adalah instruksi operasional, bukan artikel. Kalau agent tidak melakukan hal berbeda setelah memuat skill ini, skill itu gagal.

Cara Memakai Skill Ini

Skill ini dipakai dengan percakapan, bukan sekali jalan. Alurnya:

1. User memicu skill (contoh: "pakai skill skill-authoring, saya mau bikin skill untuk agent saya").
2. Agent berhenti menulis dan mulai wawancara Langkah 1: satu pertanyaan per giliran, tunggu jawaban.
3. Setelah kelima pertanyaan terjawab, agent menjalankan Langkah 2 sampai 5 dan menunjukkan draf ke user.
4. Setelah user setuju, agent menulis file (Langkah 6), lalu menjalankan uji trigger (Langkah 7) dan checklist (Langkah 8).

Aturan untuk agent:

• Jangan menulis SKILL.md sebelum kelima pertanyaan Langkah 1 terjawab. Draf dini membuat wawancara berhenti.
• Jangan mengajukan kelima pertanyaan sekaligus. Satu per giliran, dengan contoh singkat di tiap pertanyaan.
• Kalau user hanya ingin "contoh cepat", tetap tanyakan pertanyaan 1 dan 4 saja, lalu lanjut.
• Sebutkan di awal bahwa hasil akhirnya satu file SKILL.md yang bisa langsung dipakai.

Kapan Skill Ini Aktif

• User berkata "bikin skill", "buat skill", "cara bikin skill", "skill untuk agent saya".
• User punya ide kemampuan agent tapi bingung menuangkannya.
• Skill yang sudah ada tidak pernah terpicu atau tidak diikuti agent.
• Perlu memutuskan: ini harus jadi skill, agent, command, atau hook?

Untuk mencari skill yang sudah ada, pakai skill-scout lebih dulu. Untuk mengaudit skill yang sudah menumpuk, pakai skill-stocktake.

Langkah 0 - Aturan Dasar Sebelum Menulis

Skill yang baik punya empat sifat:

Sifat	Artinya
Spesifik	Menjawab satu jenis pekerjaan, bukan "semua hal tentang backend"
Operasional	Berisi langkah, perintah, contoh nyata, bukan teori
Terpicu	description memuat kata yang benar-benar dipakai user
Terbatas	Di bawah 500 baris; idealnya 100-250 baris

Kalau ide skill tidak memenuhi empat ini, perbaiki dulu idenya, jangan tulis file.

Langkah 1 - Tangkap Masalah Nyata, Bukan Fitur

Jangan mulai dari "skill untuk testing". Mulai dari kegagalan konkret.

Ajukan lima pertanyaan ini ke user (satu per satu, jangan sekaligus):

1. Apa yang agent lakukan salah atau tidak konsisten sekarang? Beri satu contoh nyata.
2. Kapan kejadian itu? (menulis kode, review PR, deploy, menjawab user, menganalisis data)
3. Seperti apa hasil yang benar? Tunjukkan satu contoh output yang user anggap bagus.
4. Informasi apa yang agent tidak tahu dan harus diberi tahu lewat skill ini? (konvensi tim, urutan langkah, jebakan)
5. Apa yang tidak boleh dilakukan agent saat menjalankan skill ini?

Jawaban nomor 4 dan 5 adalah isi skill sebenarnya. Jawaban nomor 1 dan 2 adalah isi description.

Kalau user tidak bisa menjawab nomor 1, hentikan proses. Belum ada skill yang perlu dibuat - yang ada hanya keinginan. Katakan itu.

Langkah 2 - Pilih Bentuk yang Tepat

Jangan semua hal dijadikan skill. Pilih bentuk paling murah yang menyelesaikan masalah.

Kebutuhan	Bentuk	Alasan
Pengetahuan/konvensi yang dipakai berulang saat menulis kode	Skill	Dimuat otomatis, tidak perlu dipanggil
Pekerjaan mandiri multi-langkah dengan konteks terpisah	Agent	Bisa dijalankan paralel, punya konteks sendiri
Aksi yang user picu secara sadar dengan argumen	Command	/{nama} eksplisit, bukan otomatis
Perilaku otomatis pada event (sebelum commit, setelah edit)	Hook	Berjalan tanpa keputusan model
Aturan pendek yang berlaku di semua pekerjaan	Rule	Selalu aktif, tanpa trigger
Penjelasan panjang untuk dibaca manusia	Dokumen	Tidak perlu dimuat agent

Aturan praktis:

• Butuh trigger? Skill.
• Butuh konteks terpisah atau tool terbatas? Agent.
• Butuh dipanggil manual dengan parameter? Command.
• Butuh berjalan tanpa diminta? Hook.
• Butuh selalu benar, tidak pernah dilanggar? Rule.
• Butuh dibaca manusia, bukan agent? Dokumen.

Kalau ragu antara skill dan rule: kalau isinya kurang dari 10 baris dan berlaku di mana saja, itu rule.

Langkah 3 - Cari Duplikat Dulu

Sebelum menulis, cari dulu. Folder skill berbeda per harness - sesuaikan dengan milik user:

Harness	Folder skill
Claude Code	~/.claude/skills/ atau .claude/skills/ di proyek
OpenCode	~/.config/opencode/skills/ atau .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# skill yang sudah terpasang (ganti <folder-skill> sesuai tabel di atas)
grep -ril "kata-kunci" <folder-skill> --include=SKILL.md

# kalau sedang berada di dalam repo yang punya folder skills/
grep -ril "kata-kunci" skills --include=SKILL.md

Kalau user tidak tahu folder skill-nya, jelaskan tabel di atas dan minta dia memilih harness yang dipakai. Jangan menebak.

Kalau sudah ada padanan dekat, pilih: pakai apa adanya, perluas yang ada, atau buat baru. Skill duplikat membuat agent bingung memilih dan membebani konteks.

Langkah 4 - Tulis description (Bagian Paling Menentukan)

description adalah satu-satunya bagian yang dibaca agent untuk memutuskan memuat skill atau tidak. Salah di sini berarti skill mati.

Formula:

[aktivitas yang dikerjakan] + [konteks pemicu] + [kata kunci yang dipakai user] + [kapan TIDAK dipakai]

Contoh buruk:

description: Membantu dengan testing

Contoh baik:

description: Pola pengujian React dengan Vitest dan Testing Library - render, event pengguna, mock network, dan assertion aksesibilitas. Gunakan saat menulis atau memperbaiki test komponen React. Bukan untuk E2E (pakai e2e-testing).

Aturan:

• Sebut kata yang benar-benar diketik user, bukan istilah internal.
• Sebut batasnya supaya skill tidak menyerobot pekerjaan skill lain.
• Satu baris, tanpa baris baru di dalam string.
• Hindari kata generik tunggal seperti "kode", "bantuan", "berbagai".

Uji cepat: tutup file, baca hanya description. Kalau kamu sebagai agent tidak tahu persis kapan memuatnya, tulis ulang.

Langkah 5 - Susun Isi

Urutan bagian yang terbukti bekerja:

---
name: nama-skill
description: <formula di Langkah 4>
metadata:
  origin: ECC
---

# Judul

Satu paragraf: apa yang skill ini ubah dari perilaku agent.

## Kapan Aktif
Daftar pemicu konkret.

## Inti
Langkah kerja, tabel keputusan, atau aturan. Ini 70% isi skill.

## Contoh
Satu contoh salah, satu contoh benar. Nyata, bukan placeholder.

## Anti-Pattern
Kesalahan yang harus dihindari, dengan alasan singkat.

## Checklist
Kotak centang yang bisa diverifikasi.

## Skill Terkait
Dua sampai empat nama skill.

Aturan penulisan isi:

• Kalimat perintah ("Lakukan X"), bukan deskripsi pasif ("X dapat dilakukan").
• Tabel untuk keputusan, daftar bernomor untuk urutan, blok kode untuk perintah.
• Setiap aturan harus bisa diverifikasi - "tulis kode bersih" tidak bisa, "fungsi maksimal 50 baris" bisa.
• Tanpa placeholder seperti [isi di sini], TODO, atau ... di bagian yang dijalankan agent.
• Tanpa identitas produk eksternal yang disalin mentah - ambil idenya, tulis ulang dengan konteks sendiri.
• Tanpa rahasia: API key, token, path pribadi absolut, nama internal perusahaan.

Batas panjang: 500 baris (maksimum keras 800). Kalau lebih, pecah jadi dua skill atau pindahkan detail ke references/ di folder skill yang sama.

Langkah 6 - Tulis File

Sebelum menulis, tanyakan dua hal terakhir:

1. Bahasa skill - bahasa yang dipakai user sehari-hari, atau Inggris untuk portabilitas? Ikuti jawabannya, jangan asal pilih.
2. Nama folder - usulkan nama kebab-case yang deskriptif (contoh: test-komponen-react), minta persetujuan.

Lalu tulis ke <folder-skill>/<nama>/SKILL.md. Aturan yang tidak boleh dilanggar:

• name: di frontmatter sama persis dengan nama folder. Tanpa ini, sebagian harness menolak memuat skill.
• Tampilkan draf lengkap ke user dulu, baru simpan. Jangan simpan diam-diam.
• Tidak ada placeholder (TODO, [isi di sini], ...) di bagian yang akan dijalankan agent.
• Setelah menyimpan, laporkan path lengkapnya dan satu kalimat cara memicu: "Setelah ini, minta agent memakai skill <nama> saat ."

Langkah 7 - Uji Sebelum Dipakai

Tiga uji minimal. Jangan lewati salah satu.

Uji 1 - Trigger positif (menyalakan) Beri agent tugas yang seharusnya memicu skill ini, tanpa menyebut nama skill.

"Tolong tulis test untuk komponen LoginButton."

Lulus kalau skill termuat. Gagal berarti description kurang kata kunci.

Uji 2 - Trigger negatif (tidak menyalakan) Beri tugas yang mirip tapi bukan domainnya.

"Tolong tulis test E2E untuk alur login."

Lulus kalau skill TIDAK termuat (atau agent memilih skill lain yang tepat). Gagal berarti description terlalu luas.

Uji 3 - Eksekusi Minta agent mengerjakan tugas yang benar-benar memicu skill, lalu bandingkan outputnya dengan tanpa skill.

Tanpa skill: agent menulis test gaya X
Dengan skill: agent menulis test gaya Y (sesuai konvensi tim)

Lulus kalau ada perbedaan perilaku yang bisa ditunjukkan. Kalau output identik, skill tidak berguna - hapus atau gabungkan.

Langkah 8 - Checklist Siap Kirim

• File berada di <folder-skill>/{nama}/SKILL.md, dan name: sama persis dengan nama folder
• description satu baris, memuat kata kunci user dan batas cakupan
• description tidak memakai blok literal (|), hanya string sebaris
• Ada bagian "Kapan Aktif" yang eksplisit
• Setiap aturan bisa diverifikasi, tidak ada "tulis kode yang baik"
• Ada minimal satu contoh salah dan satu contoh benar
• Ada anti-pattern
• Di bawah 500 baris
• Tidak ada secret, token, atau path pribadi absolut
• Uji 1, 2, dan 3 sudah dijalankan dan dicatat hasilnya
• Langkah 3 sudah dijalankan, tidak ada duplikat
• Menyebut 2-4 skill terkait di bagian akhir

Validasi otomatis hanya kalau memang tersedia di repo user:

# ECC / repo yang punya validator skill
node scripts/ci/validate-skills.js

Kalau tidak ada validator, cek manual empat hal yang paling sering gagal: name: cocok dengan folder, description sebaris, baris di bawah 500, dan tidak ada placeholder. Sebutkan ke user bahwa pengecekan manual ini yang dipakai.

Template Siap Pakai

---
name: nama-skill
description: <aktivitas> - <cakupan>. Gunakan saat <pemicu konkret>. Bukan untuk <di luar cakupan>.
metadata:
  origin: ECC
---

# Nama Skill

Apa yang berubah pada perilaku agent setelah skill ini dimuat.

## Kapan Aktif
- <pemicu 1>
- <pemicu 2>

## Langkah
1. <langkah pertama yang bisa langsung dikerjakan>
2. <langkah kedua>
3. <verifikasi>

## Contoh
Salah: <kode atau jawaban yang sering muncul>
Benar: <versi yang diinginkan, dengan alasan singkat>

## Anti-Pattern
- <kesalahan> - <kenapa buruk>

## Checklist
- [ ] <yang bisa dicek mesin atau mata>

## Skill Terkait
- `<skill-a>`, `<skill-b>`

Anti-Pattern Authoring

• Skill tanpa trigger. description samar, skill tidak pernah termuat. Ini penyebab kegagalan paling umum.
• Skill dinding teks. 900 baris teori tanpa satu perintah. Agent memuatnya lalu mengabaikannya.
• Skill "jadilah membantu". Tanpa pengetahuan spesifik, hasilnya identik dengan tanpa skill.
• Skill duplikat. Dua skill mengklaim domain sama; agent memilih acak.
• Menyalin skill orang lain utuh. Termasuk instruksi tersembunyi dan dependensi yang tidak kamu sadari.
• Skill dengan secret atau path pribadi. Ikut tersebar saat skill dibagikan.
• Menulis skill untuk satu kejadian. Kalau hanya dipakai sekali, itu bukan skill - itu dokumentasi atau command.
• Membuat skill sebelum mencari. Selalu jalankan Langkah 3.

Kapan Skill TIDAK Perlu Dibuat

Katakan terus terang ke user bila salah satu ini benar:

• Masalahnya bug di kode, bukan kurang pengetahuan agent.
• Butuh satu kali jalan saja - cukup beri instruksi langsung.
• Isinya kurang dari 10 baris aturan umum - itu rule.
• Cukup ditambahkan ke AGENTS.md atau CLAUDE.md proyek.
• Sudah ada skill yang mencakup 80% kebutuhan - perluas yang ada.

Skill Terkait

• skill-scout - mencari skill yang sudah ada sebelum membuat baru
• skill-stocktake - mengaudit kualitas skill yang menumpuk
• skill-comply - mengukur apakah skill benar-benar diikuti agent
• agent-harness-construction - merancang tool dan batas aksi agent