Pelajaran #2: Create an Agent Skill (SKILL.md) + Create a DESIGN.md File
31 Oktober 2026
Kemarin kamu belajar menulis AGENTS.md. Hari ini kamu belajar menulis dua file pendampingnya. SKILL.md untuk satu pekerjaan yang berulang. DESIGN.md untuk aturan tampilan. Kalau AGENTS.md itu aturan kerja di repo, SKILL.md itu resep satu pekerjaan, dan DESIGN.md itu kontrak tampilan. Dengan tiga file ini, agent tidak perlu lagi menebak setiap kali kamu minta sesuatu.
1. Create an Agent Skill (SKILL.md)
Apa itu dan kapan dipakai
Prompt ini mengubah satu pekerjaan yang sering kamu ulang menjadi file SKILL.md yang bisa dimuat Cursor atau Claude Code. Kamu isi nama pekerjaan, pemicu, input, cara ahli mengerjakannya, dan standar hasil. Agent lalu menyimpan resep itu dan memakainya lagi tanpa kamu jelaskan dari nol. Pakai prompt ini saat kamu sadar kamu menjelaskan hal yang sama untuk ketiga kalinya, misalnya audit tampilan, kritik PRD, atau sintesis riset.
Mengapa bekerja
Prompt ini bekerja karena ia memisahkan empat hal. Tugasnya jelas di awal. Konteksnya lengkap, yaitu input, sumber acuan, dan alat yang tersedia. Batasannya tegas, yaitu kapan skill aktif, kapan harus diam, apa yang tidak boleh dilakukan, dan langkah mana yang butuh persetujuan kamu. Format keluarannya juga dikunci lewat 15 bagian wajib, dari kriteria aktivasi sampai contoh dan kasus uji. Agent jadi tidak menebak. Ia mengikuti resep yang sama setiap kali.
Catatan gaya: prompt ini hanya sebagus isian kurungnya. Kalau kurung dibiarkan kosong, agent akan mengarang nilai dan contoh generik, dan hasilnya terasa seperti template. Isi dengan nama, contoh nyata, dan larangan yang spesifik.
Teks prompt
You design agent skills. Turn the workflow below into a reusable SKILL.md.
## Workflow
- Workflow name: [name]
- Job to be done: [job]
- Who will use this skill: [roles]
- When it should activate: [trigger phrases or conditions]
- When it should stay off: [out-of-scope cases]
## Inputs and context
- Required inputs: [files, documents, user input, product context, data]
- Optional inputs: [optional context]
- Source-of-truth references: [references]
- Tools available: [tools]
## How an expert does it today
[Describe the current workflow, including decision points and human review.]
## Expected output
- Deliverable: [output]
- Format: [format]
- Audience: [audience]
- Definition of done: [quality bar]
## Constraints and risks
- Design-system, brand, privacy, legal, or policy constraints: [constraints]
- Common failures to avoid: [failures]
- Steps that need human approval: [approval steps]
- Actions the AI must not take: [prohibited actions]
Write a SKILL.md with:
1. Name and purpose
2. Activation criteria
3. Non-goals
4. Required inputs and preflight checks
5. Context and source hierarchy
6. Step-by-step workflow
7. Tool-use rules
8. Output contract
9. Quality checklist
10. Human-review and escalation points
11. Failure and recovery behavior
12. Two realistic examples
13. One anti-pattern
14. Test cases
15. Owner, version, and review-date metadata
Write in plain operating instructions. If a judgment call is unsafe to automate, tell the agent to show options with evidence and wait for a person.Contoh terisi
Contoh ini untuk pekerjaan Aulia yang nyata, yaitu audit tampilan aplikasi Kumbang sebelum rilis.
You design agent skills. Turn the workflow below into a reusable SKILL.md.
## Workflow
- Workflow name: audit tampilan Kumbang sebelum rilis
- Job to be done: memeriksa satu layar aplikasi Kumbang dan menulis daftar perbaikan yang konkret
- Who will use this skill: Aulia dan coding agent di Cursor
- When it should activate: ketika Aulia minta audit tampilan, periksa layar, atau review UI sebelum deploy
- When it should stay off: ketika tugasnya mengubah logika bisnis, memperbaiki bug data, atau menulis laporan dinas
## Inputs and context
- Required inputs: tangkapan layar dari layar yang diaudit, daftar perubahan terbaru, dan file DESIGN.md aplikasi tersebut
- Optional inputs: masukan Aulia dari uji pakai di HP
- Source-of-truth references: DESIGN.md aplikasi, AGENTS.md repo, dan pedoman gaya yang sudah disepakati
- Tools available: Cursor, WebKit untuk cek tampilan di ukuran HP, dan repo aplikasi
## How an expert does it today
Aulia membuka layar di HP, membandingkan dengan DESIGN.md, mencatat yang meleset, lalu mengurutkan perbaikan dari yang paling mengganggu pengguna. Perubahan tampilan yang meragukan ditunjukkan dulu ke Aulia sebelum diterapkan.
## Expected output
- Deliverable: daftar perbaikan bernomor dengan lokasi layar dan bukti tangkapan layar
- Format: markdown singkat, satu perbaikan per penjelasan
- Audience: Aulia
- Definition of done: setiap perbaikan bisa dicek ulang di HP, tidak ada saran yang samar
## Constraints and risks
- Design-system, brand, privacy, legal, or policy constraints: pakai biru Kumbang dan aturan yang ada di DESIGN.md, jangan mengubah identitas aplikasi, jangan memakai data pengguna asli
- Common failures to avoid: saran generik tanpa lokasi, mengubah banyak hal sekaligus, dan memuji tampilan tanpa memeriksa
- Steps that need human approval: perubahan susunan layar dan perubahan warna utama
- Actions the AI must not take: mengubah file sumber sebelum Aulia menyetujui daftar perbaikan
Write a SKILL.md with:
1. Name and purpose
2. Activation criteria
3. Non-goals
4. Required inputs and preflight checks
5. Context and source hierarchy
6. Step-by-step workflow
7. Tool-use rules
8. Output contract
9. Quality checklist
10. Human-review and escalation points
11. Failure and recovery behavior
12. Two realistic examples
13. One anti-pattern
14. Test cases
15. Owner, version, and review-date metadata
Write in plain operating instructions. If a judgment call is unsafe to automate, tell the agent to show options with evidence and wait for a person.Tugas praktik hari ini
Pilih satu pekerjaan yang kamu ulang minggu ini, misalnya memeriksa tampilan sebelum deploy. Isi prompt ini untuk pekerjaan itu, simpan hasilnya sebagai SKILL.md, lalu coba pakai untuk satu tugas nyata dan lihat apakah agent masih bertanya hal yang sama.
2. Create a DESIGN.md File
Apa itu dan kapan dipakai
Prompt ini menulis DESIGN.md, yaitu file aturan tampilan untuk satu produk. Isinya token desain, komponen, pola UX, aturan tulisan, dan standar aksesibilitas. Setelah file ini ada, agent yang membuat atau mengkritik UI memakai aturan yang sama, bukan seleranya sendiri. Pakai prompt ini saat memulai aplikasi baru, atau saat layar buatan agent mulai terasa beda beda padahal produknya sama.
Mengapa bekerja
Prompt ini bekerja karena ia memaksa kamu menulis konteks produk dulu, baru aturan tampilan. Agent tahu siapa pengguna, apa pekerjaan utama, dan seperti apa kepribadian produk sebelum ia memilih warna atau komponen. Bagian Requirements mengunci aksesibilitas, interaksi, tulisan, dan pola yang dilarang. Bagian akhir memaksa agent menulis daftar cek sebelum membuat UI dan daftar cek sesudahnya. Kalimat terakhirnya penting: jangan mengarang nilai token. Bagian yang belum diketahui harus ditulis NEEDS TEAM INPUT, bukan diisi tebakan.
Teks prompt
You are a product designer who owns a design system. Write a DESIGN.md that a coding or design agent can use to generate or critique UI for this product.
## Product context
- Product name and purpose: [product]
- Target users: [users]
- Main jobs to be done: [jobs]
- Product principles: [principles]
- Brand personality: [voice]
- Supported platforms: [web, mobile, desktop]
- Responsive breakpoints: [breakpoints]
## Design system
- Design tokens: [colors, typography, spacing, radius, elevation, motion]
- Components available: [components]
- Component usage rules: [rules]
- Existing UX patterns: [navigation, forms, search, tables, empty states, errors]
- References: [Figma, Storybook, component library, screenshots, docs]
## Requirements
- Accessibility standard: [requirements]
- Interaction requirements: [keyboard, focus, touch, motion]
- Content and microcopy rules: [rules]
- Localization needs: [needs]
- Privacy, safety, or compliance constraints: [constraints]
- Known anti-patterns to avoid: [anti-patterns]
Write DESIGN.md with:
1. Purpose and scope
2. Product and user principles
3. Visual hierarchy and layout rules
4. Token and visual-system guidance
5. Component selection and usage rules
6. Interaction states and behavior
7. Content and microcopy guidance
8. Accessibility requirements
9. Responsive behavior
10. AI-specific UI patterns, if relevant
11. Anti-patterns and prohibited choices
12. Canonical design references
13. Preflight checklist before generating UI
14. Final UI QA checklist
Keep the language short and directive. Do not invent token or component values. Use [NEEDS TEAM INPUT] where details are missing.Contoh terisi
Contoh ini untuk BugarKu, aplikasi latihan kebugaran berbasis kamera yang sudah live.
You are a product designer who owns a design system. Write a DESIGN.md that a coding or design agent can use to generate or critique UI for this product.
## Product context
- Product name and purpose: BugarKu, aplikasi latihan kebugaran berbasis kamera untuk pengguna umum
- Target users: orang dewasa yang latihan di rumah dengan HP
- Main jobs to be done: memilih sesi latihan, mengikuti gerakan lewat kamera, dan melihat progres
- Product principles: gerakannya jelas, tombolnya besar, dan latihannya bisa diikuti tanpa membaca panjang
- Brand personality: energik, sederhana, dan membesarkan hati, tanpa klaim berlebihan
- Supported platforms: web
- Responsive breakpoints: HP kecil, HP besar, dan tablet
## Design system
- Design tokens: warna utama biru Kumbang, latar putih, teks gelap, spasi konsisten, sudut membulat sedang, gerakan halus dan singkat
- Components available: kartu sesi, tombol mulai, penghitung waktu, kartu progres, dan pesan kosong
- Component usage rules: satu aksi utama per layar, tombol mulai selalu terlihat tanpa gulir jauh, dan kartu progres memakai angka nyata bukan angka contoh
- Existing UX patterns: navigasi menu satu bagian dalam satu waktu, formulir pendek, pesan kosong yang menjelaskan langkah berikut, dan pesan galat yang menyebut cara memperbaiki
- References: tangkapan layar BugarKu yang sudah live dan file gaya yang dipakai sekarang
## Requirements
- Accessibility standard: kontras teks yang mudah dibaca, tombol yang mudah disentuh, dan dukungan keyboard
- Interaction requirements: fokus yang terlihat, sentuhan yang responsif, dan gerakan yang bisa dikurangi
- Content and microcopy rules: label saja, kalimat pendek, dan bahasa yang netral
- Localization needs: Bahasa Indonesia
- Privacy, safety, or compliance constraints: video kamera tidak dikirim ke server tanpa persetujuan pengguna
- Known anti-patterns to avoid: halaman panjang tanpa menu, tombol kecil yang berdekatan, dan warna yang hanya mengandalkan warna untuk menyampaikan status
Write DESIGN.md with:
1. Purpose and scope
2. Product and user principles
3. Visual hierarchy and layout rules
4. Token and visual-system guidance
5. Component selection and usage rules
6. Interaction states and behavior
7. Content and microcopy guidance
8. Accessibility requirements
9. Responsive behavior
10. AI-specific UI patterns, if relevant
11. Anti-patterns and prohibited choices
12. Canonical design references
13. Preflight checklist before generating UI
14. Final UI QA checklist
Keep the language short and directive. Do not invent token or component values. Use [NEEDS TEAM INPUT] where details are missing.Tugas praktik hari ini
Pakai prompt ini untuk menulis DESIGN.md satu aplikasi Kumbang, misalnya BugarKu atau PindaiKu. Setelah itu minta agent membuat satu layar memakai file tersebut. Kalau hasilnya meleset, perbaiki DESIGN.md nya, bukan hanya layarnya.