Panduan Resmi Arsitektur Skill AI (Edisi 2026)

Panduan Kompleksitas Membangun Skill Claude

Ubah alur kerja manual yang berulang menjadi folder instruksi cerdas terstruktur. Mengajar Claude sekali untuk digunakan secara konsisten dan otomatis selamanya.

15 - 30
Waktu Buat First Skill (Menit)
90%+
Target Trigger Accuracy
50%
Efisiensi Token Context
0 Failure
Target Failed API Calls

1 Fundamentalis & Arsitektur Utama Skill

Skill adalah sekumpulan instruksi terstruktur dalam sebuah folder sederhana yang mengajarkan Claude cara menyelesaikan alur kerja atau tugas khusus secara otomatis.

🍳

Analogi Dapur: MCP vs Skill

Memahami perbedaan fungsi teknis antara Model Context Protocol (MCP) dan Skill sangat krusial agar integrasi berjalan optimal.

MCP (Dapur & Alat-Alat):

Menyediakan konektivitas ke layanan luar (Notion, Linear, GitHub), akses data real-time, dan pemanggilan tool eksternal.

Skills (Resep & Pengetahuan):

Menyediakan panduan alur kerja bertahap, SOP standar tim, serta logika penyelesaian tugas terbaik.

💡 Kombinasi MCP + Skill mengubah alat mentah menjadi eksekusi otomatis yang andal.

Sistem 3-Tingkat Progressive Disclosure

Untuk menghemat penggunaan token context Window, skill menggunakan pengungkapan bertahap 3 tingkat.

Efisiensi Token: Level 1 dimuat otomatis di System Prompt (~100 tokens), Level 2 saat dipanggil (~1k-5k tokens), Level 3 sesuai kebutuhan spesifik.

Komponen Folder Skill

SKILL.md
WAJIB

Instruksi utama dalam format Markdown dengan YAML frontmatter wajib di bagian atas.

scripts/
OPSIONAL

Kode yang dapat dieksekusi (Python, Bash) untuk otomatisasi validasi atau pengolahan data.

references/
OPSIONAL

Dokumentasi pendukung, standar API, atau panduan detail yang dimuat secara bertahap.

assets/
OPSIONAL

Template dokumen, aset visual, font, atau sampel output yang akan digunakan oleh skrip.

2 Perencanaan & Desain Skill

Sebelum membuat skill, definisikan 2-3 use-case spesifik. Anthropic mengklasifikasikan pengaplikasian skill ke dalam 3 kategori utama dengan benchmark keberhasilan terukur.

Kategori 1

Pembuatan Dokumen & Aset

Menghasilkan output berkualitas tinggi seperti komponen frontend, dokumen docx, slide pptx, spreadsheet xlsx.

frontend-design, pptx-generator
Kategori 2

Otomatisasi Alur Kerja

Proses bertahap berurutan yang membutuhkan metodologi konsisten dan koordinasi multi-langkah.

skill-creator, sprint-planner
Kategori 3

Peningkatan MCP

Memberikan panduan alur kerja untuk memperkuat akses alat yang disediakan oleh server MCP eksternal.

sentry-code-review, linear-sprint

🚫 Aturan Kritis Penamaan & Struktur

1. Nama File Utama:

Harus tepat SKILL.md (sensitif huruf besar-kecil). Tidak menerima SKILL.MD, skill.md, atau nama lain.

2. Format Naming Folder:

Wajib menggunakan kebab-case (contoh: notion-sprint-setup). Dilarang spasi, underscore (_), atau huruf kapital.

3. Larangan README.md:

Jangan sertakan README.md di dalam folder skill. Semua dokumentasi ditujukan di dalam SKILL.md atau direktori references/.

YAML Frontmatter Spec (SKILL.md) Format Wajib 
---
name: sentry-bug-fixer
description: Menganalisis dan memperbaiki bug dari Sentry di PR. Gunakan saat pengguna mengunggah .fig, atau mengatakan "perbaiki bug sentry".
license: MIT
metadata:
  author: TeamDev
  version: 1.0.0
---
  • Description: Harus memuat APA yang dilakukan & KAPAN memicu (triggers). Maksimal 1024 karakter.
  • Keamanan: Dilarang menggunakan tag XML (< atau >) di dalam frontmatter.

3 Pengujian, Kinerja & Evaluasi

Pengujian skill yang efektif berfokus pada tiga pilar utama: Uji Triggering, Uji Fungsional, dan Perbandingan Kinerja Baseline.

Perbandingan Kinerja (Baseline vs Skill)

Data kuantitatif dampak penggunaan skill pada alur kerja berulang kompleks.

Uji Akurasi Pemicuan (Triggering Tests)

Distribusi hasil pengujian 20 skenario query otomatis.

Matriks Troubleshooting & Solusi

Gejala / Masalah Kemungkinan Penyebab Tindakan Perbaikan (Remediation)
Undertriggering (Skill tidak otomatis aktif) Deskripsi frontmatter terlalu singkat, umum, atau kurang kata pemicu (trigger phrases). Perluas deskripsi di YAML frontmatter. Tambahkan frase langsung yang sering dikatakan pengguna.
Overtriggering (Aktif pada topik irrelevant) Deskripsi terlalu luas atau ambigu (misal: "membantu kelola proyek"). Tambahkan pemicu negatif (misal: "Jangan gunakan untuk eksplorasi data sederhana").
Instruksi Tidak Diikuti Konsisten Instruksi SKILL.md terlalu panjang atau instruksi penting tertimbun. Taruh aturan kritis di paling atas dengan header ## CRITICAL atau buat langkah bernomor.

4 5 Pola Arsitektur Skill Utama

Berdasarkan praktik terbaik dari tim Anthropic, berikut 5 pola arsitektur paling efektif untuk membangun skill.

Pola 1 Orkestrasi Alur Berurutan

Sequential Workflow Orchestration

Digunakan ketika alur kerja membutuhkan langkah-langkah dalam urutan ketat dengan validasi di setiap tahap.

Langkah 1: Akun
create_customer
Langkah 2: Pembayaran
setup_payment
Langkah 3: Langganan
create_subscription
Langkah 4: Konfirmasi
send_welcome_email
Pola 2 Koordinasi Multi-MCP

Multi-MCP Coordination

Menghubungkan beberapa server MCP sekaligus dalam satu alur kerja lintas ekosistem.

Figma MCP
Ekspor aset & spec desain
Google Drive MCP
Simpan aset ke folder proyek
Linear MCP
Buat tiket dev & lampirkan link
Slack MCP
Kirim notifikasi handoff ke tim
Pola 3

Iterative Refinement

Perbaikan kualitas output secara berulang dengan skrip validasi otomatis hingga ambang batas kualitas terpenuhi.

Pola 4

Context-Aware Selection

Memilih alat atau lokasi penyimpanan terbaik secara dinamis berdasarkan ukuran file, tipe data, atau preferensi.

Pola 5

Domain Intelligence

Menanamkan aturan kepatuhan, standar industri, atau pengecekan risiko finansial/hukum sebelum eksekusi.

5 Distribusi Skill & Checklist Validasi

Opsi penyebaran skill untuk individu, tim organisasi, atau aplikasi programatis via API.

👤

Pengguna Individu

Unggah folder ZIP via menu Settings > Capabilities > Skills di Claude.ai atau masukkan ke direktori Claude Code.

Claude.ai / Claude Code
🏢

Tingkat Organisasi

Admin dapat menerapkan skill secara terpusat untuk seluruh pengguna workspace dengan pembaruan otomatis.

Workspace Deployment
⚙️

Eksekusi API

Gunakan endpoint /v1/skills dan parameter container.skills pada Messages API.

Messages API & Agent SDK

☑️ Checklist Validasi Sebelum Upload

Pastikan seluruh poin berikut telah terpenuhi sebelum mengunggah atau mendistribusikan skill Anda.

✓ Nama folder menggunakan format kebab-case tanpa spasi atau huruf kapital.
✓ File utama dinamai persis SKILL.md (sensitif huruf besar-kecil).
✓ YAML Frontmatter diawali dan diakhiri pembatas --- dengan benar.
✓ Field description memuat informasi APA yang dilakukan dan KAPAN dipicu.
✓ Tidak ada karakter XML angle brackets (< & >) di dalam frontmatter.
✓ Telah diuji terhadap 3 skenario: Trigger obvious, paraphrased, dan unrelated query.