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

Ďalšie pokyny nájdete v dokumentácii Ailoot.

Č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, 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 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.

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; 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í 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. Pri priamych volaniach si pozrite ako vypočítať využitie tokenov API. Pri práci v terminálovom agentovi si prečítajte ako vybrať zručnosti Claude Code: 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.