Menggunakan Agent Skills dengan API

Keahlian di 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:

Skill Management API Reference - Operasi CRUD untuk Skills
Skill Versions API Reference - Manajemen versi

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Tautan Cepat

Mulai dengan Agent Skills

Buat Skill pertama Anda

Buat Skills Khusus

Praktik terbaik untuk membuat Skills

Ikhtisar

Untuk penjelasan mendalam tentang arsitektur dan aplikasi dunia nyata dari Agent Skills, baca posting blog teknik: 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 dieksekusi di lingkungan eksekusi kode.

Anda dapat menggunakan Skills dari dua sumber:

Aspek	Anthropic Skills	Custom Skills
Nilai Type	`anthropic`	`custom`
Skill IDs	Nama pendek: `pptx`, `xlsx`, `docx`, `pdf`	Dihasilkan: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format Versi	Berbasis tanggal: `20251013` atau `latest`	Epoch timestamp: `1759178010641129` atau `latest`

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 Claude dari Console
Header beta:
- code-execution-2025-08-25 - Mengaktifkan eksekusi kode (diperlukan untuk Skills)
- skills-2025-10-02 - Mengaktifkan Skills API
- files-api-2025-04-14 - Untuk mengunggah/mengunduh file ke/dari container
Alat eksekusi kode diaktifkan dalam permintaan Anda

Menggunakan Skills dalam Messages

Parameter Container

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

Strukturnya identik untuk Skills Anthropic dan custom. Tentukan type dan skill_id yang diperlukan, dan secara opsional sertakan version untuk mengikat 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-Putaran

Gunakan kembali kontainer yang sama di seluruh beberapa pesan dengan menentukan ID kontainer:

Operasi Berjalan Lama

Keterampilan dapat melakukan operasi yang memerlukan beberapa putaran. Tangani alasan penghentian pause_turn:

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

Menggunakan Beberapa Skills

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

Mengelola Skills Kustom

Membuat Skill

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

Persyaratan:

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

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

Mendaftar Skills

Ambil semua Skills yang tersedia untuk ruang kerja Anda, termasuk Skills pra-bangun Anthropic dan Skills kustom Anda. Gunakan parameter source untuk memfilter berdasarkan jenis skill:

Lihat referensi API Daftar 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 mengembalikan kesalahan 400.

Versioning

Skills mendukung versioning untuk mengelola pembaruan dengan aman:

Anthropic-Managed Skills:

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

Custom Skills:

Timestamp 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 Skill Dimuat

Ketika Anda menentukan Skills dalam container:

Penemuan Metadata: Claude melihat metadata untuk setiap Skill (nama, deskripsi) dalam system prompt
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.

Use Cases

Organizational Skills

Brand & Communications

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

Project Management

Struktur catatan dengan format khusus perusahaan (OKRs, decision logs)
Hasilkan tugas mengikuti konvensi tim
Buat ringkasan rapat dan pembaruan status yang terstandar

Business Operations

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

Personal Skills

Content Creation

Template dokumen khusus
Pemformatan dan styling khusus
Pembuatan konten khusus domain

Data Analysis

Pipeline pemrosesan data khusus
Template visualisasi khusus
Metode analitik khusus industri

Development & Automation

Template pembuatan kode
Framework pengujian
Alur kerja deployment

Contoh: Pemodelan Keuangan

Gabungkan Excel dan Skill analisis DCF khusus:

Batas dan Kendala

Batas Permintaan

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

Kendala Lingkungan

Skill berjalan dalam kontainer eksekusi kode dengan batasan berikut:

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

Lihat dokumentasi alat eksekusi kode 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 khusus + pembuatan dokumen

Hindari:

Menyertakan Skill yang tidak digunakan (mempengaruhi kinerja)

Strategi Manajemen Versi

Untuk produksi:

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

Untuk pengembangan:

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

Pertimbangan Prompt Caching

Saat menggunakan prompt caching, perhatikan bahwa mengubah daftar Skill dalam kontainer Anda memecahkan cache:

Untuk kinerja caching terbaik, jaga daftar Skill Anda tetap konsisten di seluruh permintaan.

Penanganan Kesalahan

Tangani kesalahan terkait Skill dengan baik:

Retensi Data

Agent Skills tidak tercakup oleh 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

Panduan Penulisan

Praktik terbaik untuk menulis Skills yang efektif

client = anthropic.Anthropic()

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

client = anthropic.Anthropic()
file_id = "file_abc123"
# Get file metadata
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")

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

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

# Permintaan pertama membuat kontainer
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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 kontainer 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-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Gunakan kembali kontainer
        "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-opus-4-7",
    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-opus-4-7",
        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-opus-4-7",
    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"}],
)

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
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

# 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-opus-4-7",
    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-opus-4-7",
    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 Skill memecahkan cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise