Agent Skills v API-ju Claude: kako uporabiti že pripravljeno spretnost brez Claude Code

Dodatna navodila najdete v dokumentaciji Ailoot.

Kaj boste potrebovali#

Ta vodič je namenjen neposrednemu klicanju API-ja iz programa, ne pa nameščanju spretnosti v Claude Code. Potrebujete ključ API-ja Claude, dostop do izbranega modela in Python 3. Spodnja koda uporablja standardno knjižnico Pythona in HTTP, zato ni odvisna od različice SDK-ja, ki jo imate nameščeno. Ključ se posreduje prek spremenljivke okolja ANTHROPIC_API_KEY; ne vpisujte ga v besedilo programa ali pogovor.

API ponuja že pripravljene Anthropicove spretnosti: pptx za predstavitve, xlsx za preglednice, docx za Wordove dokumente in pdf za datoteke PDF. Povežete jih z uporabo type: "anthropic". Ta vodič uporablja že pripravljeno spretnost, brez nalaganja lastne spretnosti.

Uradni hitri začetek, ki je bil odprt med pripravo tega gradiva, uporablja kombinacijo claude-opus-5-5 in code_execution_20260521. Spodaj je uporabljena ta kombinacija. Primer je bil preverjen glede na dokumentacijo; ne gre za poročilo o izvedenem plačljivem klicu API-ja.

Katere beta-glave so potrebne#

Primer sledi veljavni pogodbi HTTP hitrega začetka: glave so x-api-key, anthropic-version: 2023-06-01 in content-type: application/json; anthropic-beta ni poslan. Ne kombinirajte modela, načina klicanja in oblike odgovora iz različnih generacij dokumentacije.

Tudi dokumentacija API-ja Files navaja, da API ni več v beta različici. Stara glava files-api-2025-04-14 ohrani stare oblike odgovorov; če glavo odstranite, se uporabijo trenutne oblike. Zato starega primera z client.beta.files ne morete preprosto združiti z novim.

Tukaj obstoječe storitve ne prenašamo s stare beta-pogodbe. Če takšno storitev že imate, najprej preverite njene glave in oblike odgovorov. Beseda beta v imenu metode SDK sama po sebi ne pove dovolj: dokumentacija API-ja Files ločeno pojasnjuje vedenje različnih različic SDK-ja.

Ustvarite predstavitev in prenesite datoteko#

Primer pošlje nalogo za pripravo petih diapozitivov o obnovljivih virih energije, celoten odgovor shrani v skill-response.json, nato pa pridobi ID-je ustvarjenih datotek. Poti za shranjevanje ne prevzame iz odgovora modela: datoteke se shranijo v novo lokalno mapo z imenom skill-output. Če ta mapa že obstaja, se program ustavi, da ne prepiše prejšnjega rezultata. Mapa se ustvari pred klicem API, zato ostane tudi po neuspelem klicu. Pred nadaljnjim poskusom preglejte in ohranite prejšnjega; mape ne izbrišite samo zato, da bi ponovni zagon lahko nadaljeval.

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": "Ustvari predstavitev o obnovljivih virih energije s 5 diapozitivi v mojem želenem jeziku.",
    }],
    "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("No generated file_id; inspect 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("This file cannot be downloaded through Files API")
    target = out / f"result-{index}.pptx"
    target.write_bytes(request(file_path + "/content", binary=True))
    print("Saved:", target)

Imeni result-1.pptx in tako naprej sta bili izbrani za to nalogo s predstavitvijo. Končnica datoteke ne dokazuje njene vsebine: odprite preneseni dokument in preverite njegovo obliko, število diapozitivov in besedilo. Sam HTTP 200 ali prisotnost file_id ne pomenita, da je bil postopek uspešen.

Program izpiše stop_reason, razlog, zakaj se je odgovor ustavil, in shrani celoten odgovor za pregled. Ne nadaljuje pogovora in plačljive zahteve ne ponovi samodejno. Prenesena datoteka še ne pomeni, da je naloga v celoti opravljena: preden se odločite, ali je potrebna še ena zahteva, preglejte shranjeni odgovor in sam dokument.

Pri neuspelem poskusu preglejte skill-error.json, če obstaja. Vsebuje status HTTP, ID zahteve, kadar je na voljo, in omejeno ponudnikovo sporočilo o napaki z odstranjeno nastavljeno vrednostjo ključa API. Pred deljenjem preverite, ali sporočilo vsebuje druge zasebne podatke. Napake pri avtentikaciji, dovoljenjih/modelu, omejitvah obračunavanja in obliki zahteve primerjajte z uradno referenco napak; ne sklepajte, da vsaka napaka zahteva novo plačljivo generiranje.

Če skill-response.json že vsebuje ustvarjene vrednosti file_id in je spodletel le prenos, odgovor ohranite ter z istim pooblaščenim dostopom do delovnega prostora preverite metapodatke/prenos. Bloka za generiranje ne zaganjajte znova samo za prenos obstoječega rezultata. Če izid zahteve ni znan, ohranite njen ID in razjasnite status pred novo generacijo. Šele ko ugotovite, da je novo generiranje potrebno, lokalno izhodno vrstico spremenite na neuporabljeno pot, na primer out = Path("skill-output-attempt-2"), in ohranite exist_ok=False. Nova mapa prepreči prepisovanje; ne prepreči dvojnega stroška API.

Katera dovoljenja za datoteke so potrebna#

API Files datoteke poveže z delovnim prostorom, ne pa s posameznim uporabnikom vaše aplikacije ali pogovorom. Po navedbah dokumentacije lahko do datotek, naloženih v delovni prostor, dostopa vsak ključ API, ki ima dostop do tega delovnega prostora. Primer za prenos uporablja isti ključ kot za ustvarjanje. Nikoli ne sprejemajte file_id od končnih uporabnikov ali drugih nezaupanja vrednih virov. ID-je shranjujte v strežniku in v svoji aplikaciji vzdržujte povezavo med uporabniki in njihovimi datotekami.

Metapodatke datoteke preverite ločeno: vsebovati morajo downloadable: true. Dokumentacija dovoljuje prenos datotek, ki jih ustvarijo spretnosti ali orodje za izvajanje kode; pri datotekah, ki jih naložite sami, je vrednost downloadable: false, poskus prenosa pa vrne napako 400. Dostop do delovnega prostora in možnost prenosa določene datoteke sta ločeni zahtevi.

Za večuporabniško aplikacijo dokumentacija API-ja Files priporoča ločen delovni prostor za vsako stranko kot mejo za izolacijo datotek. To priporočilo se nanaša posebej na datoteke; ne razširjajte ga na vse entitete in dovoljenja, ne da bi preverili ustrezni API.

Že pripravljene in lastne spretnosti#

Že pripravljene spretnosti imajo ID-je pptx, xlsx, docx in pdf. V referenci za seznam spretnosti je vir custom opisan kot zaseben za delovni prostor, medtem ko je anthropic skupen in samo za branje.

version: "latest" v prvem primeru pomeni najnovejšo objavljeno različico spretnosti. Pri ponovljivi integraciji upoštevajte, da se lahko ta izbira spremeni; za prehod na fiksno različico izberite obstoječo različico spretnosti, ki jo uporabljate, namesto da si izmislite ID iz primera.

Omejitve in naslednji korak#

Primer zajema samo ustvarjanje predstavitve z že pripravljeno spretnostjo in njen prenos. Nalaganje lastnih spretnosti, njihovo brisanje in dostop do storitev tretjih oseb tukaj niso bili preizkušeni. Za ta opravila je treba ločeno preveriti ustrezni API.

Če vaše opravilo vključuje datoteke v vmesniku Claude, si oglejte ločeni vodič o tem, kako naložiti datoteko v Claude. Za neposredne klice preberite, kako izračunati porabo žetonov API-ja. Za delo v terminalskem agentu preberite, kako izbrati spretnosti Claude Code: te se povezujejo na drugačen način.

Za prvo preverjanje zadostuje ena že pripravljena spretnost pptx: preglejte odgovor, prenesite datoteko, ki jo je dovoljeno prenesti, in jo odprite. Po tem preverjanju dodajte lastne spretnosti in ločite dostop med strankami.

Ko boste pripravljeni, spoznajte Ailoot.