Perluas agen dengan skills

Kontrol skill mana yang dapat Claude panggil dalam sesi Claude Agent SDK, dispatch perintah berdasarkan nama, dan buat skills yang sesi Anda temukan

Agent Skills memperluas Claude dengan kemampuan khusus yang Claude panggil ketika relevan. Skills dikemas sebagai file SKILL.md yang berisi instruksi, deskripsi, dan sumber daya pendukung opsional. Halaman ini juga mencakup perintah dalam sesi Agent SDK.

Untuk informasi komprehensif 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.md di direktorinya sendiri, seperti .claude/skills/<name>/SKILL.md
• Dimuat dari filesystem: SDK memuat skills dari lokasi filesystem yang diatur oleh settingSources (TypeScript) atau setting_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

Tidak seperti subagents, yang dapat Anda definisikan dalam opsi agents, Anda membuat skills sebagai file di disk. SDK tidak menyediakan API programatis untuk mendaftarkan mereka.

Gunakan skills dengan Agent SDK

Atur opsi skills 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:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

const options = { skills: ["pdf", "docx"] };

Siapkan skills dalam sesi

Ketika Anda menetapkan skills, 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:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",  # Let Claude invoke every discovered skill
allowed_tools=["Read", "Write", "Bash"],
)

async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: process.cwd(), // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all", // Let Claude invoke every discovered skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}

Konfirmasi skills dimuat

Dekat awal aliran, SDK menghasilkan pesan sistem dengan subtype init. 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 daftar skills. 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-check Anda 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

Secara default, baik Anda maupun Claude dapat memanggil skill apa pun. Anda dapat membatasi jalur mana pun melalui frontmatter skill. Untuk definisi dua istilah, lihat entri Perintah dan Skill dalam glosarium. Lihat Perintah dalam Claude Code untuk setiap bawaan dan Perluas Claude dengan skills untuk panduan lengkap kedua bentuk artefak.

Temukan perintah yang tersedia

Anda dapat mendispatch perintah yang bekerja tanpa terminal interaktif melalui SDK. Pesan system/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:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage


async def main():
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
print("Available commands:", message.data["slash_commands"])


asyncio.run(main())

Daftar yang dicetak mencampur perintah bawaan, skills bundel, skills yang dapat dipanggil pengguna Anda, dan file .claude/commands/:

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

Skill dengan 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 opsi skills. 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.

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:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage


async def main():
# Compaction needs existing history, so have a conversation first
try:
async for message in query(
prompt="Explain what this project does",
options=ClaudeAgentOptions(max_turns=2),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as error:
# A single-shot query() raises after yielding an error result,
# so the follow-up query below still runs.
print(f"Session ended with an error: {error}")

# Compact the same conversation
async for message in query(
prompt="/compact",
options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
):
if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
print("Compaction completed")
print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
print("Trigger:", message.data["compact_metadata"]["trigger"])
# Example output:
# Compaction completed
# Pre-compaction tokens: 1842
# Trigger: manual


asyncio.run(main())

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 file SKILL.md dengan frontmatter YAML dan konten Markdown. Bidang description menentukan kapan Claude memanggil skill Anda.

Contoh struktur direktori:

.claude/skills/security-check/
└── SKILL.md

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

Jika Anda memiliki file perintah khusus yang ada di .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:

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

Setelah file ada, skill tersedia melalui SDK. Claude memanggilnya ketika permintaan cocok dengan deskripsinya, dan Anda dapat mendispatchnya secara langsung:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
async for message in query(
prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

Jalankan yang berhasil berakhir dengan hasil success yang teksnya membawa temuan pemindaian. Terhadap aplikasi Express kecil dengan masalah yang ditanam, teks hasil dimulai:

**Security scan of `app.js` — 4 findings (most severe first):**

1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

Nama skill juga muncul dalam array slash_commands pesan init.

Pra-setujui alat untuk skills

Skills berjalan dengan alat sesi. Contoh di bawah pra-menyetujui Read, Grep, dan Glob dengan allowedTools (allowed_tools di Python), jadi Claude dapat memeriksa file saat menjalankan skill security-check tanpa berhenti untuk persetujuan:

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)


async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Check this project for security issues",
options: {
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
console.log(message);
}

Dalam aliran, pemanggilan skill muncul sebagai penggunaan alat Skill, diikuti oleh panggilan Read pada file proyek. Jalannya berakhir dengan hasil 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 pengaturan user dan project. Jika Anda menetapkan settingSources/setting_sources secara eksplisit dan menghilangkan sumber tersebut, SDK tidak memuat skills:

# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)

// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};

// Skills loaded: user and project sources included
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};

Untuk direktori skill mana yang dimuat setiap sumber, lihat tabel sumber filesystem. Untuk detail lebih lanjut tentang 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:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Loads skills from these sources
skills="all",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};

Lihat Gunakan skills dengan Agent SDK untuk pola lengkapnya.

Verifikasi lokasi filesystem:

# Check project skills
ls .claude/skills/*/SKILL.md

# Check personal skills
ls ~/.claude/skills/*/SKILL.md

Skill tidak digunakan

Periksa opsi skills: 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 daftar skills 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 :*

Setiap SDK menampilkan penolakan secara berbeda:

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

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