Menggunakan Agent Skills dengan API

Pelajari cara menggunakan Agent Skills untuk memperluas kemampuan Claude melalui API.

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

Tautan cepat

Memulai dengan Agent Skills di API

Pelajari cara menggunakan Agent Skills untuk membuat dokumen dengan Claude API dalam waktu kurang dari 10 menit.

Praktik terbaik penulisan Skill

Pelajari cara menulis Skill yang efektif agar dapat ditemukan dan digunakan Claude dengan sukses.

Ikhtisar

Skill terintegrasi dengan Messages API melalui code execution tool. Baik menggunakan Skill bawaan yang dikelola oleh Anthropic maupun Skill kustom yang telah Anda unggah, bentuk integrasinya identik: keduanya memerlukan eksekusi kode dan menggunakan struktur container yang sama.

Menggunakan Skill

Skill terintegrasi secara identik di Messages API terlepas dari sumbernya. Anda menentukan Skill dalam parameter container dengan skill_id, type, dan version opsional, dan Skill tersebut berjalan di lingkungan eksekusi kode.

Anda dapat menggunakan Skill dari dua sumber:

Aspek	Skill Anthropic	Skill Kustom
Nilai type	`anthropic`	`custom`
Skill ID	Nama pendek: `pptx`, `xlsx`, `docx`, `pdf`	Dihasilkan otomatis: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format versi	Berbasis tanggal: `20251013` atau `latest`	Timestamp epoch: `1759178010641129` atau `latest`
Pengelolaan	Dibuat dan dikelola oleh Anthropic	Unggah dan kelola melalui Skills API
Ketersediaan	Tersedia untuk semua pengguna	Privat untuk workspace Anda

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

Prasyarat

Untuk menggunakan Skill, Anda memerlukan:

Kunci API Claude dari Claude Console
Header beta:
- code-execution-2025-08-25 - Mengaktifkan eksekusi kode (diperlukan untuk Skill)
- skills-2025-10-02 - Mengaktifkan Skills API
- files-api-2025-04-14 - Diperlukan hanya ketika Anda menggunakan Files API untuk mengunggah file input atau mengunduh file yang dihasilkan oleh Skill
Code execution tool diaktifkan dalam permintaan Anda

Skill memerlukan code execution tool, jadi gunakan model dari daftar kompatibilitas modelnya.

Menggunakan Skill dalam Messages

Parameter container

Skill ditentukan menggunakan parameter container di Messages API. Anda dapat menyertakan hingga 8 Skill untuk setiap permintaan.

Strukturnya identik untuk Skill Anthropic maupun kustom. Tentukan type dan skill_id yang diperlukan, dan secara opsional sertakan version untuk mengunci ke versi tertentu:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 Skill membuat dokumen (Excel, PowerPoint, PDF, Word), Skill mengembalikan atribut file_id dalam respons. Anda harus menggunakan Files API untuk mengunduh file-file ini.

Cara kerjanya:

Skill membuat file selama eksekusi kode.
Respons menyertakan file_id untuk setiap file yang dibuat, di dalam blok hasil alat eksekusi kode (lihat Format respons).
Gunakan Files API untuk mengunduh konten file yang sebenarnya.
Simpan secara lokal atau proses sesuai kebutuhan.

Untuk menyediakan file input agar dapat diproses oleh Skill, unggah file tersebut dengan Files API dan referensikan dalam permintaan Anda dengan blok container upload.

Contoh: membuat dan mengunduh file Excel

client = anthropic.Anthropic()

# Langkah 1: Gunakan Skill untuk membuat file
response = client.beta.messages.create(
    model="claude-opus-5",
    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":
                # setiap item konten adalah blok bash_code_execution_output yang membawa file_id
                for file in content_item.content:
                    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)
    file_content = client.beta.files.download(file_id=file_id)

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

Operasi Files API tambahan:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Dapatkan metadata file
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Daftar semua file
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Hapus file
client.beta.files.delete(file_id=file_id)

Percakapan multi-turn

Objek container dalam respons membawa id container dan timestamp expires_at (lihat Penggunaan ulang container untuk detail masa aktif). Gunakan kembali container yang sama di beberapa pesan dengan menentukan ID container:

client = anthropic.Anthropic()

# Permintaan pertama membuat kontainer
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Lanjutkan percakapan dengan kontainer yang sama
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Teruskan teks asisten; container.id membawa status eksekusi
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

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

Operasi yang berjalan lama

Skill mungkin melakukan operasi yang memerlukan beberapa giliran. Tangani stop reason pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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 yang lama
for _ 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-opus-5",
        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"}],
    )

Menggunakan beberapa Skill

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 Skill kustom

Membuat Skill

Bundel Skill adalah direktori yang berisi file SKILL.md di tingkat teratas dengan frontmatter YAML name dan description, ditambah skrip atau sumber daya pendukung apa pun. Lihat Memulai dengan Agent Skills di API untuk membuatnya, dan daftar Persyaratan setelah contoh-contoh berikut untuk batasan lengkapnya.

Unggah Skill kustom Anda agar tersedia di workspace Anda. Anda dapat mengunggah arsip zip atau objek file individual. SDK Python juga menyediakan helper files_from_dir yang menerima path direktori.

File diidentifikasi berdasarkan nama file yang Anda lampirkan. Unggahan per-file harus mempertahankan direktori tingkat teratas yang sama dalam path-nya (sufiks ;filename= dalam contoh cURL dan argumen nama file dalam contoh SDK). Arsip zip harus berisi direktori skill sebagai satu-satunya entri tingkat teratas. Untuk skill dalam panduan ini, buat arsip dengan zip -r financial_skill.zip financial_skill/ dan gantikan placeholder example_skill.zip dalam opsi unggah zip dengan file tersebut.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Unggahan per-file memerlukan nama file dengan kualifikasi path, yang saat ini
# tidak dapat diatur oleh CLI. Unggah arsip zip sebagai gantinya.

Persyaratan:

Harus menyertakan file SKILL.md di tingkat teratas
Semua file harus menentukan direktori root yang sama dalam path-nya
Nama direktori tingkat teratas harus cocok dengan name di frontmatter SKILL.md (tidak sensitif terhadap huruf besar/kecil dan garis bawah: Financial_Skill cocok dengan financial-skill)
display_title bersifat opsional: jika dihilangkan, nilainya diturunkan dari name di SKILL.md; nilai eksplisit harus unik di antara skill kustom dalam workspace Anda
Total ukuran unggahan harus di bawah 30 MB (tidak terkompresi)
Persyaratan frontmatter YAML:
- name: Maksimum 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan ("anthropic", "claude")
- description: Maksimum 1024 karakter, tidak boleh kosong, tanpa tag XML

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

Mendaftar Skill

Ambil semua Skill yang tersedia untuk workspace Anda, termasuk Skill bawaan Anthropic dan Skill kustom Anda. Gunakan parameter source untuk memfilter berdasarkan jenis skill:

# Daftar semua Skill
ant beta:skills list

# Daftar hanya Skill kustom
ant beta:skills list --source custom

Lihat referensi API List Skills untuk opsi paginasi dan pemfilteran.

Mengambil Skill

Dapatkan detail tentang Skill tertentu:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Menghapus Skill

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

# Langkah 1: Daftar versi-versinya, lalu hapus masing-masing
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Ulangi untuk setiap id versi yang dikembalikan oleh daftar
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Langkah 2: Hapus Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Mencoba menghapus Skill yang masih memiliki versi akan mengembalikan error 400.

Versioning

Skill mendukung versioning untuk mengelola pembaruan dengan aman:

Skill Anthropic:

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

Skill Kustom:

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

Versi baru adalah snapshot lengkap, bukan delta: unggah seluruh kumpulan file Skill setiap kali, di bawah nama direktori tingkat teratas yang sama seperti saat pembuatan. File yang Anda hilangkan tidak akan dibawa ke versi baru. Contoh berikut mengunggah ulang bundel financial_skill/ lengkap dari Membuat Skill.

# Buat versi baru
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Gunakan versi tertentu
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Gunakan versi terbaru
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
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
YAML

Lihat referensi API Create Skill Version untuk detail lengkap.

Cara Skill dimuat

Ketika Anda menentukan Skill 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/{skill-name}/. Direktori tersebut adalah nama Skill (pptx untuk Skill Anthropic, name dari SKILL.md untuk Skill kustom), bukan ID skill_01...-nya.
Penggunaan otomatis: Claude secara otomatis memuat dan menggunakan Skill ketika relevan dengan permintaan Anda.
Komposisi: Beberapa Skill dapat dikomposisikan bersama untuk alur kerja yang kompleks.

Claude memuat instruksi Skill lengkap hanya ketika diperlukan.

Kasus penggunaan

Skill cocok untuk pekerjaan organisasi maupun personal. Organisasi menggunakannya untuk menerapkan format merek pada dokumen, menyusun catatan dan laporan berdasarkan template perusahaan, dan menjalankan prosedur analitis khusus perusahaan. Individu menggunakannya untuk template dokumen kustom, pipeline data khusus, serta konvensi pembuatan kode atau deployment.

Contoh: pemodelan keuangan

Gabungkan Skill Excel dan Skill analisis DCF kustom:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Buat Skill analisis DCF kustom

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Gunakan dengan Excel untuk membuat model keuangan
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Batasan dan kendala

Batasan permintaan

Maksimum Skill per permintaan: 8
Maksimum ukuran unggahan Skill: 30 MB (semua file digabungkan, tidak terkompresi)
Persyaratan frontmatter YAML:
- name: Maksimum 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan ("anthropic", "claude")
- description: Maksimum 1024 karakter, tidak boleh kosong, tanpa tag XML

Kendala lingkungan

Skill berjalan di container eksekusi kode dengan batasan berikut:

Tanpa akses jaringan: Tidak dapat melakukan panggilan API eksternal
Tanpa instalasi paket saat runtime: Hanya paket yang sudah terinstal yang tersedia
Lingkungan terisolasi: Container baru dibuat kecuali Anda menentukan ID container yang sudah ada

Lihat Code execution tool untuk paket yang tersedia.

Praktik terbaik

Kapan menggunakan beberapa Skill

Gabungkan Skill 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 Skill yang tidak digunakan (memengaruhi performa)

Strategi manajemen versi

Tab SDK di bagian ini menunjukkan nilai container yang harus disertakan dalam permintaan Messages. Tab cURL dan CLI menunjukkan permintaan lengkap.

Untuk produksi: kunci ke versi tertentu, sehingga pembaruan Skill tidak pernah mengubah perilaku yang telah Anda deploy. ID versi berasal dari respons create-version di Versioning atau dari API List Skill Versions. ID selalu berupa string: beri tanda kutip pada ID timestamp epoch dalam JSON atau YAML.

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

Untuk pengembangan: gunakan latest untuk mengambil versi terbaru secara otomatis saat Anda melakukan iterasi.

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

Pertimbangan caching prompt

Jika Anda menggunakan Caching prompt, mengubah daftar Skill dalam container Anda akan merusak cache. Skill dirender ke dalam prompt sistem dalam urutan tetap, sehingga daftar yang sama menghasilkan prefiks yang dapat di-cache yang sama:

client = anthropic.Anthropic()

# Skill di-render ke dalam prompt sistem dengan urutan tetap yang ramah cache
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Mengubah daftar Skill ([xlsx] vs [xlsx, pptx]) mengubah prefiks: cache miss, sedangkan daftar yang identik menghasilkan cache hit
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Untuk performa caching terbaik, jaga agar daftar Skill Anda, termasuk urutannya, konsisten di seluruh permintaan. Mengunci versi Skill kustom juga membantu: dengan "latest", menerbitkan versi baru dapat membatalkan prefiks yang di-cache jika hal itu mengubah deskripsi Skill.

Penanganan error

Tangani error terkait Skill dengan baik:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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 error khusus skill
    else:
        raise

Retensi data

Agent Skills tidak tercakup dalam pengaturan ZDR. Definisi Skill dan data eksekusi disimpan sesuai dengan kebijakan retensi data standar Anthropic.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Langkah selanjutnya

Referensi API

Referensi API lengkap dengan semua endpoint

Praktik terbaik penulisan Skill

Pelajari cara menulis Skill yang efektif agar dapat ditemukan dan digunakan Claude dengan sukses.

Code execution tool

Jalankan kode Python dan bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan melakukan iterasi pada solusi.

Was this page helpful?

MessagesSkills

Menggunakan Agent Skills dengan API

Pelajari cara menggunakan Agent Skills untuk memperluas kemampuan Claude melalui API.

Tautan cepat

Memulai dengan Agent Skills di API

Pelajari cara menggunakan Agent Skills untuk membuat dokumen dengan Claude API dalam waktu kurang dari 10 menit.

Praktik terbaik penulisan Skill

Pelajari cara menulis Skill yang efektif agar dapat ditemukan dan digunakan Claude dengan sukses.

Ikhtisar

Menggunakan Skill

Anda dapat menggunakan Skill dari dua sumber:

Aspek	Skill Anthropic	Skill Kustom
Nilai type	`anthropic`	`custom`
Skill ID	Nama pendek: `pptx`, `xlsx`, `docx`, `pdf`	Dihasilkan otomatis: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format versi	Berbasis tanggal: `20251013` atau `latest`	Timestamp epoch: `1759178010641129` atau `latest`
Pengelolaan	Dibuat dan dikelola oleh Anthropic	Unggah dan kelola melalui Skills API
Ketersediaan	Tersedia untuk semua pengguna	Privat untuk workspace Anda

Prasyarat

Untuk menggunakan Skill, Anda memerlukan:

Kunci API Claude dari Claude Console
Header beta:
- code-execution-2025-08-25 - Mengaktifkan eksekusi kode (diperlukan untuk Skill)
- skills-2025-10-02 - Mengaktifkan Skills API
- files-api-2025-04-14 - Diperlukan hanya ketika Anda menggunakan Files API untuk mengunggah file input atau mengunduh file yang dihasilkan oleh Skill
Code execution tool diaktifkan dalam permintaan Anda

Skill memerlukan code execution tool, jadi gunakan model dari daftar kompatibilitas modelnya.

Menggunakan Skill dalam Messages

Parameter container

Skill ditentukan menggunakan parameter container di Messages API. Anda dapat menyertakan hingga 8 Skill untuk setiap permintaan.

Strukturnya identik untuk Skill Anthropic maupun kustom. Tentukan type dan skill_id yang diperlukan, dan secara opsional sertakan version untuk mengunci ke versi tertentu:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 Skill membuat dokumen (Excel, PowerPoint, PDF, Word), Skill mengembalikan atribut file_id dalam respons. Anda harus menggunakan Files API untuk mengunduh file-file ini.

Cara kerjanya:

Skill membuat file selama eksekusi kode.
Respons menyertakan file_id untuk setiap file yang dibuat, di dalam blok hasil alat eksekusi kode (lihat Format respons).
Gunakan Files API untuk mengunduh konten file yang sebenarnya.
Simpan secara lokal atau proses sesuai kebutuhan.

Untuk menyediakan file input agar dapat diproses oleh Skill, unggah file tersebut dengan Files API dan referensikan dalam permintaan Anda dengan blok container upload.

Contoh: membuat dan mengunduh file Excel

client = anthropic.Anthropic()

# Langkah 1: Gunakan Skill untuk membuat file
response = client.beta.messages.create(
    model="claude-opus-5",
    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":
                # setiap item konten adalah blok bash_code_execution_output yang membawa file_id
                for file in content_item.content:
                    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)
    file_content = client.beta.files.download(file_id=file_id)

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

Operasi Files API tambahan:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Dapatkan metadata file
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Daftar semua file
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Hapus file
client.beta.files.delete(file_id=file_id)

Percakapan multi-turn

client = anthropic.Anthropic()

# Permintaan pertama membuat kontainer
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Lanjutkan percakapan dengan kontainer yang sama
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Teruskan teks asisten; container.id membawa status eksekusi
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

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

Operasi yang berjalan lama

Skill mungkin melakukan operasi yang memerlukan beberapa giliran. Tangani stop reason pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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 yang lama
for _ 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-opus-5",
        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"}],
    )

Menggunakan beberapa Skill

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 Skill kustom

Membuat Skill

Unggah Skill kustom Anda agar tersedia di workspace Anda. Anda dapat mengunggah arsip zip atau objek file individual. SDK Python juga menyediakan helper files_from_dir yang menerima path direktori.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Unggahan per-file memerlukan nama file dengan kualifikasi path, yang saat ini
# tidak dapat diatur oleh CLI. Unggah arsip zip sebagai gantinya.

Persyaratan:

Harus menyertakan file SKILL.md di tingkat teratas
Semua file harus menentukan direktori root yang sama dalam path-nya
Nama direktori tingkat teratas harus cocok dengan name di frontmatter SKILL.md (tidak sensitif terhadap huruf besar/kecil dan garis bawah: Financial_Skill cocok dengan financial-skill)
display_title bersifat opsional: jika dihilangkan, nilainya diturunkan dari name di SKILL.md; nilai eksplisit harus unik di antara skill kustom dalam workspace Anda
Total ukuran unggahan harus di bawah 30 MB (tidak terkompresi)
Persyaratan frontmatter YAML:
- name: Maksimum 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan ("anthropic", "claude")
- description: Maksimum 1024 karakter, tidak boleh kosong, tanpa tag XML

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

Mendaftar Skill

Ambil semua Skill yang tersedia untuk workspace Anda, termasuk Skill bawaan Anthropic dan Skill kustom Anda. Gunakan parameter source untuk memfilter berdasarkan jenis skill:

# Daftar semua Skill
ant beta:skills list

# Daftar hanya Skill kustom
ant beta:skills list --source custom

Lihat referensi API List Skills untuk opsi paginasi dan pemfilteran.

Mengambil Skill

Dapatkan detail tentang Skill tertentu:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Menghapus Skill

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

# Langkah 1: Daftar versi-versinya, lalu hapus masing-masing
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version \
  --raw-output

# Ulangi untuk setiap id versi yang dikembalikan oleh daftar
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Langkah 2: Hapus Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Mencoba menghapus Skill yang masih memiliki versi akan mengembalikan error 400.

Versioning

Skill mendukung versioning untuk mengelola pembaruan dengan aman:

Skill Anthropic:

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

Skill Kustom:

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

# Buat versi baru
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Gunakan versi tertentu
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Gunakan versi terbaru
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
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
YAML

Lihat referensi API Create Skill Version untuk detail lengkap.

Cara Skill dimuat

Ketika Anda menentukan Skill 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/{skill-name}/. Direktori tersebut adalah nama Skill (pptx untuk Skill Anthropic, name dari SKILL.md untuk Skill kustom), bukan ID skill_01...-nya.
Penggunaan otomatis: Claude secara otomatis memuat dan menggunakan Skill ketika relevan dengan permintaan Anda.
Komposisi: Beberapa Skill dapat dikomposisikan bersama untuk alur kerja yang kompleks.

Claude memuat instruksi Skill lengkap hanya ketika diperlukan.

Kasus penggunaan

Contoh: pemodelan keuangan

Gabungkan Skill Excel dan Skill analisis DCF kustom:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Buat Skill analisis DCF kustom

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Gunakan dengan Excel untuk membuat model keuangan
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Batasan dan kendala

Batasan permintaan

Maksimum Skill per permintaan: 8
Maksimum ukuran unggahan Skill: 30 MB (semua file digabungkan, tidak terkompresi)
Persyaratan frontmatter YAML:
- name: Maksimum 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan ("anthropic", "claude")
- description: Maksimum 1024 karakter, tidak boleh kosong, tanpa tag XML

Kendala lingkungan

Skill berjalan di container eksekusi kode dengan batasan berikut:

Tanpa akses jaringan: Tidak dapat melakukan panggilan API eksternal
Tanpa instalasi paket saat runtime: Hanya paket yang sudah terinstal yang tersedia
Lingkungan terisolasi: Container baru dibuat kecuali Anda menentukan ID container yang sudah ada

Lihat Code execution tool untuk paket yang tersedia.

Praktik terbaik

Kapan menggunakan beberapa Skill

Gabungkan Skill 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 Skill yang tidak digunakan (memengaruhi performa)

Strategi manajemen versi

Tab SDK di bagian ini menunjukkan nilai container yang harus disertakan dalam permintaan Messages. Tab cURL dan CLI menunjukkan permintaan lengkap.

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

Untuk pengembangan: gunakan latest untuk mengambil versi terbaru secara otomatis saat Anda melakukan iterasi.

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

Pertimbangan caching prompt

client = anthropic.Anthropic()

# Skill di-render ke dalam prompt sistem dengan urutan tetap yang ramah cache
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Mengubah daftar Skill ([xlsx] vs [xlsx, pptx]) mengubah prefiks: cache miss, sedangkan daftar yang identik menghasilkan cache hit
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Penanganan error

Tangani error terkait Skill dengan baik:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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 error khusus skill
    else:
        raise

Retensi data

Agent Skills tidak tercakup dalam pengaturan ZDR. Definisi Skill dan data eksekusi disimpan sesuai dengan kebijakan retensi data standar Anthropic.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Langkah selanjutnya

Referensi API

Referensi API lengkap dengan semua endpoint

Praktik terbaik penulisan Skill

Pelajari cara menulis Skill yang efektif agar dapat ditemukan dan digunakan Claude dengan sukses.

Code execution tool

Jalankan kode Python dan bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan melakukan iterasi pada solusi.

Was this page helpful?

Tautan cepat

Ikhtisar

Menggunakan Skill

Prasyarat

Menggunakan Skill dalam Messages

Parameter container

Mengunduh file yang dihasilkan

Percakapan multi-turn

Operasi yang berjalan lama

Menggunakan beberapa Skill

Mengelola Skill kustom

Membuat Skill

Mendaftar Skill

Mengambil Skill

Menghapus Skill

Versioning

Cara Skill dimuat

Kasus penggunaan

Contoh: pemodelan keuangan

Batasan dan kendala

Batasan permintaan

Kendala lingkungan

Praktik terbaik

Kapan menggunakan beberapa Skill

Strategi manajemen versi

Pertimbangan caching prompt

Penanganan error

Retensi data

Langkah selanjutnya

Tautan cepat

Ikhtisar

Menggunakan Skill

Prasyarat

Menggunakan Skill dalam Messages

Parameter container

Mengunduh file yang dihasilkan

Percakapan multi-turn

Operasi yang berjalan lama

Menggunakan beberapa Skill

Mengelola Skill kustom

Membuat Skill

Mendaftar Skill

Mengambil Skill

Menghapus Skill

Versioning

Cara Skill dimuat

Kasus penggunaan

Contoh: pemodelan keuangan

Batasan dan kendala

Batasan permintaan

Kendala lingkungan

Praktik terbaik

Kapan menggunakan beberapa Skill

Strategi manajemen versi

Pertimbangan caching prompt

Penanganan error

Retensi data

Langkah selanjutnya

Tautan cepat

Ikhtisar

Menggunakan Skill

Prasyarat

Menggunakan Skill dalam Messages

Parameter container

Mengunduh file yang dihasilkan

Percakapan multi-turn

Operasi yang berjalan lama

Menggunakan beberapa Skill

Mengelola Skill kustom

Membuat Skill

Mendaftar Skill

Mengambil Skill

Menghapus Skill

Versioning

Cara Skill dimuat

Kasus penggunaan

Contoh: pemodelan keuangan

Batasan dan kendala

Batasan permintaan

Kendala lingkungan

Praktik terbaik

Kapan menggunakan beberapa Skill

Strategi manajemen versi

Pertimbangan caching prompt

Penanganan error

Retensi data

Langkah selanjutnya

Tautan cepat

Ikhtisar

Menggunakan Skill

Prasyarat

Menggunakan Skill dalam Messages

Parameter container

Mengunduh file yang dihasilkan

Percakapan multi-turn

Operasi yang berjalan lama

Menggunakan beberapa Skill

Mengelola Skill kustom

Membuat Skill

Mendaftar Skill

Mengambil Skill

Menghapus Skill

Versioning

Cara Skill dimuat

Kasus penggunaan

Contoh: pemodelan keuangan

Batasan dan kendala

Batasan permintaan

Kendala lingkungan

Praktik terbaik

Kapan menggunakan beberapa Skill

Strategi manajemen versi

Pertimbangan caching prompt

Penanganan error

Retensi data

Langkah selanjutnya