Agent Skills dalam SDK
Perluas Claude dengan kemampuan khusus menggunakan Agent Skills dalam Claude Agent SDK
Ikhtisar
Agent Skills memperluas Claude dengan kemampuan khusus yang Claude secara otomatis memanggil ketika relevan. Skills dikemas sebagai file SKILL.md yang berisi instruksi, deskripsi, dan sumber daya pendukung opsional.
Untuk informasi komprehensif tentang Skills, termasuk manfaat, arsitektur, dan panduan penulisan, lihat ikhtisar Agent Skills.
Cara Skills Bekerja dengan SDK
Saat menggunakan Claude Agent SDK, Skills adalah:
- Didefinisikan sebagai artefak filesystem: Dibuat sebagai file
SKILL.mddi direktori tertentu (.claude/skills/) - Dimuat dari filesystem: Skills dimuat dari lokasi filesystem yang diatur oleh
settingSources(TypeScript) atausetting_sources(Python) - Ditemukan secara otomatis: Setelah pengaturan filesystem dimuat, metadata Skill ditemukan saat startup dari direktori pengguna dan proyek; konten penuh dimuat saat dipicu
- Dipanggil oleh model: Claude secara otomatis memilih kapan menggunakannya berdasarkan konteks
- Disaring melalui opsi
skills: Skills yang ditemukan diaktifkan secara default. Berikan daftar nama skill,"all", atau[]untuk mengontrol mana yang tersedia dalam sesi
Tidak seperti subagents (yang dapat didefinisikan secara programatis), Skills harus dibuat sebagai artefak filesystem. SDK tidak menyediakan API programatis untuk mendaftarkan Skills.
Skills ditemukan melalui sumber pengaturan filesystem. Dengan opsi query() default, SDK memuat sumber pengguna dan proyek, jadi skills di ~/.claude/skills/ dan <cwd>/.claude/skills/ tersedia. Jika Anda menetapkan settingSources secara eksplisit, sertakan 'user' atau 'project' untuk mempertahankan penemuan skill, atau gunakan opsi plugins untuk memuat skills dari jalur tertentu.
Menggunakan Skills dengan SDK
Atur opsi skills pada query() untuk mengontrol Skills mana yang tersedia untuk sesi. Ketika dihilangkan, Skills yang ditemukan diaktifkan dan alat Skill tersedia, sesuai dengan perilaku CLI. Berikan "all" untuk mengaktifkan setiap Skill yang ditemukan, daftar nama Skill untuk mengaktifkan hanya yang tersebut, atau [] untuk menonaktifkan semua. Ketika Anda menetapkan skills, SDK mengaktifkan alat Skill secara otomatis, jadi Anda tidak perlu mencantumkannya dalam allowedTools.
Setelah dikonfigurasi, Claude secara otomatis menemukan Skills dari filesystem dan memanggilnya ketika relevan dengan permintaan pengguna.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project", # Project with .claude/skills/
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all", # Enable 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: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
Untuk mengaktifkan hanya Skills tertentu, berikan nama mereka. Nama cocok dengan bidang name di SKILL.md atau nama direktori Skill. Gunakan plugin:skill untuk Skills yang disediakan plugin.
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
Opsi skills adalah filter konteks, bukan sandbox. Skills yang tidak tercantum disembunyikan dari model dan ditolak oleh alat Skill, tetapi file mereka tetap di disk dan dapat diakses melalui Read dan Bash.
Lokasi Skill
Skills dimuat dari direktori filesystem berdasarkan konfigurasi settingSources/setting_sources Anda:
- Project Skills (
.claude/skills/): Dibagikan dengan tim Anda melalui git - dimuat ketikasetting_sourcesmencakup"project" - User Skills (
~/.claude/skills/): Skills pribadi di semua proyek - dimuat ketikasetting_sourcesmencakup"user" - Plugin Skills: Disertakan dengan plugin Claude Code yang diinstal
Membuat Skills
Skills didefinisikan 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/processing-pdfs/
└── SKILL.md
Untuk panduan lengkap tentang membuat Skills, termasuk struktur SKILL.md, Skills multi-file, dan contoh, lihat:
- Agent Skills dalam Claude Code: Panduan lengkap dengan contoh
- Agent Skills Best Practices: Panduan penulisan dan konvensi penamaan
Pembatasan Alat
Bidang frontmatter allowed-tools di SKILL.md hanya didukung saat menggunakan Claude Code CLI secara langsung. Ini tidak berlaku saat menggunakan Skills melalui SDK.
Saat menggunakan SDK, kontrol akses alat melalui opsi allowedTools utama dalam konfigurasi query Anda.
Untuk mengontrol akses alat untuk Skills dalam aplikasi SDK, gunakan allowedTools untuk pra-persetujuan alat tertentu. Tanpa callback canUseTool, apa pun yang tidak ada dalam daftar ditolak:
Pernyataan impor dari contoh pertama diasumsikan dalam cuplikan kode berikut.
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(message);
}
Menemukan Skills yang Tersedia
Untuk melihat Skills mana yang tersedia dalam aplikasi SDK Anda, cukup tanyakan kepada Claude:
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
)
async for message in query(prompt="What Skills are available?", options=options):
print(message)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(message);
}
Claude akan mencantumkan Skills yang tersedia berdasarkan direktori kerja saat ini dan plugin yang diinstal.
Menguji Skills
Uji Skills dengan mengajukan pertanyaan yang cocok dengan deskripsi mereka:
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}
Claude secara otomatis memanggil Skill yang relevan jika deskripsi cocok dengan permintaan Anda.
Pemecahan Masalah
Skills Tidak Ditemukan
Periksa konfigurasi settingSources: Skills ditemukan melalui sumber pengaturan user dan project. Jika Anda menetapkan settingSources/setting_sources secara eksplisit dan menghilangkan sumber tersebut, skills tidak dimuat:
# 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 options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
skills: "all"
};
Untuk detail lebih lanjut tentang settingSources/setting_sources, lihat referensi SDK TypeScript atau referensi SDK Python.
Periksa direktori kerja: SDK memuat Skills relatif terhadap opsi cwd. Pastikan itu menunjuk ke direktori yang berisi .claude/skills/:
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # Must contain .claude/skills/
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", // Must contain .claude/skills/
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Lihat bagian "Menggunakan Skills dengan SDK" di atas 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 melewatkan daftar skills, konfirmasi nama skill disertakan. Melewatkan [] menonaktifkan semua skills.
Periksa deskripsi: Pastikan itu spesifik dan mencakup kata kunci yang relevan. Lihat Agent Skills Best Practices untuk panduan tentang menulis deskripsi yang efektif.
Pemecahan Masalah Tambahan
Untuk pemecahan masalah Skills umum (sintaks YAML, debugging, dll.), lihat bagian pemecahan masalah Claude Code Skills.
Dokumentasi Terkait
Panduan Skills
- Agent Skills dalam Claude Code: Panduan Skills lengkap dengan pembuatan, contoh, dan pemecahan masalah
- Agent Skills Overview: Ikhtisar konseptual, manfaat, dan arsitektur
- Agent Skills Best Practices: Panduan penulisan untuk Skills yang efektif
- Agent Skills Cookbook: Contoh Skills dan template
Sumber Daya SDK
- Subagents dalam SDK: Agen berbasis filesystem serupa dengan opsi programatis
- Slash Commands dalam SDK: Perintah yang dipanggil pengguna
- SDK Overview: Konsep SDK umum
- Referensi SDK TypeScript: Dokumentasi API lengkap
- Referensi SDK Python: Dokumentasi API lengkap