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

> Kako povezati že pripravljeno spretnost pptx z API-jem Claude: container.skills, orodje za izvajanje kode, preverjanje odgovora in prenos predstavitve prek API-ja Files.

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


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ključna ugotovitev za ta razdelek">

Ključna ugotovitev

Že pripravljene Agent Skills za dokumente lahko uporabljate prek neposrednega API-ja Claude: določite spretnost v `container.skills` in omogočite `code_execution`. Za prvo zahtevo uporabite združljivo kombinacijo modela in orodja iz uradnega primera. Ustvarjeno datoteko prenesite ločeno z njenim `file_id`; primer za zahtevo in prenos uporablja isti ključ API.

</div>



Dodatna navodila najdete v [dokumentaciji Ailoot](https://ailoot.ai/docs/).

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

```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": "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](https://platform.claude.com/docs/en/api/errors); 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](https://platform.claude.com/docs/en/api/skills/list.md) 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](https://ailoot.ai/blog/sl/claude-file-upload/). Za neposredne klice preberite, [kako izračunati porabo žetonov API-ja](https://ailoot.ai/blog/sl/api-token-usage-calculation/). Za delo v terminalskem agentu preberite, [kako izbrati spretnosti Claude Code](https://ailoot.ai/blog/sl/choose-claude-code-skills/): 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](https://ailoot.ai/).

## Vprašanja in odgovori: Agent Skills v API-ju Claude: kako uporabiti že pripravljeno spretnost brez Claude Code

### Zakaj file_id ne zadošča za razglasitev končane predstavitve?

ID kaže, da je bila datoteka vrnjena, ne da je uporabna predstavitev. V metapodatkih preverite `downloadable: true`, jo prenesite z dostopom do delovnega prostora in odprite ter preverite obliko datoteke, število diapozitivov in besedilo.

### Ali lahko prenesem vsako datoteko, naloženo v Claude Files API?

Ne. Vodnik loči ustvarjene datoteke z oznako `downloadable: true` od naloženih datotek z oznako `downloadable: false`. Dostop do delovnega prostora in dovoljenje za prenos določene datoteke sta ločeni preverjanji; od končnih uporabnikov ne sprejemajte poljubnih ID-jev datotek.


## Ailoot · Podjetje in njegov portfelj projektov

Ailoot temelji na pridobljenih operativnih izkušnjah, široki bazi strank, stabilni storitvi in stalnem spremljanju KPI.

Podjetje in njegov portfelj projektov: milijoni strank; mesečna prodaja v milijardah.

Ailoot te operativne izkušnje uporablja za dostop prek API do funkcij umetne inteligence v izdelkih strank, agentih, aplikacijah in avtomatizacijah.