Agent Skills i Claude API: sådan bruger du en færdig skill uden Claude Code

Du kan finde flere instruktioner i Ailoot-dokumentationen.

Det skal du bruge#

Denne vejledning handler om at kalde API'et direkte fra et program, ikke om at installere en skill i Claude Code. Du skal bruge en Claude API-nøgle, adgang til den valgte model og Python 3. Koden nedenfor bruger Pythons standardbibliotek og HTTP, så den afhænger ikke af, hvilken SDK-version du har installeret. Nøglen sendes via miljøvariablen ANTHROPIC_API_KEY; skriv den ikke ind i programteksten eller en samtale.

API'et tilbyder færdige Anthropic-skills: pptx til præsentationer, xlsx til regneark, docx til Word-dokumenter og pdf til PDF-filer. De forbindes med type: "anthropic". Denne vejledning bruger en færdig skill uden at uploade en brugerdefineret.

Den officielle quickstart, som blev åbnet, da dette materiale blev udarbejdet, bruger kombinationen claude-opus-5-5 og code_execution_20260521. Det er den kombination, der bruges nedenfor. Eksemplet er kontrolleret mod dokumentationen; det er ikke en rapport om et betalt API-kald.

Hvilke beta-headere er nødvendige?#

Eksemplet følger quickstartens aktuelle HTTP-kontrakt: headerne er x-api-key, anthropic-version: 2023-06-01 og content-type: application/json; det sender ikke anthropic-beta. Kombinér ikke en model, en kaldemetode og et svarformat fra forskellige generationer af dokumentationen.

Dokumentationen til Files API angiver også, at API'et er ude af beta. Den gamle header files-api-2025-04-14 bevarer de gamle svarformater; når headeren fjernes, skifter formaterne til de aktuelle. Derfor kan et gammelt eksempel med client.beta.files ikke bare kombineres med et nyt.

Vi migrerer ikke en eksisterende tjeneste fra den gamle betakontrakt her. Hvis du allerede har en sådan tjeneste, skal du først kontrollere dens headere og svarformater. Ordet beta i et SDK-metodenavn er ikke nok i sig selv: dokumentationen til Files API forklarer særskilt, hvordan forskellige SDK-versioner fungerer.

Opret en præsentation, og download filen#

Eksemplet sender en opgave om at oprette fem slides om vedvarende energi, gemmer hele svaret i skill-response.json og udtrækker derefter ID'erne på de genererede filer. Det henter ikke en sti til lagring fra modellens svar: filerne gemmes i en ny lokal mappe med navnet skill-output. Hvis mappen allerede findes, stopper programmet, så det ikke overskriver det tidligere resultat. Mappen oprettes før API-kaldet og bliver derfor også liggende efter et mislykket kald. Undersøg og bevar det forsøg, før du gør mere; slet ikke mappen blot for at få en ny kørsel til at fortsætte.

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": "Create a presentation about renewable energy with 5 slides in my preferred language.",
    }],
    "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)

Navnene result-1.pptx og så videre er valgt til denne præsentationsopgave. En filendelse beviser ikke, hvad filen indeholder: Åbn det downloadede dokument, og kontrollér formatet, antallet af slides og teksten. Betragt ikke alene HTTP 200 eller tilstedeværelsen af et file_id som et vellykket resultat.

Programmet udskriver stop_reason, årsagen til, at svaret blev afsluttet, og gemmer hele svaret til eftersyn. Det fortsætter ikke samtalen eller gentager automatisk den betalte forespørgsel. At have en downloadet fil betyder ikke, at hele opgaven er fuldført: Gennemgå det gemte svar og selve dokumentet, før du beslutter, om der er brug for en ny forespørgsel.

Ved et mislykket forsøg skal du gennemgå skill-error.json, hvis filen findes. Den indeholder HTTP-status, et eventuelt request-ID og en afgrænset fejlmeddelelse fra udbyderen, hvor den konfigurerede API-nøgle er fjernet. Kontrollér meddelelsen for andre private oplysninger, før du deler den. Sammenhold godkendelsesfejl, rettigheds-/modelfejl, betalingsgrænser og formatfejl med den officielle fejlreference; antag ikke, at alle fejl kræver en ny betalt generering.

Hvis skill-response.json allerede indeholder genererede file_id-værdier, og kun downloaden fejlede, skal du bevare svaret og undersøge metadata/download med samme autoriserede adgang til arbejdsområdet. Kør ikke genereringsblokken igen blot for at hente et eksisterende resultat. Er udfaldet ukendt, skal du bevare request-ID’et og afklare status før endnu en generering. Først når du har afgjort, at en ny generering er nødvendig, ændrer du den lokale outputlinje til en ubrugt sti, for eksempel out = Path("skill-output-attempt-2"), og beholder exist_ok=False. En ny mappe forhindrer overskrivning; den forhindrer ikke en dobbelt API-udgift.

Hvilke filtilladelser kræves?#

Files API knytter filer til et arbejdsområde snarere end til en enkelt bruger af din applikation eller en samtale. Ifølge dokumentationen kan enhver API-nøgle med adgang til det arbejdsområde få adgang til filer, der er uploadet dertil. Eksemplet bruger samme nøgle til download som til generering. Accepter aldrig et file_id fra slutbrugere eller andre kilder, du ikke har tillid til. Gem disse ID'er på serveren, og vedligehold tilknytningen mellem brugere og deres filer i din egen applikation.

Kontrollér filens metadata særskilt: De skal indeholde downloadable: true. Dokumentationen tillader download af filer, der er genereret af skills eller kodekørselværktøjet; filer, du uploader, har downloadable: false, og et forsøg på at downloade dem returnerer 400. Adgang til arbejdsområdet og muligheden for at downloade en bestemt fil er separate krav.

Til applikationer med flere brugere anbefaler dokumentationen til Files API et separat arbejdsområde for hver klient som grænse for filisolering. Anbefalingen handler specifikt om filer; udvid den ikke til alle entiteter og tilladelser uden at kontrollere den relevante API.

Færdige skills og brugerdefinerede skills#

De færdige skills har ID'erne pptx, xlsx, docx og pdf. I referencen til skills-listen beskrives kilden custom som privat for arbejdsområdet, mens anthropic er delt og skrivebeskyttet.

version: "latest" i det første eksempel betyder den seneste publicerede version af skillen. Hvis integrationen skal kunne reproduceres, skal du være opmærksom på, at dette valg kan ændre sig; hvis du skifter til en fast version, skal du vælge en eksisterende version af den skill, du bruger, i stedet for at opfinde et ID ud fra et eksempel.

Begrænsninger og næste skridt#

Eksemplet omfatter kun oprettelse af en præsentation med en færdig skill og download af den. Upload af brugerdefinerede skills, sletning af dem og adgang til tredjepartstjenester er ikke blevet testet her. Disse opgaver kræver et særskilt tjek af den relevante API.

Hvis din opgave handler om filer i Claude-grænsefladen, findes der en separat vejledning om hvordan du uploader en fil til Claude. Ved direkte kald kan du se hvordan du beregner API-tokenforbrug. Til arbejde i en terminalagent kan du læse hvordan du vælger Claude Code-skills: De forbindes på en anden måde.

Til det første tjek er én færdig pptx-skill nok: Gennemgå svaret, download en fil, der må downloades, og åbn den. Tilføj brugerdefinerede skills og adgangsadskillelse mellem klienter efter dette tjek.

Når du er klar, kan du lære Ailoot at kende.