Agent Skills dalam Claude API: cara menggunakan kemahiran sedia ada tanpa Claude Code

Anda boleh mendapatkan arahan tambahan dalam dokumentasi Ailoot.

Perkara yang anda perlukan#

Panduan ini adalah untuk memanggil API secara langsung daripada program, bukannya memasang kemahiran dalam Claude Code. Anda memerlukan kunci Claude API, akses kepada model yang dipilih dan Python 3. Kod di bawah menggunakan pustaka standard Python dan HTTP, jadi kod ini tidak bergantung pada versi SDK yang anda pasang. Kunci dihantar melalui pemboleh ubah persekitaran ANTHROPIC_API_KEY; jangan letakkannya dalam teks program atau perbualan.

API menyediakan kemahiran Anthropic sedia ada: pptx untuk pembentangan, xlsx untuk hamparan, docx untuk dokumen Word dan pdf untuk PDF. Kemahiran ini disambungkan menggunakan type: "anthropic". Panduan ini menggunakan kemahiran sedia ada tanpa memuat naik kemahiran tersuai.

Panduan mula pantas rasmi yang dibuka semasa bahan ini disediakan menggunakan gabungan claude-opus-5-5 dan code_execution_20260521. Gabungan yang sama digunakan di bawah. Contoh ini telah disemak berdasarkan dokumentasi; ini bukan laporan tentang panggilan API berbayar.

Pengepala beta yang diperlukan#

Contoh ini mengikuti kontrak HTTP semasa dalam panduan mula pantas: pengepalanya ialah x-api-key, anthropic-version: 2023-06-01 dan content-type: application/json; contoh ini tidak menghantar anthropic-beta. Jangan gabungkan model, kaedah panggilan dan format respons daripada generasi dokumentasi yang berlainan.

Dokumentasi Files API juga menyatakan bahawa API ini tidak lagi dalam beta. Pengepala lama files-api-2025-04-14 mengekalkan format respons lama; jika pengepala itu dibuang, format semasa akan digunakan. Itulah sebabnya contoh lama yang menggunakan client.beta.files tidak boleh digabungkan begitu sahaja dengan contoh baharu.

Di sini kita tidak sedang memindahkan perkhidmatan sedia ada daripada kontrak beta lama. Jika anda sudah mempunyai perkhidmatan sedemikian, semak pengepala dan format responsnya terlebih dahulu. Perkataan beta dalam nama kaedah SDK sahaja tidak mencukupi: dokumentasi Files API menerangkan secara berasingan cara versi SDK yang berbeza berfungsi.

Cipta pembentangan dan muat turun fail#

Contoh ini menghantar tugas untuk mencipta lima slaid tentang tenaga boleh baharu, menyimpan keseluruhan respons dalam skill-response.json, kemudian mengekstrak ID fail yang dijana. Contoh ini tidak mengambil laluan simpanan daripada respons model: fail disimpan dalam folder setempat baharu bernama skill-output. Jika folder itu sudah wujud, program akan berhenti supaya hasil terdahulu tidak ditulis ganti. Folder itu dicipta sebelum panggilan API, jadi ia juga kekal selepas panggilan gagal. Periksa dan simpan percubaan itu sebelum melakukan apa-apa lagi; jangan padamkannya semata-mata supaya larian semula berjaya.

import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

API = "https://api.anthropic.com/v1"
KEY = os.environ["ANTHROPIC_API_KEY"]
HEADERS = {
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
}

def request(path, payload=None, binary=False):
    data = None if payload is None else json.dumps(payload).encode("utf-8")
    req = Request(API + path, data=data, headers=HEADERS)
    try:
        with urlopen(req, timeout=600) as result:
            body = result.read()
    except HTTPError as error:
        try:
            details = json.loads(error.read().decode("utf-8"))
        except (ValueError, UnicodeError):
            details = {}
        info = details.get("error", {})
        request_id = error.headers.get("request-id") or details.get("request_id")
        diagnostic = {
            "http_status": error.code,
            "request_id": request_id,
            "error_type": info.get("type"),
            "message": str(info.get("message", "No JSON error message")).replace(KEY, "[REDACTED]")[:1000],
        }
        (out / "skill-error.json").write_text(
            json.dumps(diagnostic, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        raise RuntimeError(
            f"Claude API HTTP {error.code}; request_id={request_id}; inspect skill-error.json"
        ) from None
    return body if binary else json.loads(body)

out = Path("skill-output")
out.mkdir(exist_ok=False)
response = request("/messages", {
    "model": "claude-opus-5-5",
    "max_tokens": 16000,
    "container": {
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    "messages": [{
        "role": "user",
        "content": "Cipta pembentangan tentang tenaga boleh baharu dengan 5 slaid dalam bahasa pilihan saya.",
    }],
    "tools": [{"type": "code_execution_20260521", "name": "code_execution"}],
})
(out / "skill-response.json").write_text(
    json.dumps(response, ensure_ascii=False, indent=2), encoding="utf-8"
)
print("stop_reason:", response.get("stop_reason"))

file_ids = []
for block in response["content"]:
    if block["type"] == "bash_code_execution_tool_result":
        result = block["content"]
        if result["type"] == "bash_code_execution_result":
            for item in result["content"]:
                file_id = item.get("file_id")
                if file_id and file_id not in file_ids:
                    file_ids.append(file_id)
if not file_ids:
    raise RuntimeError("Tiada file_id yang dijana; periksa skill-response.json")

for index, file_id in enumerate(file_ids, start=1):
    from urllib.parse import quote
    file_path = "/files/" + quote(file_id, safe="")
    metadata = request(file_path)
    if metadata.get("downloadable") is not True:
        raise RuntimeError("Fail ini tidak boleh dimuat turun melalui Files API")
    target = out / f"result-{index}.pptx"
    target.write_bytes(request(file_path + "/content", binary=True))
    print("Disimpan:", target)

Nama result-1.pptx dan seterusnya dipilih untuk tugas pembentangan ini. Sambungan fail tidak membuktikan kandungan fail itu: buka dokumen yang dimuat turun dan semak format, bilangan slaid serta teksnya. Jangan anggap HTTP 200 sahaja atau kewujudan file_id sebagai hasil yang berjaya.

Program ini mencetak stop_reason, iaitu sebab respons dihentikan, dan menyimpan keseluruhan respons untuk diperiksa. Program ini tidak meneruskan perbualan atau mengulangi permintaan berbayar secara automatik. Fail yang telah dimuat turun tidak bermakna keseluruhan tugas telah selesai: periksa respons yang disimpan dan dokumen itu sendiri sebelum memutuskan sama ada permintaan lain diperlukan.

Jika percubaan gagal, periksa skill-error.json jika ada. Fail itu merekodkan status HTTP, ID permintaan jika dibekalkan dan mesej ralat penyedia yang dihadkan panjangnya serta dibuang nilai kunci API yang dikonfigurasikan. Semak mesej untuk kandungan peribadi lain sebelum berkongsi. Bandingkan ralat pengesahan, kebenaran/model, had bil dan format permintaan dengan rujukan ralat rasmi; jangan anggap semua kegagalan memerlukan penjanaan berbayar yang lain.

Jika skill-response.json sudah mengandungi nilai file_id yang dijana dan hanya muat turun gagal, simpan respons itu dan periksa langkah metadata/muat turun menggunakan akses ruang kerja dibenarkan yang sama. Jangan jalankan semula blok penjanaan hanya untuk memuat turun hasil sedia ada. Jika hasil permintaan tidak diketahui, simpan ID permintaannya dan tentukan statusnya sebelum menghantar penjanaan lain. Hanya selepas memutuskan penjanaan baharu diperlukan, ubah baris output setempat kepada laluan yang belum digunakan, contohnya out = Path("skill-output-attempt-2"), dan kekalkan exist_ok=False. Folder baharu mengelakkan penulisan ganti; ia tidak mengelakkan caj API berganda.

Kebenaran fail yang diperlukan#

Files API mengaitkan fail dengan ruang kerja, bukannya dengan pengguna individu aplikasi anda atau sesuatu perbualan. Menurut dokumentasi, mana-mana kunci API yang mempunyai akses kepada ruang kerja tersebut boleh mengakses fail yang dimuat naik ke sana. Contoh ini menggunakan kunci yang sama untuk memuat turun dan menjana fail. Jangan sekali-kali menerima file_id daripada pengguna akhir atau sumber lain yang tidak dipercayai. Simpan ID ini pada pelayan dan kekalkan pemetaan antara pengguna dengan fail mereka dalam aplikasi anda sendiri.

Semak metadata fail secara berasingan: metadata itu mesti mengandungi downloadable: true. Dokumentasi membenarkan muat turun fail yang dijana oleh kemahiran atau alat pelaksanaan kod; fail yang anda muat naik mempunyai downloadable: false, dan percubaan untuk memuat turunnya akan memulangkan 400. Akses kepada ruang kerja dan kebenaran untuk memuat turun fail tertentu ialah dua syarat yang berasingan.

Untuk aplikasi berbilang pengguna, dokumentasi Files API mengesyorkan ruang kerja yang berasingan bagi setiap pelanggan sebagai sempadan pengasingan fail. Syor ini khusus tentang fail; jangan lanjutkannya kepada semua entiti dan kebenaran tanpa menyemak API yang berkaitan.

Kemahiran sedia ada dan kemahiran tersuai#

Kemahiran sedia ada mempunyai ID pptx, xlsx, docx dan pdf. Dalam rujukan senarai kemahiran, sumber custom diterangkan sebagai peribadi kepada ruang kerja, manakala anthropic dikongsi dan baca sahaja.

version: "latest" dalam contoh pertama bermaksud versi kemahiran terbaharu yang diterbitkan. Untuk integrasi yang boleh dihasilkan semula, ambil perhatian bahawa pilihan ini boleh berubah; untuk beralih kepada versi tetap, pilih versi sedia ada bagi kemahiran yang anda gunakan, bukannya ID rekaan daripada contoh.

Batasan dan langkah seterusnya#

Contoh ini hanya merangkumi penciptaan pembentangan dengan kemahiran sedia ada dan muat turun fail tersebut. Memuat naik kemahiran tersuai, memadamkannya dan mengakses perkhidmatan pihak ketiga tidak diuji di sini. Tugas tersebut memerlukan semakan berasingan terhadap API yang berkaitan.

Jika tugas anda melibatkan fail dalam antara muka Claude, terdapat panduan berasingan tentang cara memuat naik fail ke Claude. Untuk panggilan langsung, lihat cara mengira penggunaan token API. Untuk kerja dalam ejen terminal, baca cara memilih kemahiran Claude Code: kemahiran itu disambungkan dengan cara yang berbeza.

Untuk semakan pertama, satu kemahiran pptx sedia ada sudah memadai: periksa respons, muat turun fail yang dibenarkan untuk dimuat turun dan buka fail itu. Tambahkan kemahiran tersuai dan pengasingan akses antara pelanggan selepas semakan tersebut.

Apabila anda sudah bersedia, kenali Ailoot.