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

> Näin yhdistät valmiin pptx-skillin Claude APIin: container.skills, koodinsuoritustyökalu, vastauksen tarkistaminen ja esityksen lataaminen Files APIlla.

Source: https://ailoot.ai/blog/fi/claude-api-agent-skills/
Canonical: https://ailoot.ai/blog/fi/claude-api-agent-skills/
Language: fi
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-039
Revision: sha256-e6ee8973a927f3dc0f0fe48a9ee242a517d981a45975797ce9f3214cb641d7b8


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Tämän osion tärkein asia">

Tärkein asia

Valmiita dokumenttien Agent Skills -skillejä voi käyttää suoraan Claude APIsta: määritä skilli kohdassa `container.skills` ja ota `code_execution` käyttöön. Käytä ensimmäisessä pyynnössä virallisessa esimerkissä olevaa yhteensopivaa malli- ja työkaluyhdistelmää. Lataa luotu tiedosto erikseen sen `file_id`-tunnisteella; esimerkissä samaa API-avainta käytetään sekä pyyntöön että lataukseen.

</div>



Lisäohjeita on [Ailoot-dokumentaatiossa](https://ailoot.ai/docs/).

## 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart.md), 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](https://platform.claude.com/docs/en/build-with-claude/files.md) 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.

```python
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](https://platform.claude.com/docs/en/api/errors); 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ä](https://platform.claude.com/docs/en/api/skills/list.md) 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](https://ailoot.ai/blog/fi/claude-file-upload/). Suoria kutsuja varten katso [kuinka API-tunnusten käyttö lasketaan](https://ailoot.ai/blog/fi/api-token-usage-calculation/). Jos työskentelet pääteagentissa, lue [kuinka Claude Code -skillejä valitaan](https://ailoot.ai/blog/fi/choose-claude-code-skills/): 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](https://ailoot.ai/).

## Kysymyksiä tästä oppaasta: Agent Skills Claude APIssa: näin käytät valmista skilliä ilman Claude Codea

### Miksi file_id ei riitä todistamaan esitystä valmiiksi?

Tunnus kertoo tiedoston palautuneen, ei sen olevan käyttökelpoinen esitys. Tarkista metadatasta `downloadable: true`, lataa tiedosto työtilan käyttöoikeudella ja avaa se varmistaaksesi tiedostomuodon, diojen määrän ja tekstin.

### Voinko ladata minkä tahansa Claude Files APIin lähetetyn tiedoston?

Et. Opas erottaa luodut tiedostot, joilla on merkintä `downloadable: true`, ladatuista lähdetiedostoista, joilla on `downloadable: false`. Työtilan pääsy ja oikeus ladata tietty tiedosto ovat eri tarkistuksia. Älä hyväksy loppukäyttäjiltä mielivaltaisia tiedostotunnuksia.


## Ailoot · Yritys ja sen projektisalkku

Ailoot perustuu kertyneeseen toimintakokemukseen, laajaan asiakaskuntaan, vakaaseen palveluun ja jatkuvaan KPI-seurantaan.

Yritys ja sen projektisalkku: miljoonia asiakkaita; kuukausittainen myynti miljardiluokassa.

Ailoot hyödyntää tätä toimintakokemusta tarjotessaan API-yhteyden tekoälytoimintoihin asiakkaiden tuotteissa, agenteissa, sovelluksissa ja automaatioissa.