Menggunakan Agent Skills dengan API

Agent Skills memperluas kemampuan Claude melalui folder terorganisir yang berisi instruksi, skrip, dan sumber daya. Panduan ini menunjukkan cara menggunakan Skills yang sudah dibuat sebelumnya dan Skills kustom dengan Claude API.

Untuk referensi API lengkap termasuk skema permintaan/respons dan semua parameter, lihat:

Referensi API Manajemen Skill - Operasi CRUD untuk Skills
Referensi API Versi Skill - Manajemen versi

Tautan Cepat

Mulai dengan Agent Skills

Buat Skill pertama Anda

Buat Skills Kustom

Praktik terbaik untuk membuat Skills

Ikhtisar

Untuk penjelasan mendalam tentang arsitektur dan aplikasi dunia nyata dari Agent Skills, baca blog teknik kami: Equipping agents for the real world with Agent Skills.

Skills terintegrasi dengan Messages API melalui alat eksekusi kode. Baik menggunakan Skills yang sudah dibuat sebelumnya yang dikelola oleh Anthropic atau Skills kustom yang telah Anda unggah, bentuk integrasi identik—keduanya memerlukan eksekusi kode dan menggunakan struktur container yang sama.

Menggunakan Skills

Skills terintegrasi secara identik dalam Messages API terlepas dari sumbernya. Anda menentukan Skills dalam parameter container dengan skill_id, type, dan version opsional, dan mereka dieksekusi di lingkungan eksekusi kode. Anda dapat menggunakan Skills dari dua sumber:

Aspek	Skills Anthropic	Skills Kustom
Nilai type	`anthropic`	`custom`
ID Skill	Nama pendek: `pptx`, `xlsx`, `docx`, `pdf`	Dihasilkan: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format versi	Berbasis tanggal: `20251013` atau `latest`	Stempel waktu epoch: `1759178010641129` atau `latest`
Manajemen	Dibuat sebelumnya dan dikelola oleh Anthropic	Unggah dan kelola melalui Skills API
Ketersediaan	Tersedia untuk semua pengguna	Pribadi untuk ruang kerja Anda

Kedua sumber skill dikembalikan oleh endpoint List Skills (gunakan parameter source untuk memfilter). Bentuk integrasi dan lingkungan eksekusi identik—satu-satunya perbedaan adalah dari mana Skills berasal dan bagaimana mereka dikelola.

Prasyarat

Untuk menggunakan Skills, Anda memerlukan:

Kunci API Anthropic dari Console
Header Beta:
- code-execution-2025-08-25 - Mengaktifkan eksekusi kode (diperlukan untuk Skills)
- skills-2025-10-02 - Mengaktifkan Skills API
- files-api-2025-04-14 - Untuk mengunggah/mengunduh file ke/dari container
Alat eksekusi kode diaktifkan dalam permintaan Anda

Menggunakan Skills dalam Messages

Parameter Container

Skills ditentukan menggunakan parameter container dalam Messages API. Anda dapat menyertakan hingga 8 Skills per permintaan. Strukturnya identik untuk Skills Anthropic dan kustom—tentukan type dan skill_id yang diperlukan, dan secara opsional sertakan version untuk mengikat ke versi tertentu:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create a presentation about renewable energy"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Mengunduh File yang Dihasilkan

Ketika Skills membuat dokumen (Excel, PowerPoint, PDF, Word), mereka mengembalikan atribut file_id dalam respons. Anda harus menggunakan Files API untuk mengunduh file-file ini. Cara kerjanya:

Skills membuat file selama eksekusi kode
Respons mencakup file_id untuk setiap file yang dibuat
Gunakan Files API untuk mengunduh konten file aktual
Simpan secara lokal atau proses sesuai kebutuhan

Contoh: Membuat dan mengunduh file Excel

import anthropic

client = anthropic.Anthropic()

# Langkah 1: Gunakan Skill untuk membuat file
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create an Excel file with a simple budget spreadsheet"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Langkah 2: Ekstrak ID file dari respons
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == 'bash_code_execution_tool_result':
            content_item = item.content
            if content_item.type == 'bash_code_execution_result':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Langkah 3: Unduh file menggunakan Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Langkah 4: Simpan ke disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Operasi Files API tambahan:

# Dapatkan metadata file
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Daftar semua file
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Hapus file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

Untuk detail lengkap tentang Files API, lihat dokumentasi Files API.

Percakapan Multi-Turn

Gunakan kembali container yang sama di beberapa pesan dengan menentukan ID container:

# Permintaan pertama membuat container
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Lanjutkan percakapan dengan container yang sama
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Gunakan kembali container
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Operasi Berjalan Lama

Skills dapat melakukan operasi yang memerlukan beberapa turn. Tangani alasan penghentian pause_turn:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Tangani pause_turn untuk operasi panjang
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )

Respons mungkin mencakup alasan penghentian pause_turn, yang menunjukkan bahwa API menjeda operasi Skill yang berjalan lama. Anda dapat memberikan respons kembali apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya, atau memodifikasi konten jika Anda ingin mengganggu percakapan dan memberikan panduan tambahan.

Menggunakan Beberapa Skills

Gabungkan beberapa Skills dalam satu permintaan untuk menangani alur kerja yang kompleks:

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",
                "version": "latest"
            },
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            },
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Analyze sales data and create a presentation"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Mengelola Skills Kustom

Membuat Skill

Unggah Skill kustom Anda untuk membuatnya tersedia di ruang kerja Anda. Anda dapat mengunggah menggunakan jalur direktori atau objek file individual.

import anthropic

client = anthropic.Anthropic()

# Opsi 1: Menggunakan helper files_from_dir (Python saja, direkomendasikan)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Opsi 2: Menggunakan file zip
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Opsi 3: Menggunakan tuple file (nama file, konten file, tipe mime)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

Persyaratan:

Harus menyertakan file SKILL.md di tingkat atas
Semua file harus menentukan direktori root umum dalam jalur mereka
Ukuran unggahan total harus di bawah 8MB
Frontmatter YAML: name (maksimal 64 karakter), description (maksimal 1024 karakter)

Untuk skema permintaan/respons lengkap, lihat referensi API Create Skill.

Mendaftar Skills

Ambil semua Skills yang tersedia untuk ruang kerja Anda, termasuk Skills yang sudah dibuat sebelumnya oleh Anthropic dan Skills kustom Anda. Gunakan parameter source untuk memfilter berdasarkan jenis skill:

# Daftar semua Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# Daftar hanya Skills kustom
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

Lihat referensi API List Skills untuk opsi paginasi dan pemfilteran.

Mengambil Skill

Dapatkan detail tentang Skill tertentu:

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Menghapus Skill

Untuk menghapus Skill, Anda harus terlebih dahulu menghapus semua versinya:

# Langkah 1: Hapus semua versi
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Langkah 2: Hapus Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

Mencoba menghapus Skill dengan versi yang ada akan mengembalikan kesalahan 400.

Versioning

Skills mendukung versioning untuk mengelola pembaruan dengan aman: Skills yang Dikelola Anthropic:

Versi menggunakan format tanggal: 20251013
Versi baru dirilis saat pembaruan dilakukan
Tentukan versi yang tepat untuk stabilitas

Skills Kustom:

Stempel waktu epoch yang dihasilkan secara otomatis: 1759178010641129
Gunakan "latest" untuk selalu mendapatkan versi terbaru
Buat versi baru saat memperbarui file Skill

# Buat versi baru
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Gunakan versi tertentu
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Gunakan versi terbaru
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest"
        }]
    },
    messages=[{"role": "user", "content": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Lihat referensi API Create Skill Version untuk detail lengkap.

Bagaimana Skills Dimuat

Ketika Anda menentukan Skills dalam container:

Penemuan Metadata: Claude melihat metadata untuk setiap Skill (nama, deskripsi) dalam prompt sistem
Pemuatan File: File Skill disalin ke dalam container di /skills/{directory}/
Penggunaan Otomatis: Claude secara otomatis memuat dan menggunakan Skills ketika relevan dengan permintaan Anda
Komposisi: Beberapa Skills bersama-sama untuk alur kerja yang kompleks

Arsitektur pengungkapan progresif memastikan penggunaan konteks yang efisien—Claude hanya memuat instruksi Skill lengkap ketika diperlukan.

Kasus Penggunaan

Skills Organisasi

Brand & Komunikasi

Terapkan pemformatan khusus perusahaan (warna, font, tata letak) ke dokumen
Hasilkan komunikasi mengikuti template organisasi
Pastikan panduan merek yang konsisten di semua output

Manajemen Proyek

Struktur catatan dengan format khusus perusahaan (OKR, log keputusan)
Hasilkan tugas mengikuti konvensi tim
Buat ringkasan rapat dan pembaruan status yang standar

Operasi Bisnis

Buat laporan, proposal, dan analisis standar perusahaan
Jalankan prosedur analitik khusus perusahaan
Hasilkan model keuangan mengikuti template organisasi

Skills Pribadi

Pembuatan Konten

Template dokumen kustom
Pemformatan dan gaya khusus
Pembuatan konten khusus domain

Analisis Data

Pipeline pemrosesan data kustom
Template visualisasi khusus
Metode analitik khusus industri

Pengembangan & Otomasi

Template pembuatan kode
Kerangka kerja pengujian
Alur kerja penyebaran

Contoh: Pemodelan Keuangan

Gabungkan Skills Excel dan analisis DCF kustom:

# Buat Skill analisis DCF kustom
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"]
)

# Gunakan dengan Excel untuk membuat model keuangan
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Build a DCF valuation model for a SaaS company with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Batas dan Kendala

Batas Permintaan

Maksimal Skills per permintaan: 8
Ukuran unggahan Skill maksimal: 8MB (semua file digabungkan)
Batas frontmatter YAML: name 64 karakter, description 1024 karakter

Kendala Lingkungan

Skills berjalan di container eksekusi kode dengan batasan berikut:

Tidak ada akses jaringan - Tidak dapat melakukan panggilan API eksternal
Tidak ada instalasi paket runtime - Hanya paket yang sudah diinstal sebelumnya tersedia
Lingkungan terisolasi - Setiap permintaan mendapatkan container segar

Lihat dokumentasi alat eksekusi kode untuk paket yang tersedia.

Praktik Terbaik

Kapan Menggunakan Beberapa Skills

Gabungkan Skills ketika tugas melibatkan beberapa jenis dokumen atau domain: Kasus penggunaan yang baik:

Analisis data (Excel) + pembuatan presentasi (PowerPoint)
Pembuatan laporan (Word) + ekspor ke PDF
Logika domain kustom + pembuatan dokumen

Hindari:

Menyertakan Skills yang tidak digunakan (mempengaruhi kinerja)

Strategi Manajemen Versi

Untuk produksi:

# Ikat ke versi tertentu untuk stabilitas
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Versi tertentu
    }]
}

Untuk pengembangan:

# Gunakan latest untuk pengembangan aktif
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Selalu dapatkan yang terbaru
    }]
}

Pertimbangan Prompt Caching

Saat menggunakan prompt caching, perhatikan bahwa mengubah daftar Skills di container Anda akan memecahkan cache:

# Permintaan pertama membuat cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Menambah/menghapus Skills memecahkan cache
response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"}  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Untuk kinerja caching terbaik, pertahankan daftar Skills Anda tetap konsisten di seluruh permintaan.

Penanganan Kesalahan

Tangani kesalahan terkait Skill dengan baik:

try:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Tangani kesalahan khusus skill
    else:
        raise

Langkah Berikutnya

Referensi API

Referensi API lengkap dengan semua endpoint

Panduan Penulisan

Praktik terbaik untuk menulis Skills yang efektif

Alat Eksekusi Kode

Pelajari tentang lingkungan eksekusi kode

Menggunakan API

Referensi API

SDK

Contoh

API Pihak Ketiga

Menggunakan Admin API

Dukungan & konfigurasi

​Tautan Cepat

Mulai dengan Agent Skills

Buat Skills Kustom

​Ikhtisar

​Menggunakan Skills

​Prasyarat

​Menggunakan Skills dalam Messages

​Parameter Container

​Mengunduh File yang Dihasilkan

​Percakapan Multi-Turn

​Operasi Berjalan Lama

​Menggunakan Beberapa Skills

​Mengelola Skills Kustom

​Membuat Skill

​Mendaftar Skills

​Mengambil Skill

​Menghapus Skill

​Versioning

​Bagaimana Skills Dimuat

​Kasus Penggunaan

​Skills Organisasi

​Skills Pribadi

​Contoh: Pemodelan Keuangan

​Batas dan Kendala

​Batas Permintaan

​Kendala Lingkungan

​Praktik Terbaik

​Kapan Menggunakan Beberapa Skills

​Strategi Manajemen Versi

​Pertimbangan Prompt Caching

​Penanganan Kesalahan

​Langkah Berikutnya

Referensi API

Panduan Penulisan

Alat Eksekusi Kode

Tautan Cepat

Ikhtisar

Menggunakan Skills

Prasyarat

Menggunakan Skills dalam Messages

Parameter Container

Mengunduh File yang Dihasilkan

Percakapan Multi-Turn

Operasi Berjalan Lama

Menggunakan Beberapa Skills

Mengelola Skills Kustom

Membuat Skill

Mendaftar Skills

Mengambil Skill

Menghapus Skill

Versioning

Bagaimana Skills Dimuat

Kasus Penggunaan

Skills Organisasi

Skills Pribadi

Contoh: Pemodelan Keuangan

Batas dan Kendala

Batas Permintaan

Kendala Lingkungan

Praktik Terbaik

Kapan Menggunakan Beberapa Skills

Strategi Manajemen Versi

Pertimbangan Prompt Caching

Penanganan Kesalahan

Langkah Berikutnya