Agent Skills dalam SDK

Ringkasan

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 pedoman penulisan, lihat ringkasan Agent Skills.

Cara Skills Bekerja dengan SDK

Saat menggunakan Claude Agent SDK, Skills adalah:

1. Didefinisikan sebagai artefak sistem file: Dibuat sebagai file SKILL.md di direktori tertentu (.claude/skills/)
2. Dimuat dari sistem file: Skills dimuat dari lokasi sistem file yang dikonfigurasi. Anda harus menentukan settingSources (TypeScript) atau setting_sources (Python) untuk memuat Skills dari sistem file
3. Ditemukan secara otomatis: Setelah pengaturan sistem file dimuat, metadata Skill ditemukan saat startup dari direktori pengguna dan proyek; konten penuh dimuat ketika dipicu
4. Dipanggil model: Claude secara otomatis memilih kapan menggunakannya berdasarkan konteks
5. Diaktifkan melalui allowed_tools: Tambahkan "Skill" ke allowed_tools Anda untuk mengaktifkan Skills

Tidak seperti subagents (yang dapat didefinisikan secara terprogram), Skills harus dibuat sebagai artefak sistem file. SDK tidak menyediakan API terprogram untuk mendaftarkan Skills.

Menggunakan Skills dengan SDK

Untuk menggunakan Skills dengan SDK, Anda perlu:

1. Sertakan "Skill" dalam konfigurasi allowed_tools Anda
2. Konfigurasikan settingSources/setting_sources untuk memuat Skills dari sistem file

Setelah dikonfigurasi, Claude secara otomatis menemukan Skills dari direktori yang ditentukan 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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

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

asyncio.run(main())

Lokasi Skill

Skills dimuat dari direktori sistem file berdasarkan konfigurasi settingSources/setting_sources Anda:

• Project Skills (.claude/skills/): Dibagikan dengan tim Anda melalui git - dimuat ketika setting_sources mencakup "project"
• User Skills (~/.claude/skills/): Skills pribadi di semua proyek - dimuat ketika setting_sources mencakup "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: Pedoman penulisan dan konvensi penamaan

Pembatasan Alat

Untuk membatasi alat untuk Skills dalam aplikasi SDK, gunakan opsi allowedTools:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(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
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(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
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)

Claude secara otomatis memanggil Skill yang relevan jika deskripsi cocok dengan permintaan Anda.

Pemecahan Masalah

Skills Tidak Ditemukan

Periksa konfigurasi settingSources: Skills hanya dimuat ketika Anda secara eksplisit mengonfigurasi settingSources/setting_sources. Ini adalah masalah paling umum:

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Lihat bagian "Menggunakan Skills dengan SDK" di atas untuk pola lengkapnya.

Verifikasi lokasi sistem file:

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

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

Skill Tidak Digunakan

Periksa alat Skill diaktifkan: Konfirmasi "Skill" ada dalam allowedTools Anda.

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
• Ringkasan Agent Skills: Ringkasan konseptual, manfaat, dan arsitektur
• Agent Skills Best Practices: Pedoman penulisan untuk Skills yang efektif
• Agent Skills Cookbook: Contoh Skills dan template

Sumber Daya SDK

• Subagents dalam SDK: Agen berbasis sistem file serupa dengan opsi terprogram
• Slash Commands dalam SDK: Perintah yang dipanggil pengguna
• Ringkasan SDK: Konsep SDK umum
• Referensi SDK TypeScript: Dokumentasi API lengkap
• Referensi SDK Python: Dokumentasi API lengkap