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 khusus 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 Khusus

Praktik terbaik untuk membuat Skills

Ikhtisar

Untuk pendalaman 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 khusus 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 dijalankan di lingkungan eksekusi kode.

Anda dapat menggunakan Skills dari dua sumber:

Aspek	Skills Anthropic	Skills Khusus
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

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 Konsol
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 Pesan

Parameter Container

Skills ditentukan menggunakan parameter container dalam Messages API. Anda dapat menyertakan hingga 8 Skills per permintaan.

Strukturnya identik untuk Skills Anthropic dan khusus—tentukan type dan skill_id yang diperlukan, dan secara opsional sertakan version untuk menyematkan ke versi tertentu:

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 sebenarnya
Simpan secara lokal atau proses sesuai kebutuhan

Contoh: Membuat dan mengunduh file Excel

Operasi Files API tambahan:

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:

Operasi Berjalan Lama

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

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 giliran, atau ubah konten jika Anda ingin menghentikan percakapan dan memberikan panduan tambahan.

Menggunakan Beberapa Skills

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

Mengelola Skills Khusus

Membuat Skill

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

Persyaratan:

Harus menyertakan file SKILL.md di tingkat atas
Semua file harus menentukan direktori root umum dalam jalur mereka
Total ukuran unggahan harus di bawah 8MB
Persyaratan frontmatter YAML:
- name: Maksimal 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan ("anthropic", "claude")
- description: Maksimal 1024 karakter, tidak kosong, tanpa tag XML

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

Daftar Skills

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

Lihat referensi API List Skills untuk opsi paginasi dan pemfilteran.

Mengambil Skill

Dapatkan detail tentang Skill tertentu:

Menghapus Skill

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

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 Khusus:

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

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 pertemuan dan pembaruan status 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 khusus
Pemformatan dan styling khusus
Pembuatan konten khusus domain

Analisis Data

Pipeline pemrosesan data khusus
Template visualisasi khusus
Metode analitik khusus industri

Pengembangan & Otomasi

Template pembuatan kode
Kerangka kerja pengujian
Alur kerja penerapan

Contoh: Pemodelan Keuangan

Gabungkan Skills Excel dan analisis DCF khusus:

Batas dan Kendala

Batas Permintaan

Maksimal Skills per permintaan: 8
Ukuran unggahan Skill maksimal: 8MB (semua file digabungkan)
Persyaratan frontmatter YAML:
- name: Maksimal 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan
- description: Maksimal 1024 karakter, tidak kosong, tanpa tag XML

Kendala Lingkungan

Skills berjalan di container eksekusi kode dengan batasan ini:

Tidak ada akses jaringan - Tidak dapat membuat 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 khusus + pembuatan dokumen

Hindari:

Menyertakan Skills yang tidak digunakan (berdampak pada kinerja)

Strategi Manajemen Versi

Untuk produksi:

# Sematkan 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 Caching Prompt

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

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

Penanganan Kesalahan

Tangani kesalahan terkait Skill dengan baik:

Langkah Berikutnya

Referensi API

Referensi API lengkap dengan semua endpoint

import anthropic

client = anthropic.Anthropic()

response = client.beta.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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Langkah 1: Gunakan Skill untuk membuat file
response = client.beta.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}")

# 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"]
)

# Permintaan pertama membuat container
response1 = client.beta.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.beta.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"}]
)

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

response = client.beta.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.beta.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"}]
    )

response = client.beta.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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Opsi 1: Menggunakan pembantu files_from_dir (hanya Python, 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}")

# 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 khusus
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

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}")

# 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"]
)

# 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.beta.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.beta.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"}]
)

# Buat Skill analisis DCF khusus
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.beta.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"}]
)

# Permintaan pertama membuat cache
response1 = client.beta.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.beta.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"}]
)

try:
    response = client.beta.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