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 bawaan maupun Skills kustom dengan Claude API.

Tautan cepat

Ikhtisar

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

Menggunakan Skills

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

Anda dapat menggunakan Skills dari dua sumber:

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 Skills berasal dan bagaimana Skills tersebut dikelola.

Prasyarat

Untuk menggunakan Skills, Anda memerlukan:

1. Kunci API Claude dari Claude Console
2. Alat eksekusi kode diaktifkan dalam permintaan Anda

Skills memerlukan alat eksekusi kode, jadi gunakan model dari daftar kompatibilitas model alat tersebut.

Menggunakan Skills dalam Messages

Parameter container

Skills ditentukan menggunakan parameter container di Messages API. Anda dapat menyertakan hingga 20 Skills untuk setiap permintaan.

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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), Skills mengembalikan atribut file_id dalam respons. Anda harus menggunakan Files API untuk mengunduh file-file ini.

Cara kerjanya:

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

Untuk menyediakan file input yang akan dikerjakan oleh Skills, 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.files.retrieve_metadata(file_id=file_id)
    file_content = client.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.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.files.list():
    print(f"{file.filename} - {file.created_at}")

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

Percakapan multi-giliran

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

client = anthropic.Anthropic()

# Permintaan pertama membuat container
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 container 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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

Skills dapat 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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 berjalan lama
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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 Skills

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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

Bundle 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 menulisnya, 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. Python SDK juga menyediakan helper files_from_dir yang menerima path direktori.

File diidentifikasi berdasarkan nama file yang Anda lampirkan (sufiks ;filename= dalam contoh cURL dan argumen nama file dalam contoh SDK). Untuk skill dalam panduan ini, buat zip dengan zip -r financial_skill.zip financial_skill/ dan gunakan sebagai pengganti placeholder example_skill.zip dalam opsi unggah zip.

zip -r financial_skill.zip financial_skill/
ant skills create --file financial_skill.zip

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Persyaratan:

• Harus menyertakan file SKILL.md di root unggahan (atau di tingkat teratas dari satu folder pembungkus)
• display_name bersifat opsional: jika dihilangkan, nilainya diturunkan dari name di SKILL.md; nilai eksplisit dapat berisi hingga 255 karakter dan tidak perlu unik dalam workspace
• 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 Skills

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

# Daftar semua Skills
ant skills list

# Daftar hanya Skills kustom
ant skills list --source custom

Lihat referensi API List Skills untuk opsi paginasi dan pemfilteran.

Mengambil Skill

Dapatkan detail tentang Skill tertentu:

ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Menghapus Skill

Menghapus Skill juga menghapus semua versinya.

ant skills delete --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Pembuatan versi

Skills mendukung pembuatan versi untuk mengelola pembaruan dengan aman:

Skills Anthropic:

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

Skills Kustom:

• ID versi yang dihasilkan otomatis: skver_01AbCdEfGhIjKlMnOpQrStUv
• 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. File yang Anda hilangkan tidak akan dibawa, dan name dalam SKILL.md versi baru harus cocok dengan nama Skill yang sudah ada. Contoh berikut mengunggah ulang bundle financial_skill/ lengkap dari Membuat Skill.

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

# Gunakan versi tertentu
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_ID"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Gunakan versi terbaru
ant messages create <<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.

Bagaimana Skills dimuat

Ketika Anda menentukan Skills dalam container:

1. Penemuan metadata: Claude melihat metadata untuk setiap Skill (nama, deskripsi) dalam prompt sistem.
2. Pemuatan file: File Skill disalin ke dalam container di /skills/{skill-name}/. Direktorinya adalah nama Skill (pptx untuk Skill Anthropic, name di SKILL.md untuk Skill kustom), bukan ID skill_01...-nya.
3. Penggunaan otomatis: Claude secara otomatis memuat dan menggunakan Skills ketika relevan dengan permintaan Anda.
4. Komposisi: Beberapa Skills dapat dikomposisikan bersama untuk alur kerja yang kompleks.

Claude memuat instruksi Skill lengkap hanya ketika diperlukan.

Kasus penggunaan

Skills cocok untuk pekerjaan organisasi maupun pribadi. 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, dan 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.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Gunakan bersama Excel untuk membuat model keuangan
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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)

Batas dan kendala

Batas permintaan

• Maksimum Skills per permintaan: 20
• Ukuran unggahan Skill maksimum: 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

Skills 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 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 (memengaruhi performa)

Strategi manajemen versi

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

Untuk produksi: kunci versi tertentu, sehingga pembaruan Skill tidak pernah mengubah perilaku yang sudah Anda deploy. Jika Anda menghilangkan version atau mengaturnya ke "latest", permintaan menggunakan versi terbaru dari Skill, sehingga versi yang diunggah oleh siapa pun di workspace langsung mengubah apa yang dijalankan agen produksi Anda. ID versi berasal dari respons create-version di Pembuatan versi atau dari API List Skill Versions. ID selalu berupa string, jadi beri tanda kutip dalam JSON atau YAML meskipun terlihat seperti angka.

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

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

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

Pertimbangan caching prompt

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

client = anthropic.Anthropic()

# Skills dirender ke dalam prompt sistem dalam urutan tetap yang ramah cache
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 Skills ([xlsx] vs [xlsx, pptx]) mengubah prefiks: cache miss, sedangkan daftar yang identik menghasilkan cache hit
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 Skills 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 versi tersebut mengubah deskripsi Skill.

Penanganan error

Tangani error terkait Skill dengan baik:

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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

Migrasi dari skills-2025-10-02

Skills API telah keluar dari beta dan tidak memerlukan header beta. Migrasi dari skills-2025-10-02 bersifat opsional: permintaan yang masih mengirimkannya tetap berfungsi dan tetap mengembalikan bentuk respons beta, sehingga integrasi yang sudah ada tetap berfungsi sampai Anda mengubahnya. Menghapus header tersebut mengalihkan permintaan-permintaan itu ke bentuk yang didokumentasikan di halaman ini:

Untuk bermigrasi:

1. Hapus header beta. Buang anthropic-beta: skills-2025-10-02 dari permintaan Anda. Di SDK, panggil client.skills alih-alih client.beta.skills; tetap menggunakan client.beta.skills hanya berfungsi pada rilis SDK yang tidak lagi mengirim header tersebut. Rilis sebelumnya mengirimkannya dari client.beta.skills bahkan tanpa argumen betas.
2. Ganti nama field dalam kode Anda: display_title menjadi display_name, latest_version menjadi latest_version_id, dan baca source.type alih-alih membandingkan source dengan string.
3. Gunakan ID versi. Di mana pun Anda menyimpan versi epoch-mikrodetik, simpan id versi sebagai gantinya, atau gunakan latest. Referensi Skill dalam permintaan Messages menerima ID versi, latest, atau (untuk Skills Anthropic) versi katalog.
4. Tinjau panggilan delete. DELETE /v1/skills/{skill_id} sekarang menghapus setiap versi bersama Skill. Jika Anda mengandalkan penolakan beta sebagai pengaman, tambahkan pemeriksaan Anda sendiri.

Skill yang semua versinya dihapus di bawah beta tidak memiliki versi terkini untuk dikembalikan: GET /v1/skills/{skill_id} mengembalikan error 400 dan Skill tersebut dihilangkan dari respons list sampai Anda mengunggah versi ke dalamnya. Anda masih dapat menghapusnya.

Namespace beta SDK

Mulai dari Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, dan C# SDK 12.44.0, client.beta.skills tidak lagi mengirim skills-2025-10-02 dan mengembalikan bentuk yang sama dengan client.skills, dengan nama tipe berprefiks Beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Namespace ini menerima argumen betas untuk fitur Skills yang masih dalam beta. Dalam tipe Messages beta, tipe referensi Skill container diganti namanya dari BetaSkill menjadi BetaContainerSkill (field yang sama: type, skill_id, version); BetaSkill sekarang menamai resource Skill, sesuai dengan Skill dan ContainerSkill dalam tipe non-beta. Rilis SDK sebelumnya memiliki tipe sesuai bentuk beta; jika Anda bergantung pada tipe-tipe tersebut, tetaplah pada rilis sebelumnya sampai Anda bermigrasi.

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.

Pencatatan audit

Jika organisasi Anda mengaktifkan Compliance API, Activity Feed-nya mencatat pembuatan dan penghapusan Skills serta versi Skill yang dilakukan dengan kunci API Claude atau dari Claude Console. Operasi yang terjadi saat Compliance API nonaktif tidak dicatat dan tidak dapat dipulihkan kemudian, jadi siapkan Compliance API sebelum Anda mengandalkan jejak audit ini.

Langkah selanjutnya