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:

​
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:
AspekSkills AnthropicSkills Khusus
Nilai typeanthropiccustom
ID SkillNama pendek: pptx, xlsx, docx, pdfDihasilkan: skill_01AbCdEfGhIjKlMnOpQrStUv
Format versiBerbasis tanggal: 20251013 atau latestStempel waktu epoch: 1759178010641129 atau latest
ManajemenDibuat sebelumnya dan dikelola oleh AnthropicUnggah dan kelola melalui Skills API
KetersediaanTersedia untuk semua penggunaPribadi 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:
  1. Kunci API Anthropic dari Konsol
  2. 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
  3. 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: 
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"
    }]
)

​
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:
  1. Skills membuat file selama eksekusi kode
  2. Respons mencakup file_id untuk setiap file yang dibuat
  3. Gunakan Files API untuk mengunduh konten file sebenarnya
  4. 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.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}")
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.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"}]
)

​
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.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"}]
    )
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: 
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"
    }]
)

​
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. 
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}")
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: 
# 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"]
)
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 Khusus:
  • 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.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"}]
)
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/{directory}/
  3. Penggunaan Otomatis: Claude secara otomatis memuat dan menggunakan Skills ketika relevan dengan permintaan Anda
  4. 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: 
# 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"}]
)

​
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: 
# 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"}]
)
Untuk kinerja caching terbaik, pertahankan daftar Skills Anda tetap konsisten di seluruh permintaan.

​
Penanganan Kesalahan

Tangani kesalahan terkait Skill dengan baik: 
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

​
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