--- name: skill-conventions description: "Standar dan konvensi pembuatan skill di Holomoc Indonesia. Mencakup aturan frontmatter, struktur direktori, instruksi langkah-demi-langkah, MCP Integration Patterns, dan Agent Iteration & Evaluation Guidance. Gunakan saat akan membuat skill baru, mengupdate skill yang sudah ada, atau mengecek kepatuhan skill terhadap standar Holomoc." metadata: version: 1.1.0 category: holomoc --- # Holomoc Skill Conventions Panduan ini mendefinisikan standar pembuatan dan pemeliharaan skill di Holomoc. Setiap skill WAJIB mengikuti konvensi berikut. --- ## 1. Struktur Direktori & File ``` skills/holomoc// ├── SKILL.md # WAJIB — file utama (case-sensitive) ├── references/ # Opsional — dokumentasi detail │ ├── .md │ └── ... ├── scripts/ # Opsional — kode eksekusi (Python/Bash) │ └── .py └── assets/ # Opsional — template/aset desain ``` ### Aturan Ketat - ✅ Nama folder: `kebab-case` (tanpa spasi, huruf kapital, garis bawah) - ✅ File utama: `SKILL.md` (case-sensitive, huruf besar di S dan M) - ❌ DILARANG: `README.md` di dalam folder skill - ❌ DILARANG: nama skill mengandung kata "claude" atau "anthropic" - ✅ Absolute paths: jangan gunakan `~` — gunakan `/home/ubuntu/...` - ✅ Folder referensi: gunakan `references/` untuk dokumentasi panjang agar SKILL.md tetap ringan --- ## 2. Konfigurasi YAML Frontmatter Frontmatter WAJIB di bagian PALING ATAS file `SKILL.md`: ```yaml --- name: # WAJIB — harus sama dengan nama folder description: > # WAJIB — maks 1024 karakter "Apa fungsi skill dan kapan digunakan. Sertakan trigger phrases spesifik: 'katakan ini', 'bilang itu', dll." metadata: version: X.Y.Z # WAJIB — gunakan semver category: # WAJIB — contoh: document-automation, finance --- ``` ### Aturan - `name`: kebab-case, identik dengan nama folder. ❌ Jangan pakai "claude" atau "anthropic" - `description`: WAJIB mencakup fungsi skill DAN trigger phrases. ❌ DILARANG tag XML `<` atau `>` di frontmatter - Batas panjang description: **1024 karakter maksimal** --- ## 3. Isi SKILL.md — Desain Instruksi Utama ### Format - Instruksi dalam Markdown di bawah frontmatter - WAJIB format **langkah-demi-langkah** (Step 1, Step 2, Step 3, ...) - Spesifik dan berorientasi pada tindakan ### Jika dokumentasi panjang - Pindahkan detail ke `references/.md` - Cukup tautkan satu baris di SKILL.md: "Lihat detail di `references/.md`" ### Komponen yang WAJIB ada di setiap skill #### a. MCP Integration Patterns ```markdown ## MCP Integration Patterns ### Sequential Orchestration Workflow memiliki N langkah berurutan yang WAJIB diikuti: **Step 1** → **Step 2** → **Step 3**. Jika salah satu step gagal, jangan lanjut ke step berikutnya. ### Multi-MCP (Cross-Skill Coordination) Kolaborasi dengan skill lain: - **skill-a → skill-b**: Kapan harus arahkan ke skill lain - **skill-a → skill-c**: Kapan harus panggil script dari skill lain ### Iterative Refinement - Jika : lakukan . - Jika : lakukan . ``` #### b. Agent Iteration & Evaluation Guidance ```markdown ## Agent Iteration & Evaluation Guidance ### Trigger Phrase Testing Skill ini akan terpanggil saat user menggunakan kata/frasa: - ✅ "trigger phrase 1" - ✅ "trigger phrase 2" Jika skill terlalu sering aktif di luar konteks (overtriggering), persempit deskripsi. ### Failure Recovery - ****: - ****: ### Precondition Verification Sebelum menjalankan workflow, WAJIB verifikasi: 1. ✅ 2. ✅ ``` #### c. Troubleshooting Section ```markdown ## Troubleshooting **Error:** **Cause:** **Solution:** ``` #### d. Response Format Rules (khusus chat/WhatsApp) ```markdown # RESPONSE FORMAT RULES (WAJIB) Setiap kali merespon user di chat, GUNAKAN FORMAT LIST (bullet/numbered). - ✅ Tampilkan data sebagai numbered list atau bullet list - ✅ Gunakan emoji untuk memperjelas (📋, 👤, 💰, dll) - ❌ JANGAN gunakan format tabel markdown - ❌ JANGAN buat tabel visual ``` --- ## 4. Integrasi Model Context Protocol (MCP) ### Sequential Pattern - Definisikan urutan langkah, dependensi antar tahap - Instruksi rollback jika gagal ### Multi-MCP Pattern - Koordinasikan alur kerja lintas layanan - Pisahkan tindakan ke fase yang jelas - Validasi transfer data antar MCP ### Iterative Pattern - Bangun loop penyempurnaan - Cek ulang via skrip evaluasi - Iterasi sampai memenuhi standar kualitas --- ## 5. Script Eksternal untuk Validasi Untuk langkah kritis, instruksikan EKSEKUSI script eksternal — jangan hanya mengandalkan pemahaman bahasa model. Contoh dari skill yang sudah ada: - `scripts/add_arsip.py` — menambah entry index arsip - `scripts/add_finance.py` — menambah entry cashbon/reimburse - `scripts/add_mom.py` — validasi MoM, simpan file, update index - `scripts/search_arsip.py` — pencarian di index arsip - `scripts/generate_excel.py` — generate Excel - `scripts/generate_png.py` — generate PNG image --- ## 6. Version Management & Maintenance ### 6a. Version Bumping (Semver) WAJIB update versi setiap kali ada perubahan pada SKILL.md atau file referensi: | Perubahan | Bump | Contoh | |-----------|------|--------| | Menghapus fitur/step (breaking) | MAJOR (X+1.0.0) | 3.2.0 → **4.0.0** | | Menambah fitur/step baru (backward compatible) | MINOR (X.Y+1.0) | 3.2.0 → **3.3.0** | | Bugfix, typo, clarifikasi (no behavior change) | PATCH (X.Y.Z+1) | 3.2.0 → **3.2.1** | ### 6b. Step Renumbering Cascade ⚠️ PITFALL Ketika menghapus atau menambah **Step N** di SKILL.md: 1. **Renumber semua step berikutnya** di SKILL.md itu sendiri (N+1 → N, N+2 → N+1, dst.) 2. **Cari cross-references** di seluruh file skill yang menyebut nomor step tersebut: - File referensi di `references/` (contoh: `cashbon-workflow.md` menyebut "Lihat Step 6 di SKILL.md") - File script di `scripts/` (jarang, tapi cek komentar) - MCP Integration Patterns section yang menyebut step numbers - Sequential Orchestration yang menyebut urutan step 3. **Update juga nomor di Sequential Orchestration** dan Failure Recovery yang bisa menyebut step tertentu 4. Gunakan `search_files` dengan pattern seperti `"Step 6"` atau `"Step 5"` di seluruh folder skill untuk menemukan semua referensi ### 6c. Cross-File Reference Audit Jika mengubah nama variabel, path, atau komponen yang dirujuk antar file: ```bash # Cari semua referensi ke teks lama di seluruh skill Holomoc grep -r "teks-lama" /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/ ``` Perhatikan terutama: - File `references/` yang memanggil step number dari SKILL.md - File SKILL.md yang menyebut path di `references/` - Contoh kode/command yang mengandung step number atau nama file --- ## Referensi Terkait File di `references/` masing-masing skill berisi detail spesifik: - `finance/references/auth-rules.md` — histori hak akses (sudah tidak ada validasi) - `finance/references/cashbon-workflow.md` — workflow kasbon - `finance/references/reimburse-workflow.md` — workflow reimburse - `arsip-document/references/json-schema.md` — schema index JSON - `mom/references/mom-template.md` — template MoM - `mom/references/indexing-schema.md` — schema indexing MoM - `holomoc-email/references/configuration.md` — konfigurasi email - `holomoc-email/references/message-composition.md` — format MML - `holomoc-email/references/gmail-locale-folders.md` — folder Gmail