Langsung ke konten utama

​
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:
  1. Didefinisikan sebagai artefak filesystem: Dibuat sebagai file SKILL.md di direktori tertentu (.claude/skills/)
  2. Dimuat dari filesystem: Skills dimuat dari lokasi filesystem yang diatur oleh settingSources (TypeScript) atau setting_sources (Python)
  3. Ditemukan secara otomatis: Setelah pengaturan filesystem dimuat, metadata Skill ditemukan saat startup dari direktori pengguna dan proyek; konten penuh dimuat saat dipicu
  4. Dipanggil oleh model: Claude secara otomatis memilih kapan menggunakannya berdasarkan konteks
  5. 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/, <cwd>/.claude/skills/, dan .claude/skills/ di direktori induk mana pun dari <cwd> hingga akar repositori 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 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. 
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())
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"])
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 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:

​
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)

​
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)
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)
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",
)
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",
)
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

​
Sumber Daya SDK