# Agent Skills v Claude API: ako používať hotovú zručnosť bez Claude Code

> Ako pripojiť hotovú zručnosť pptx k Claude API: container.skills, nástroj na vykonávanie kódu, kontrola odpovede a stiahnutie prezentácie prostredníctvom Files API.

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


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Kľúčové posolstvo tejto časti">

Kľúčové posolstvo

Hotové Agent Skills pre dokumenty možno používať prostredníctvom priameho Claude API: zadajte zručnosť v `container.skills` a povoľte `code_execution`. Pri prvej požiadavke použite kompatibilnú kombináciu modelu a nástroja z oficiálneho príkladu. Vygenerovaný súbor stiahnite samostatne pomocou jeho `file_id`; príklad používa rovnaký kľúč API na požiadavku aj stiahnutie.

</div>



Ďalšie pokyny nájdete v [dokumentácii Ailoot](https://ailoot.ai/docs/).

## Čo budete potrebovať

Tento návod je určený na priame volanie API z programu, nie na inštaláciu zručnosti v Claude Code. Potrebujete kľúč Claude API, prístup k vybranému modelu a Python 3. Nižšie uvedený kód používa štandardnú knižnicu Pythonu a HTTP, takže nezávisí od verzie SDK, ktorú máte nainštalovanú. Kľúč sa odovzdáva prostredníctvom premennej prostredia `ANTHROPIC_API_KEY`; nevkladajte ho do textu programu ani do konverzácie.

API ponúka hotové zručnosti Anthropic: `pptx` pre prezentácie, `xlsx` pre tabuľkové zošity, `docx` pre dokumenty Word a `pdf` pre súbory PDF. Pripájajú sa pomocou `type: "anthropic"`. Tento návod používa hotovú zručnosť bez nahrávania vlastnej.

[Oficiálny quickstart](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart.md), otvorený v čase prípravy tohto materiálu, používa kombináciu `claude-opus-5-5` a `code_execution_20260521`. Nižšie je použitá táto kombinácia. Tento príklad bol skontrolovaný podľa dokumentácie; nejde o správu o uskutočnení platenej požiadavky na API.

## Ktoré hlavičky beta sú potrebné

Príklad sa riadi aktuálnou HTTP zmluvou quickstartu: hlavičky sú `x-api-key`, `anthropic-version: 2023-06-01` a `content-type: application/json`; hlavičku `anthropic-beta` neposiela. Nekombinujte model, spôsob volania a formát odpovede z rôznych generácií dokumentácie.

Dokumentácia [Files API](https://platform.claude.com/docs/en/build-with-claude/files.md) tiež uvádza, že API už nie je v beta verzii. Stará hlavička `files-api-2025-04-14` zachováva staré formáty odpovedí; jej odstránením sa prejde na aktuálne formáty. Preto nemožno starý príklad používajúci `client.beta.files` jednoducho skombinovať s novým.

Tu nemigrujeme existujúcu službu zo starej zmluvy beta. Ak už takú službu máte, najskôr skontrolujte jej hlavičky a formáty odpovedí. Samotné slovo `beta` v názve metódy SDK nestačí: dokumentácia Files API samostatne vysvetľuje správanie rôznych verzií SDK.





## Vytvorenie prezentácie a stiahnutie súboru

Príklad odošle úlohu na vytvorenie piatich snímok o obnoviteľnej energii, uloží celú odpoveď do `skill-response.json` a potom z nej získa identifikátory vygenerovaných súborov. Cestu na uloženie nepreberá z odpovede modelu: súbory sa ukladajú do nového miestneho priečinka s názvom `skill-output`. Ak tento priečinok už existuje, program sa zastaví, aby neprepísal predchádzajúci výsledok. Priečinok vzniká pred volaním API, preto zostane aj po neúspešnom pokuse. Skôr než niečo zopakujete, pokus skontrolujte a zachovajte; priečinok nemažte len preto, aby opakované spustenie prešlo kontrolou.

```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": "Vytvorte prezentáciu o obnoviteľnej energii s 5 snímkami v mojom preferovanom jazyku.",
    }],
    "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)
```

Názvy `result-1.pptx` a podobne boli zvolené pre túto prezentačnú úlohu. Prípona súboru nedokazuje, čo súbor obsahuje: stiahnutý dokument otvorte a skontrolujte jeho formát, počet snímok a text. Za úspešný výsledok nepovažujte samotný HTTP 200 ani prítomnosť `file_id`.

Program vypíše `stop_reason`, teda dôvod, pre ktorý sa odpoveď zastavila, a uloží celú odpoveď na kontrolu. Nepokračuje v konverzácii ani automaticky neopakuje platenú požiadavku. Stiahnutý súbor ešte neznamená, že je celá úloha dokončená: pred rozhodnutím, či je potrebná ďalšia požiadavka, skontrolujte uloženú odpoveď aj samotný dokument.

Pri neúspešnom pokuse skontrolujte `skill-error.json`, ak vznikol. Zaznamenáva stav HTTP, ID požiadavky, ak ho poskytovateľ uviedol, a obmedzenú chybovú správu poskytovateľa s odstráneným nastaveným kľúčom API. Pred zdieľaním overte, či správa neobsahuje iné súkromné údaje. Chyby overenia totožnosti, oprávnení či modelu, fakturačných limitov a formátu požiadavky porovnajte s [oficiálnym prehľadom chýb](https://platform.claude.com/docs/en/api/errors); nepredpokladajte, že každé zlyhanie potrebuje ďalšie platené generovanie.

Ak `skill-response.json` už obsahuje vygenerované hodnoty `file_id` a zlyhalo iba sťahovanie, odpoveď zachovajte a diagnostikujte metadáta či stiahnutie súboru s rovnakým oprávneným prístupom k pracovnému priestoru. Nespúšťajte generovanie znovu len preto, aby ste stiahli existujúci výstup. Ak výsledok požiadavky nie je známy, zachovajte jej ID a zistite stav pred ďalším generovaním. Až po rozhodnutí, že je nové generovanie potrebné, zmeňte miestnu cestu na nepoužitú, napríklad `out = Path("skill-output-attempt-2")`, a zachovajte `exist_ok=False`. Nový priečinok bráni prepísaniu, nie duplicitnému účtovaniu API.

## Aké oprávnenia na prístup k súborom sú potrebné

Files API priraďuje súbory k pracovnému priestoru, nie k jednotlivému používateľovi vašej aplikácie ani ku konverzácii. Podľa dokumentácie môže k súborom nahraným do daného pracovného priestoru pristupovať každý kľúč API, ktorý má k tomuto priestoru prístup. Príklad používa na stiahnutie rovnaký kľúč ako na generovanie. Nikdy neprijímajte `file_id` od koncových používateľov ani z iných nedôveryhodných zdrojov. Tieto identifikátory ukladajte na serveri a vo vlastnej aplikácii udržiavajte mapovanie medzi používateľmi a ich súbormi.

Metadáta súboru kontrolujte samostatne: musia obsahovať `downloadable: true`. Dokumentácia povoľuje sťahovanie súborov vygenerovaných zručnosťami alebo nástrojom na vykonávanie kódu; súbory, ktoré nahráte vy, majú `downloadable: false` a pokus o stiahnutie vráti 400. Prístup k pracovnému priestoru a možnosť stiahnuť konkrétny súbor sú samostatné požiadavky.

Pri aplikácii pre viacerých používateľov odporúča dokumentácia Files API samostatný pracovný priestor pre každého klienta ako hranicu izolácie súborov. Toto odporúčanie sa týka konkrétne súborov; bez kontroly príslušného API ho nerozširujte na všetky entity a oprávnenia.

## Hotové a vlastné zručnosti

Hotové zručnosti majú identifikátory `pptx`, `xlsx`, `docx` a `pdf`. V [referenčnej príručke zoznamu zručností](https://platform.claude.com/docs/en/api/skills/list.md) je zdroj `custom` opísaný ako súkromný pre pracovný priestor, zatiaľ čo `anthropic` je zdieľaný a určený iba na čítanie.

`version: "latest"` v prvom príklade znamená najnovšiu publikovanú verziu zručnosti. Pri reprodukovateľnej integrácii majte na pamäti, že tento výber sa môže zmeniť; na prechod na pevnú verziu musíte vybrať existujúcu verziu používanej zručnosti, nie vymyslený identifikátor z príkladu.

## Obmedzenia a ďalší krok

Príklad sa týka iba vytvorenia prezentácie pomocou hotovej zručnosti a jej stiahnutia. Nahrávanie vlastných zručností, ich odstraňovanie a prístup k službám tretích strán sa tu netestovali. Tieto úlohy si vyžadujú samostatnú kontrolu príslušného API.

Ak vaša úloha zahŕňa súbory v rozhraní Claude, k dispozícii je samostatný návod [ako nahrať súbor do Claude](https://ailoot.ai/blog/sk/claude-file-upload/). Pri priamych volaniach si pozrite [ako vypočítať využitie tokenov API](https://ailoot.ai/blog/sk/api-token-usage-calculation/). Pri práci v terminálovom agentovi si prečítajte [ako vybrať zručnosti Claude Code](https://ailoot.ai/blog/sk/choose-claude-code-skills/): pripájajú sa iným spôsobom.

Na prvú kontrolu stačí jedna hotová zručnosť `pptx`: skontrolujte odpoveď, stiahnite súbor, ktorý je povolené stiahnuť, a otvorte ho. Vlastné zručnosti a oddelenie prístupu medzi klientmi pridajte až po tejto kontrole.





Keď budete pripravení, spoznajte [Ailoot](https://ailoot.ai/).

## Otázky a odpovede: Agent Skills v Claude API: ako používať hotovú zručnosť bez Claude Code

### Prečo samotné file_id nestačí na dokončenie prezentácie?

ID dokazuje vrátenie súboru, nie použiteľnú prezentáciu. V metadátach overte downloadable: true, súbor stiahnite s prístupom do pracovného priestoru a otvorte ho na kontrolu formátu, počtu snímok a textu.

### Môžem stiahnuť ľubovoľný súbor nahratý do Claude Files API?

Nie. Sprievodca odlišuje vygenerované súbory s downloadable: true od nahratých súborov s downloadable: false. Prístup do pracovného priestoru a právo stiahnuť konkrétny súbor sú samostatné kontroly; od koncových používateľov neprijímajte ľubovoľné ID súborov.


## Ailoot · Spoločnosť a jej portfólio projektov

Ailoot stavia na dlhodobých prevádzkových skúsenostiach, širokej klientskej základni, stabilných službách a priebežnom sledovaní KPI.

Spoločnosť a jej portfólio projektov: milióny zákazníkov; mesačné tržby v miliardách.

Ailoot využíva tieto prevádzkové skúsenosti na poskytovanie prístupu cez API k funkciám AI v produktoch zákazníkov, agentoch, aplikáciách a automatizáciách.