SKILL.md yang berisi instruksi, deskripsi, dan sumber daya pendukung opsional. Halaman ini juga mencakup perintah dalam sesi Agent SDK.
Untuk informasi lebih lanjut tentang skills, termasuk manfaat, arsitektur, dan panduan penulisan, lihat ikhtisar Agent Skills.
Cara skills bekerja dengan Agent SDK
Saat menggunakan Claude Agent SDK, skills adalah:- Didefinisikan sebagai artefak filesystem: Anda membuat setiap skill sebagai file
SKILL.mddi direktorinya sendiri, seperti.claude/skills/<name>/SKILL.md - Dimuat dari filesystem: SDK memuat skills dari lokasi filesystem yang diatur oleh
settingSources(TypeScript) atausetting_sources(Python) - Ditemukan secara otomatis: Setelah pengaturan filesystem dimuat, SDK menemukan metadata skill saat startup dari direktori pengguna dan proyek, dan memuat konten penuh ketika Claude memanggil skill
- Dipanggil oleh model: Claude secara otomatis memilih kapan menggunakannya berdasarkan konteks
- Dipanggil oleh pengguna: Anda dispatch skill secara langsung dengan mengirim
/<name>dalam prompt. Lihat Perintah dalam sesi Agent SDK - Disaring melalui opsi
skills: Skills yang ditemukan diaktifkan secara default. Berikan daftar nama skill,"all", atau[]untuk mengontrol skill mana yang dapat Claude panggil
agents, Anda membuat skills sebagai file di disk. SDK tidak menyediakan API programatis untuk mendaftarkan mereka.
Skills ditemukan melalui sumber pengaturan filesystem. Dengan opsi
query() default, SDK memuat sumber pengguna dan proyek, jadi skills di ~/.claude/skills/, <cwd>/.claude/skills/, dan .claude/skills/ di direktori induk mana pun dari <cwd> hingga akar repositori tersedia. Sumber proyek juga mencakup <dir>/.claude/skills/ di setiap direktori yang Anda lewatkan melalui additionalDirectories (TypeScript) atau add_dirs (Python), karena SDK meneruskan direktori tersebut ke Claude Code sebagai --add-dir. Jika Anda menetapkan settingSources secara eksplisit, sertakan 'project' untuk mempertahankan skills proyek dan direktori tambahan serta 'user' untuk mempertahankan skills pribadi Anda, atau gunakan opsi plugins untuk memuat skills dari jalur tertentu.Gunakan skills dengan Agent SDK
Atur opsiskills pada query() untuk mengontrol skill mana yang dapat Claude panggil dalam sesi. Ketika dihilangkan, skills yang ditemukan diaktifkan dan alat Skill tersedia, sesuai dengan perilaku CLI. Berikan "all" untuk membiarkan Claude memanggil setiap skill yang ditemukan, daftar nama skill untuk mengizinkan hanya yang tersebut, atau [] untuk membiarkan Claude tidak memanggil apa pun.
Misalnya, untuk membiarkan Claude memanggil hanya dua skill bernama:
Siapkan skills dalam sesi
Ketika Anda menetapkanskills, SDK secara otomatis menambahkan alat Skill ke allowedTools. Jika Anda juga meneruskan daftar tools eksplisit, sertakan "Skill" dalam daftar tersebut sehingga Claude dapat memanggil skills.
Setelah dikonfigurasi, Claude secara otomatis menemukan skills dari filesystem dan memanggilnya ketika relevan dengan permintaan pengguna.
Contoh berikut mengaktifkan setiap skill yang ditemukan dalam sesi dan pra-menyetujui alat yang skills biasanya butuhkan. Contoh menetapkan cwd ke direktori kerja proses saat ini, jadi jalankan dari dalam proyek yang memiliki direktori .claude/skills/ di direktori saat ini atau induk mana pun hingga akar repositori:
Konfirmasi skills dimuat
Dekat awal aliran, SDK menghasilkan pesan sistem dengan subtypeinit. Periksa array skills untuk mengonfirmasi skills Anda dimuat sebelum Claude mulai bekerja. Array mencakup skills yang dapat dipanggil pengguna yang telah Anda definisikan dengan bidang frontmatter description atau when_to_use, bersama dengan skills bundel yang disertakan dengan Claude Code.
Array hanya mencantumkan skills yang dapat dipanggil pengguna. Skill dengan user-invocable: false dalam frontmatter dimuat dan tetap tersedia untuk Claude, tetapi tidak muncul dalam array. Array mencantumkan skills yang sama apakah atau tidak mereka ada dalam daftar skills Anda.
Izinkan hanya skills tertentu
Untuk membiarkan Claude memanggil hanya skills tertentu, berikan nama mereka dalam daftarskills. Nama cocok dengan bidang name di SKILL.md atau nama direktori skill. Gunakan plugin:skill untuk skills yang disediakan plugin.
Daftar hanya mengambil nama skill yang tepat. Jika entri tidak dapat berfungsi sebagai nama yang tepat, query() menolak daftar sebelum sesi dimulai. Lihat Kesalahan nama skill tidak valid untuk aturan nama dan kesalahan yang setiap SDK angkat.
Model tidak melihat skills yang tidak tercantum dan alat Skill menolaknya, sementara file mereka tetap di disk dan tetap dapat diakses melalui Read dan Bash. Membatasi daftar tidak membatasi dispatch berdasarkan nama.
Untuk membiarkan Claude memanggil setiap skill yang ditemukan, berikan skills: "all" daripada wildcard.
Perintah dalam sesi Agent SDK
Bagian ini adalah dokumentasi perintah SDK. Perintah adalah apa pun yang Anda jalankan dengan mengirim/<name> dalam prompt. Entri pada permukaan perintah berbeda dalam apa yang mendukung mereka:
- Perintah bawaan: menjalankan logika yang dikodekan ke dalam proses Claude Code yang SDK jalankan, misalnya
/compact - Skills bundel: artefak prompt yang disertakan dengan Claude Code, misalnya
/code-review - Skills Anda: artefak prompt yang Anda buat, masing-masing direktori yang menyimpan file
SKILL.md. Nama skill yang dapat dipanggil pengguna bergabung dengan permukaan secara otomatis, jadi mendispatch/security-checkAnda sendiri dan menjalankan bawaan bekerja dengan cara yang sama - File perintah khusus: bentuk artefak yang lebih lama dengan perilaku yang sama, file Markdown datar di
.claude/commands/yang nama file mereka menjadi nama perintah. Skills adalah penerus yang direkomendasikan
Temukan perintah yang tersedia
Anda dapat mendispatch perintah yang bekerja tanpa terminal interaktif melalui SDK. Pesansystem/init mencantumkan yang tersedia dalam sesi Anda di bidang slash_commands. Perintah yang membutuhkan terminal interaktif, seperti /theme dan /terminal-setup, tidak muncul dalam daftar. Akses bidang ketika sesi Anda dimulai:
.claude/commands/:
user-invocable: false dalam frontmatter tidak muncul dalam daftar ini atau dalam array skills dari Konfirmasi skills dimuat. Sesi yang mengonfigurasi server MCP juga dapat mengekspos prompt MCP sebagai perintah.
Dispatch perintah berdasarkan nama
Kirim perintah dengan memasukkannya dalam string prompt Anda, dengan cara yang sama Anda mengirim teks biasa. Dispatch tidak bergantung pada opsiskills. Mengirim /<name> menjalankan skill yang dapat dipanggil pengguna bahkan ketika daftar skills Anda menghilangkannya. Perintah yang bertindak pada riwayat percakapan, seperti /compact, membutuhkan pesan sebelumnya untuk bekerja dengan.
Sebuah /<name> yang tidak cocok dengan perintah apa pun dalam sesi maupun perintah Claude Code bawaan tidak gagal query. Claude Code mengirim prompt ke Claude sebagai pesan biasa, dengan catatan bahwa perintah tidak berjalan, jadi query menghabiskan putaran model dan mengembalikan balasan Claude. Sebelum v2.1.274, sebuah /<name> yang tidak cocok dengan apa pun mengembalikan Unknown command: /<name> sebagai hasil tanpa putaran model.
Sebuah /<name> yang cocok dengan perintah Claude Code bawaan yang tidak tersedia dalam sesi, seperti /theme, mengembalikan /theme isn't available in this environment. sebagai hasil tanpa putaran model.
Perintah dapat mencapai batas
maxTurns / max_turns seperti prompt lainnya, mengakhiri query dengan hasil kesalahan daripada success. Untuk kontrak hasil kesalahan, lihat Tangani hasil. Jika perintah Anda mungkin mencapai batas, bungkus loop dalam try/catch di TypeScript atau try/except di Python, seperti yang ditunjukkan dalam Input Pesan Tunggal, atau atur maxTurns cukup tinggi agar pekerjaan selesai.Kompres riwayat dengan /compact
Perintah /compact mengurangi ukuran riwayat percakapan Anda dengan merangkum pesan yang lebih lama sambil mempertahankan konteks penting. Pemadatan membutuhkan percakapan yang ada dengan cukup pesan sebelumnya untuk dirangkum. Contoh ini memiliki percakapan terlebih dahulu, kemudian memadatkannya dan membaca pesan sistem compact_boundary yang melaporkan hasilnya:
Pesan
compact_boundary hanya tiba ketika pemadatan berjalan. Ketika sesi yang dilanjutkan memiliki pesan tetapi tidak ada yang dapat dirangkum oleh /compact, jalannya masih berakhir dengan hasil success daripada kesalahan, dan tidak ada pesan compact_boundary yang tiba. Teks hasil kemudian membawa alasannya, misalnya Not enough messages to compact. ketika sesi menyimpan prompt tetapi belum ada balasan dari Claude. Panggilan query() satu kali yang segar dimulai dengan konteks kosong, jadi gunakan pola ini dalam sesi dengan putaran sebelumnya, misalnya dalam mode input streaming atau saat melanjutkan sesi.Atur ulang konteks dengan /clear
Perintah /clear mengatur ulang percakapan ke konteks kosong, jadi prompt berikutnya dimulai tanpa riwayat percakapan sebelumnya. Percakapan sebelumnya tetap di disk. Anda dapat kembali ke percakapan itu dengan meneruskan ID sesinya ke opsi resume.
/clear berguna dalam mode input streaming, di mana Anda mengirim beberapa prompt melalui koneksi tunggal. Untuk panggilan query() satu kali, setiap panggilan sudah dimulai dengan konteks kosong, jadi mengirim /clear tidak memiliki efek praktis. Mulai query() baru sebagai gantinya.
Buat skills
Buat setiap skill sebagai direktori yang berisi fileSKILL.md dengan frontmatter YAML dan konten Markdown. Bidang description menentukan kapan Claude memanggil skill Anda.
Contoh struktur direktori:
Pilih tingkat penemuan
Simpan skills di salah satu dari dua tingkat penemuan paling umum discovery levels:- Skills proyek:
.claude/skills/, hanya tersedia di proyek saat ini - Skills pribadi:
~/.claude/skills/, tersedia di semua proyek Anda
.claude/commands/, mereka terus bekerja. File perintah di .claude/commands/deploy.md membuat /deploy dan bekerja dengan cara yang sama seperti skill di .claude/skills/deploy/SKILL.md. Jika file perintah dan skill berbagi nama, lihat Selesaikan skills yang berbagi nama untuk yang mana yang berjalan. SDK memuat file .claude/commands/ dan ~/.claude/commands/ dari dua cakupan yang sama dengan skills. Lihat Perluas Claude dengan skills untuk panduan lengkap kedua bentuk artefak.
Buat dan dispatch skill pertama Anda
Untuk melihat alur lengkapnya, buat.claude/skills/security-check/SKILL.md:
success yang teksnya membawa temuan pemindaian. Terhadap aplikasi Express kecil dengan masalah yang ditanam, teks hasil dimulai:
slash_commands pesan init.
Claude Code mencakup skills bundel
code-review dan verify. Jika Anda memberi nama file .claude/commands/ setelah salah satunya, misalnya .claude/commands/code-review.md, file perintah mengaburkan skill bundel dan slash_commands mencantumkan nama sekali.Pra-setujui alat untuk skills
Dalam sesi SDK, Anda dapat pra-menyetujui tool untuk skill proyek atau pribadi dengan frontmatter
allowed-tools milik skill tersebut atau dengan opsi allowedTools (allowed_tools di Python) dalam konfigurasi query Anda. Jika organisasi Anda menetapkan allowManagedPermissionRulesOnly dalam pengaturan terkelola, Claude Code mengabaikan keduanya. Skills disinkronkan dari claude.ai mengikuti aturan frontmatter mereka sendiri.Read, Grep, dan Glob dengan allowedTools (allowed_tools di Python), jadi Claude dapat memeriksa file saat menjalankan skill security-check tanpa berhenti untuk persetujuan:
success yang teksnya membawa temuan.
Daftar pra-menyetujui alat bernama daripada membatasi yang lain. Untuk alur izin lengkap, termasuk mode izin dan callback canUseTool, lihat Izin.
Pemecahan Masalah
Skills tidak ditemukan
Periksa konfigurasi settingSources: SDK menemukan skills melalui sumber pengaturanuser dan project. Jika Anda menetapkan settingSources/setting_sources secara eksplisit dan menghilangkan sumber tersebut, SDK tidak memuat skills:
settingSources/setting_sources, lihat referensi SDK TypeScript atau referensi SDK Python.
Periksa direktori kerja: SDK memuat skills dari .claude/skills/ dalam opsi cwd dan di setiap direktori induk hingga akar repositori. Pastikan cwd menunjuk ke atau di bawah direktori yang berisi .claude/skills/, dalam repositori yang sama:
Skill tidak digunakan
Periksa opsiskills: jika Anda meneruskan daftar skills, konfirmasi nama skill disertakan. Ketika Claude mencoba memanggil skill yang tidak tercantum, alat Skill mengembalikan Skill <name> is not in this session's skills allowlist. Tambahkan nama ke daftar Anda, atau dispatch skill secara langsung dengan mengirim /<name> dalam prompt, yang bekerja tanpa pencatatan.
Periksa deskripsi: pastikan itu spesifik dan mencakup kata kunci yang relevan. Lihat praktik terbaik Agent Skills untuk panduan tentang menulis deskripsi yang efektif.
Kesalahan nama skill tidak valid
Ketika nama dalam daftarskills Anda tidak dapat berfungsi sebagai nama skill yang tepat, query() menolak daftar sebelum memulai proses Claude Code. Nama yang memicu penolakan mencakup:
- Nama kosong
- Nama yang berisi tanda kurung, koma, atau karakter kontrol
- Nama yang diisi dengan spasi putih
- Bentuk wildcard seperti
*telanjang atau akhiran:*
- TypeScript
- Python
SDK TypeScript melempar Nama kosong melaporkan
Error yang menyatakan aturan yang entri langgar. Misalnya, skills: ["docs:*"] melempar:Skill names must be non-empty strings.Sebelum TypeScript Agent SDK 0.3.221, SDK tidak menjalankan pemeriksaan ini.Pemecahan masalah tambahan
Untuk pemecahan masalah skills umum, seperti kesalahan sintaks YAML dan debugging, lihat bagian pemecahan masalah skills Claude Code.Langkah berikutnya
Panduan skills Claude Code mencakup penulisan secara mendalam. Panduan tersebut berlaku untuk sesi SDK. Mulai dengan bagian ini:- Referensi frontmatter: setiap bidang yang didukung
- Berikan argumen ke skills:
$ARGUMENTS,$0,$1, dan penumpukan skill. Tabel substitusi lengkap menambahkan argumen bernama dan variabel${CLAUDE_*} - Injeksi konteks dinamis: baris
!`command`yang berjalan sebelum Claude melihat konten skill - Pilih di mana skills dimuat: setiap lokasi skill, namespace plugin, dan skill mana yang berjalan ketika dua berbagi nama
Sumber daya terkait
- Perintah dalam Claude Code: permukaan perintah lengkap, termasuk setiap bawaan
- Ikhtisar Agent Skills: ikhtisar konseptual, manfaat, dan arsitektur
- Praktik terbaik Agent Skills: panduan penulisan untuk skills yang efektif
- Buku resep Agent Skills: contoh skills dan template
- Subagents dalam SDK: agen berbasis filesystem serupa dengan opsi programatis
- Ikhtisar SDK: konsep SDK umum
- Referensi SDK TypeScript: dokumentasi API lengkap
- Referensi SDK Python: dokumentasi API lengkap