Skill Engineering: Ajari AI Agent Pakai SKILL.md

Prompt panjang itu rapuh. Kamu tulis 500 kata instruksi untuk AI agent, berharap dia mengikuti setiap langkah. Hasilnya: agent lupa langkah nomor 3, mengimprovisasi langkah yang tidak ada, atau mencoba pendekatan sendiri yang konflik dengan instruksi. Yang saya butuhkan bukan instruksi sekali pakai, tapi prosedur yang bisa dipanggil ulang — itulah skill engineering dengan SKILL.md.

Artikel ini bukan teori. Saya akan menunjukkan potongan nyata dari file SKILL.md yang mengajari agent saya cara deploy website, dan keputusan desain di balik setiap bagian.

TL;DR:

• Prompt (sekali pakai), tool (mekanisme), dan skill (prosedur persistent) itu tiga hal berbeda — skill engineering menulis yang ketiga
• SKILL.md yang bekerja punya lima bagian: trigger, prasyarat/guard, workflow bernomor, kriteria keberhasilan, penanganan gagal
• Bagian tersulit adalah deskripsi trigger — terlalu luas maka salah panggil, terlalu sempit maka tidak terpanggil
• Skill yang belum diuji adalah hipotesis: uji trigger, uji eksekusi, uji jalur gagal

Prompt, tool, skill: tiga hal yang sering dicampuradukkan

Banyak orang menggunakan ketiganya bergantian. Mereka berbeda:

Prompt adalah instruksi ad-hoc yang kamu ketik ke agent. Sekali pakai, tidak persistent. Kalau kamu mengulang tugas yang sama besok, kamu harus menulis prompt lagi (dan mungkin lupa setengah isinya).

Tool adalah capability yang agent miliki — terminal, file editor, browser. Tools tidak tahu kapan harus dipakai; agent yang memutuskan. Tools tidak berisi prosedur, hanya mekanisme eksekusi.

Skill adalah prosedur persistent yang agent bisa panggil ketika kondisi terpenuhi. Skill berisi: kapan dipakai (trigger), prasyarat apa yang harus dicek, langkah-langkah bernomor, kriteria keberhasilan, dan apa yang dilakukan kalau gagal. Skill adalah cara mengajari agent tugas berulang.

Perbedaan praktis: prompt berumur satu percakapan. Tool ada selamanya tapi tidak punya konteks. Skill ada selamanya dan punya konteks spesifik untuk satu jenis tugas.

Anatomi SKILL.md yang bekerja

Sebuah SKILL.md yang baik punya lima bagian. Berikut template kerangka kosong yang bisa langsung di-copy:

---
name: nama-skill
description: "Satu kalimat: kapan dipakai, apa yang dilakukan."
version: 1.0.0
---

# Judul Skill

## Kapan Dipakai
- Trigger condition yang spesifik
- Tugas yang cocok untuk skill ini

## Prasyarat
- Apa yang harus ada/ada sebelum mulai
- Guard: apa yang harus dicek SEBELUM eksekusi

## Workflow
1. Langkah pertama yang eksplisit
2. Langkah kedua dengan perintah persis
3. Langkah ketiga

## Kriteria Keberhasilan
- Bagaimana agent tahu tugas selesai
- Bukan "sudah dijalankan" tapi hasil yang terverifikasi

## Penanganan Gagal
- Kapan berhenti dan lapor
- Bukan mencoba jalan lain yang tidak ada di workflow

Deskripsi trigger: bagian tersulit

Deskripsi skill menentukan apakah skill kepanggil atau tidak. Agent memindai deskripsi setiap skill di awal percakapan. Kalau deskripsi tidak match dengan apa yang user minta, skill tidak akan dipanggil — bahkan kalau isinya sempurna.

Contoh deskripsi buruk yang pernah saya tulis:

description: "Deploy aplikasi ke server."

Ini terlalu generik. Agent akan memanggilnya untuk hampir apapun yang mengandung kata "deploy" atau "server" — termasuk hal yang tidak relevan.

Versi yang lebih baik:

description: "Use when deploying a dynamic app (WordPress / Laravel / Next.js)
  to a <name>.jayax.dev subdomain on this host. Replaces the 'needs a server
  runtime, propose its own container' dead-end of static-site-publishing."

Deskripsi ini punya: trigger spesifik ("deploying a dynamic app"), framework yang didukung, lokasi target (subdomain jayax.dev), dan kapan TIDAK dipakai ("replaces static-site-publishing"). Agent tahu persis kapan skill ini relevan.

Prasyarat dan guard

Bagian ini mencegah agent menjalankan tugas ketika kondisi tidak terpenuhi. Contoh dari skill deploy:

## Prasyarat
- Docker Desktop harus jalan di host Windows
- Container MariaDB harus aktif
- Cloudflare Tunnel (cloudflared container) harus connected
- Folder /hermes-queue/ harus writable

Agent dicek prasyarat sebelum mulai. Kalau MariaDB mati, agent tidak mencoba deploy — dia lapor "MariaDB tidak aktif, tidak bisa deploy" dan berhenti.

Workflow bernomor: langkah eksplisit, bukan deskripsi tujuan

Langkah yang buruk: "Deploy WordPress ke subdomain." Ini deskripsi tujuan, bukan instruksi. Agent tidak tahu bagaimana mencapainya.

Langkah yang baik:

1. Tulis file perintah ke queue:
   `echo "wsl-deploy wordpress <nama>" > /hermes-queue/deploy-wordpress-<nama>.cmd`
2. Polling untuk result file setiap 10 detik, maksimum 9 kali
3. Baca `/hermes-queue/result-deploy-wordpress-<nama>.txt`
4. Cek baris pertama: `exit=0` = sukses, `exit=1` = gagal
5. Kalau sukses, verifikasi dengan `curl -H "Host: <nama>.jayax.dev" http://site-server/`

Setiap langkah punya perintah persis atau kriteria cek yang objektif. Tidak ada ruang untuk improvisasi.

Kriteria keberhasilan

Skill harus mendefinisikan kapan tugas selesai — bukan "sudah dijalankan" tapi hasil yang terverifikasi:

## Kriteria Keberhasilan
- Result file berisi `exit=0`
- Output berisi `SITE '<nama>' TERDEPLOY`
- `curl -H "Host: <nama>.jayax.dev" http://site-server/` balas 200 atau 302
- Tidak ada error di output

Tanpa kriteria ini, agent bisa melaporkan sukses padahal deploy gagal di tengah.

Penanganan gagal: kapan berhenti dan lapor

## Penanganan Gagal
- Kalau result file tidak muncul dalam 90 detik: timeout, lapor ke user
- Kalau exit code bukan 0: baca output, lapor error spesifik ke user
- Kalau curl balas selain 200/302: deploy mungkin gagal, cek log container
- JANGAN auto-retry. Satu percobaan per request.

"Aturan JANGAN auto-retry" adalah keputusan disain penting. Deploy yang gagal bisa meninggalkan container setengah-configured. Retry bisa memperburuk. Lebih baik laporkan dan biarkan user memutuskan.

Studi kasus: SKILL.md untuk deploy website

Skill deploy nyata yang agent saya pakai mengarahkan agent menggunakan jalur bridge queue, bukan mencoba menjalankan docker langsung. Ini potongan dari workflow:

## Workflow
1. Tentukan jenis app: wordpress | laravel | nextjs
2. Tentukan nama: lowercase [a-z0-9-], 2-31 chars. Reserved: status.
3. Tulis perintah ke bridge queue:
   echo "wsl-deploy <type> <name>" > /hermes-queue/deploy-<type>-<name>.cmd
4. Polling result file (sleep 10, up to 9 tries):
   /hermes-queue/result-deploy-<type>-<name>.txt
5. Baca exit code (baris pertama).
6. Verifikasi HTTP:
   curl -s -o /dev/null -w "%{http_code}" -H "Host: <name>.jayax.dev" http://site-server/

Perhatikan langkah 3: agent menulis ke /hermes-queue/, bukan menjalankan docker compose up. Agent tidak punya akses docker langsung. Skill secara eksplisit mengarahkan ke bridge queue — dan ini disengaja, bukan kebetulan.

Skill ini juga punya batasan yang jelas:

## Batasan
- RAM host: hanya 2-3 dynamic app aktif bersamaan
- Agent TIDAK menjalankan docker compose sendiri
- WordPress install wizard tetap manual setelah deploy
- Tidak ada rollback otomatis kalau deploy gagal di tengah

Kesalahan yang saya buat di versi pertama

Skill deploy versi pertama saya punya empat masalah yang menghasilkan behavior tidak diinginkan:

1. Terlalu abstrak. Versi pertama berisi "deploy website ke subdomain." Agent improvisasi: mencoba menjalankan docker compose langsung, mencoba install WordPress manual lewat WP-CLI, mencoba edit nginx config sendiri. Fix: setiap langkah diberi perintah persis (echo "wsl-deploy..." > /hermes-queue/...).

2. Tidak ada kriteria selesai. Versi pertama tidak mendefinisikan kapan deploy dianggap sukses. Agent melaporkan sukses setelah menulis file .cmd ke queue — padahal deploy belum selesai diproses oleh bridge. Fix: tambah kriteria verifikasi (exit=0, SITE '<nama>' TERDEPLOY, HTTP check).

3. Tidak melarang improvisasi. Versi pertama tidak secara eksplisit melarang agent mencoba alternatif. Saat bridge queue lambat, agent mencoba SSH ke host (yang tidak ada server SSH-nya), mencoba akses docker socket, dll. Fix: tambah aturan eksplisit "JANGAN jalankan docker langsung, JANGAN auto-retry, gunakan hanya bridge queue."

4. Tidak menyebut perintah persis. Versi pertama mengatakan "kirim perintah deploy ke bridge." Agent tidak tahu format perintahnya apa. Kadang dia menulis deploy wordpress blog (tanpa prefix wsl-deploy), yang ditolak bridge. Fix: setiap perintah ditulis persis dengan contoh.

Cara menguji sebuah skill

Skill yang belum diuji adalah hipotesis, bukan tool. Tiga jenis test:

Test trigger. Berikan kalimat yang harus memanggil skill: "deploy WordPress untuk klien baru" → harus terpanggil. Berikan kalimat mirip yang TIDAK harus memanggil: "jelaskan cara kerja WordPress" → tidak boleh terpanggil. Kalau skill terpanggil untuk yang tidak relevan, deskripsi terlalu luas. Kalau tidak terpanggil untuk yang relevan, deskripsi terlalu sempit.

Test eksekusi. Berikan task yang sesuai trigger. Ikuti apakah agent menjalankan setiap langkah workflow dengan benar. Kalau agent skip langkah, langkah itu mungkin terlalu abstrak atau dianggap "sudah jelas."

Test jalur gagal. Sengaja gagalkan salah satu prasyarat (misal: matikan MariaDB). Lihat apakah agent mengikuti penanganan gagal (lapor, berhenti) atau mencoba improvisasi (mencoba start MariaDB sendiri). Skill yang baik menghentikan eksekusi dan melapor.

Kapan sesuatu TIDAK layak jadi skill

Tidak semua tugas layak dijadikan skill. Aturan praktis:

• Tugas sekali pakai → prompt saja. Kalau kamu tidak akan mengulang tugas ini, tidak perlu skill.
• Tugas yang selalu berbeda → prompt. Kalau setiap instance butuh pendekatan unik, skill (yang punya workflow tetap) tidak cocok.
• Tugas yang agent sudah tahu → tidak perlu skill. Agent tidak butuh skill "baca file" — itu tool default.
• Tugas dengan terlalu banyak edge case → terlalu kompleks untuk satu skill. Pecah jadi multiple skill atau tetap manual.

Yang cocok jadi skill: tugas berulang dengan langkah predictable, yang kamu ingin konsisten setiap kali. Deploy website, backup database, restart service, audit SEO — semua kandidat baik.

Langkah berikutnya

Skill deploy yang dibahas di sini adalah bagian dari AI agent yang deploy website otomatis. Detail teknis jalur bridge queue yang dipakai skill ini ada di cara menjalankan perintah Windows dari WSL2.

FAQ

Apakah SKILL.md menggantikan prompt sama sekali?

Tidak. Skill dipakai untuk tugas berulang yang punya prosedur tetap. Prompt tetap dipakai untuk tugas unik, eksplorasi, dan request ad-hoc. Keduanya melengkapi.

Berapa panjang ideal SKILL.md?

Sependek mungkin yang masih lengkap. Skill deploy saya sekitar 180 baris. Kalau skill melebihi 300 baris, kemungkinan terlalu abstrak atau mencakup terlalu banyak hal. Pecah jadi beberapa skill.

Bagaimana agent tahu skill mana yang dipakai?

Agent memindai field description dari semua skill di awal percakapan. Deskripsi yang match dengan request user akan memicu skill. Kalau tidak ada yang match, agent menggunakan pengetahuannya sendiri.

Apakah skill bisa di-update tanpa restart agent?

Ya. Skill dibaca dari filesystem di awal percakapan. Setiap sesi baru akan memuat versi terbaru. Tidak perlu restart container atau daemon.

Kesimpulan

Skill engineering dengan SKILL.md adalah cara mengubah prosedur yang ada di kepala kamu menjadi executable instruction yang agent bisa ikuti. Bagian tersulit bukan menulis langkah-langkah — tapi menulis deskripsi trigger yang tepat, mendefinisikan kriteria keberhasilan yang objektif, dan menahan diri untuk tidak membiarkan agent berimprovisasi.

Mulai dengan satu skill untuk tugas yang paling sering kamu ulang. Tulis, uji trigger, uji eksekusi, uji jalur gagal. Iterasi sampai konsisten. Lalu tambah skill berikutnya.

Untuk memahami bagaimana skill ini dipanggil dalam konteks sistem lengkap, baca AI agent yang deploy website otomatis.