Agent Skills Claude APIssa: näin käytät valmista skilliä ilman Claude Codea

Lisäohjeita on Ailoot-dokumentaatiossa.

Mitä tarvitset#

Tämä opas käsittelee API:n kutsumista suoraan ohjelmasta, ei skillin asentamista Claude Codeen. Tarvitset Claude API -avaimen, pääsyn valitsemaasi malliin ja Python 3:n. Alla oleva koodi käyttää Pythonin standardikirjastoa ja HTTP:tä, joten se ei riipu asentamastasi SDK-versiosta. Avain välitetään ympäristömuuttujan ANTHROPIC_API_KEY kautta; älä kirjoita sitä ohjelman tekstiin tai keskusteluun.

API tarjoaa valmiita Anthropic-skillejä: pptx esityksille, xlsx laskentataulukoille, docx Word-asiakirjoille ja pdf PDF-tiedostoille. Ne otetaan käyttöön määrittämällä type: "anthropic". Tässä oppaassa käytetään valmista skilliä ilman mukautetun skillin lataamista.

A virallisessa pika-aloitusoppaassa, joka avattiin tätä materiaalia valmisteltaessa, käytetään yhdistelmää claude-opus-5-5 ja code_execution_20260521. Alla käytetään samaa yhdistelmää. Esimerkki on tarkistettu dokumentaatiota vasten; se ei ole raportti maksullisen API-kutsun suorittamisesta.

Mitä beta-otsakkeita tarvitaan?#

Esimerkki noudattaa pika-aloitusoppaan nykyistä HTTP-sopimusta: otsakkeet ovat x-api-key, anthropic-version: 2023-06-01 ja content-type: application/json; se ei lähetä anthropic-beta-otsaketta. Älä yhdistä dokumentaation eri sukupolvista peräisin olevaa mallia, kutsutapaa ja vastausmuotoa.

Files API -dokumentaatiossa todetaan myös, että API ei ole enää betavaiheessa. Vanha files-api-2025-04-14-otsake säilyttää vanhat vastausmuodot; kun otsake poistetaan, käyttöön tulevat nykyiset muodot. Siksi vanhaa client.beta.files-esimerkkiä ei voi noin vain yhdistää uuteen esimerkkiin.

Tässä ei siirretä olemassa olevaa palvelua vanhasta betasopimuksesta. Jos sinulla on jo tällainen palvelu, tarkista ensin sen otsakkeet ja vastausmuodot. SDK-metodin nimessä oleva sana beta ei yksin riitä: Files API -dokumentaatiossa selitetään erikseen, miten eri SDK-versiot toimivat.

Luo esitys ja lataa tiedosto#

Esimerkissä lähetetään tehtävä, jossa luodaan viisi diaa uusiutuvasta energiasta, tallennetaan koko vastaus tiedostoon skill-response.json ja poimitaan sitten luotujen tiedostojen tunnisteet. Tiedoston tallennuspolkua ei oteta mallin vastauksesta: tiedostot tallennetaan uuteen paikalliseen skill-output-nimiseen kansioon. Jos kansio on jo olemassa, ohjelma pysähtyy, jotta se ei korvaa edellistä tulosta. Kansio luodaan ennen API-kutsua, joten se jää myös epäonnistuneen kutsun jälkeen. Tarkista ja säilytä kyseinen yritys ennen jatkamista; älä poista sitä vain saadaksesi uusinta-ajon onnistumaan.

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)

Nimet result-1.pptx ja niin edelleen on valittu tätä esitystehtävää varten. Tiedostopääte ei todista, mitä tiedosto sisältää: avaa ladattu asiakirja ja tarkista sen muoto, diojen määrä ja teksti. Älä pidä pelkkää HTTP 200 -vastausta tai file_id-tunnisteen olemassaoloa onnistuneena tuloksena.

Ohjelma tulostaa stop_reason-arvon eli syyn, miksi vastaus päättyi, ja tallentaa koko vastauksen tarkasteltavaksi. Se ei jatka keskustelua eikä toista maksullista pyyntöä automaattisesti. Ladattu tiedosto ei tarkoita, että koko tehtävä olisi valmis: tarkista tallennettu vastaus ja itse asiakirja ennen kuin päätät, tarvitaanko uusi pyyntö.

Jos yritys epäonnistuu, tarkista skill-error.json, jos se on olemassa. Siihen tallennetaan HTTP-tila, palveluntarjoajan antama pyyntötunniste ja pituudeltaan rajattu virheviesti, josta määritetty API-avain on poistettu. Tarkista viesti muun yksityisen sisällön varalta ennen jakamista. Vertaa tunnistautumis-, käyttöoikeus-/malli-, laskutusraja- ja pyyntömuotovirheitä viralliseen virheviitteeseen; jokainen epäonnistuminen ei edellytä uutta maksullista generointia.

Jos skill-response.json sisältää jo luotuja file_id-arvoja ja vain lataus epäonnistui, säilytä vastaus ja selvitä tiedoston metatieto-/latausvaihe samalla valtuutetulla työtilan käyttöoikeudella. Älä suorita generointilohkoa uudelleen vain ladataksesi olemassa olevan tuloksen. Jos pyynnön lopputulos on tuntematon, säilytä pyyntötunniste ja selvitä tila ennen uuden generoinnin lähettämistä. Vaihda paikallinen tulostepolku käyttämättömään polkuun, esimerkiksi out = Path("skill-output-attempt-2"), vasta kun uusi generointi on todettu tarpeelliseksi, ja säilytä exist_ok=False. Uusi kansio estää ylikirjoittamisen; se ei estä kaksinkertaista API-veloitusta.

Millaisia tiedostojen käyttöoikeuksia tarvitaan?#

Files API liittää tiedostot työtilaan, ei sovelluksesi yksittäiseen käyttäjään tai keskusteluun. Dokumentaation mukaan kaikki API-avaimet, joilla on pääsy kyseiseen työtilaan, voivat käyttää sinne ladattuja tiedostoja. Esimerkissä käytetään samaa avainta lataamiseen ja luomiseen. Älä koskaan hyväksy file_id-tunnistetta loppukäyttäjältä tai muusta epäluotetusta lähteestä. Tallenna tunnisteet palvelimelle ja ylläpidä käyttäjien ja heidän tiedostojensa välistä yhteyttä omassa sovelluksessasi.

Tarkista tiedoston metatiedot erikseen: niissä on oltava downloadable: true. Dokumentaatio sallii skilleillä tai koodinsuoritustyökalulla luotujen tiedostojen lataamisen; itse lataamiesi tiedostojen arvo on downloadable: false, ja latausyritys palauttaa 400-virheen. Työtilaan pääsy ja tietyn tiedoston latausoikeus ovat erillisiä vaatimuksia.

Usean käyttäjän sovelluksissa Files API -dokumentaatio suosittelee erillistä työtilaa kullekin asiakkaalle tiedostojen eristysrajana. Suositus koskee nimenomaan tiedostoja; älä laajenna sitä kaikkiin entiteetteihin ja käyttöoikeuksiin tarkistamatta asiaankuuluvaa API:a.

Valmiit ja mukautetut skillit#

Valmiiden skillien tunnisteet ovat pptx, xlsx, docx ja pdf. Skills-listan viitteessä lähdettä custom kuvataan työtilakohtaiseksi, kun taas anthropic on jaettu ja vain luku -muotoinen.

Ensimmäisen esimerkin version: "latest" tarkoittaa skillin viimeisintä julkaistua versiota. Jos haluat toistettavan integraation, huomioi, että tämä valinta voi muuttua; kiinteään versioon vaihtaminen edellyttää käyttämäsi skillin olemassa olevan version valitsemista, ei esimerkistä keksityn tunnisteen käyttämistä.

Rajoitukset ja seuraava vaihe#

Esimerkki kattaa vain esityksen luomisen valmiilla skillillä ja sen lataamisen. Mukautettujen skillien lataamista tai poistamista eikä kolmannen osapuolen palvelujen käyttöä ole testattu tässä. Nämä tehtävät edellyttävät asiaankuuluvan API:n erillistä tarkistusta.

Jos tehtäväsi koskee Claude-käyttöliittymässä olevia tiedostoja, tarjolla on erillinen opas siitä, kuinka tiedosto ladataan Claudeen. Suoria kutsuja varten katso kuinka API-tunnusten käyttö lasketaan. Jos työskentelet pääteagentissa, lue kuinka Claude Code -skillejä valitaan: ne yhdistetään eri tavalla.

Ensimmäiseen tarkistukseen riittää yksi valmis pptx-skill: tarkista vastaus, lataa tiedosto, jonka saa ladata, ja avaa se. Lisää mukautetut skillit ja asiakkaiden välinen käyttöoikeuksien erottelu tämän tarkistuksen jälkeen.

Kun olet valmis, tutustu Ailootiin.