Agent Skills v Claude API: jak použít hotovou dovednost bez Claude Code

Další pokyny najdete v dokumentaci Ailoot.

Co potřebujete pro použití Agent Skills v Claude API?#

Tento návod je určený pro přímé volání API z programu, nikoli pro instalaci dovednosti v Claude Code. Potřebujete klíč Claude API, přístup k vybranému modelu a Python 3. Níže uvedený kód používá standardní knihovnu Pythonu a HTTP, takže nezávisí na verzi nainstalované sady SDK. Klíč se předává prostřednictvím proměnné prostředí ANTHROPIC_API_KEY; nevkládejte ho do textu programu ani do konverzace.

API nabízí hotové dovednosti Anthropic: pptx pro prezentace, xlsx pro tabulky, docx pro dokumenty Word a pdf pro soubory PDF. Připojují se pomocí type: "anthropic". Tento návod používá hotovou dovednost, aniž by nahrával vlastní.

Oficiální průvodce rychlým spuštěním, otevřený při přípravě tohoto materiálu, používá kombinaci claude-opus-5-5 a code_execution_20260521. Níže používáme tutéž kombinaci. Tento příklad byl ověřen podle dokumentace; nejde o zprávu o placeném volání API.

Které beta hlavičky potřebuje Agent Skills v Claude API?#

Příklad se řídí aktuální HTTP specifikací průvodce rychlým spuštěním: hlavičkami x-api-key, anthropic-version: 2023-06-01 a content-type: application/json; hlavičku anthropic-beta neposílá. Nekombinujte model, způsob volání a formát odpovědi z různých generací dokumentace.

Dokumentace Files API také uvádí, že API už není v beta verzi. Stará hlavička files-api-2025-04-14 zachovává staré formáty odpovědí; její odebrání přepne na aktuální formáty. Proto nelze starý příklad používající client.beta.files jednoduše zkombinovat s novým.

Zde nemigrujeme existující službu ze staré beta specifikace. Pokud takovou službu už máte, nejprve zkontrolujte její hlavičky a formáty odpovědí. Samotné slovo beta v názvu metody SDK nestačí: dokumentace Files API samostatně vysvětluje, jak se chovají různé verze SDK.

Vytvořte prezentaci a stáhněte soubor#

Příklad odešle úlohu na vytvoření pěti snímků o obnovitelné energii, uloží celou odpověď do skill-response.json a poté získá ID vygenerovaných souborů. Cestu pro uložení nepřebírá z odpovědi modelu: soubory se ukládají do nové místní složky skill-output. Pokud tato složka už existuje, program se zastaví, aby nepřepsal předchozí výsledek. Složka vzniká před voláním API, takže zůstane i po neúspěšném pokusu. Než něco spustíte znovu, pokus prohlédněte a zachovejte; složku nemažte jen proto, aby opakované spuštění proš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": "Vytvoř prezentaci o obnovitelné energii s 5 snímky v jazyce, kterému dávám přednost.",
    }],
    "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("Není k dispozici žádné vygenerované file_id; zkontrolujte 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("Tento soubor nelze stáhnout prostřednictvím Files API")
    target = out / f"result-{index}.pptx"
    target.write_bytes(request(file_path + "/content", binary=True))
    print("Uloženo:", target)

Názvy result-1.pptx a podobně byly zvoleny pro tento úkol s prezentací. Přípona souboru nedokazuje, co soubor obsahuje: otevřete stažený dokument a zkontrolujte jeho formát, počet snímků a text. Nepovažujte samotnou odpověď HTTP 200 ani přítomnost file_id za úspěšný výsledek.

Program vypisuje stop_reason, tedy důvod ukončení odpovědi, a ukládá celou odpověď ke kontrole. Nepokračuje v konverzaci ani placený požadavek automaticky neopakuje. Stažený soubor neznamená, že je celý úkol hotový: než rozhodnete, zda je třeba další požadavek, zkontrolujte uloženou odpověď i samotný dokument.

Při neúspěšném pokusu prohlédněte skill-error.json, pokud vznikl. Obsahuje stav HTTP, ID požadavku, je-li poskytnuto, a omezenou zprávu o chybě poskytovatele s odstraněným nastaveným klíčem API. Před sdílením zkontrolujte, zda zpráva neobsahuje jiné soukromé údaje. Chyby autentizace, oprávnění či modelu, fakturační limity a formát požadavku posuzujte podle oficiálního přehledu chyb; nevyvozujte, že každý neúspěch vyžaduje další placené generování.

Pokud skill-response.json již obsahuje vygenerované hodnoty file_id a selhalo jen stahování, odpověď zachovejte a diagnostikujte metadata či stahování souboru se stejným oprávněným přístupem k pracovnímu prostoru. Nespouštějte generování znovu jen kvůli stažení existujícího výstupu. Není-li výsledek požadavku známý, zachovejte jeho ID a před dalším generováním zjistěte stav. Teprve po rozhodnutí, že je nové generování nutné, změňte místní cestu na nepoužitou, například out = Path("skill-output-attempt-2"), a ponechte exist_ok=False. Nová složka brání přepsání, nikoli duplicitnímu účtování API.

Jaká oprávnění k souborům jsou potřeba#

Files API přiřazuje soubory k pracovnímu prostoru, nikoli k jednotlivému uživateli vaší aplikace nebo ke konverzaci. Podle dokumentace může k souborům nahraným do pracovního prostoru přistupovat jakýkoli klíč API s přístupem k tomuto prostoru. Příklad používá ke stažení stejný klíč jako ke generování. Nikdy nepřijímejte file_id od koncových uživatelů ani z jiných nedůvěryhodných zdrojů. Ukládejte tato ID na serveru a ve vlastní aplikaci udržujte mapování mezi uživateli a jejich soubory.

Metadata souboru kontrolujte samostatně: musí obsahovat downloadable: true. Dokumentace umožňuje stahovat soubory vygenerované dovednostmi nebo nástrojem pro spouštění kódu; soubory, které nahrajete, mají downloadable: false a pokus o stažení vrátí 400. Přístup k pracovnímu prostoru a možnost stáhnout konkrétní soubor jsou samostatné požadavky.

Pro aplikaci s více uživateli dokumentace Files API doporučuje samostatný pracovní prostor pro každého klienta jako hranici izolace souborů. Toto doporučení se týká konkrétně souborů; nerozšiřujte ho na všechny entity a oprávnění bez kontroly příslušného API.

Hotové dovednosti a vlastní dovednosti#

Hotové dovednosti mají ID pptx, xlsx, docx a pdf. V referenční příručce k seznamu dovedností je zdroj custom popsán jako soukromý pro pracovní prostor, zatímco anthropic je sdílený a pouze pro čtení.

version: "latest" v prvním příkladu znamená nejnovější publikovanou verzi dovednosti. U reprodukovatelné integrace mějte na paměti, že se tento výběr může změnit; přechod na pevnou verzi vyžaduje zvolit existující verzi používané dovednosti, nikoli vymyšlené ID z příkladu.

Omezení a další krok#

Příklad se zabývá pouze vytvořením prezentace pomocí hotové dovednosti a jejím stažením. Nahrávání vlastních dovedností, jejich mazání a přístup ke službám třetích stran zde nebyly testovány. Tyto úlohy vyžadují samostatnou kontrolu příslušného API.

Pokud váš úkol zahrnuje soubory v rozhraní Claude, je tu samostatný návod jak nahrát soubor do Claude. Přímá volání pokrývá návod na výpočet využití tokenů API. Pro práci v terminálovém agentovi si přečtěte jak vybrat dovednosti Claude Code: připojují se jiným způsobem.

Pro první kontrolu stačí jedna hotová dovednost pptx: prohlédněte odpověď, stáhněte soubor, který lze stáhnout, a otevřete ho. Vlastní dovednosti a oddělení přístupu mezi klienty přidejte až po této kontrole.

Až budete připraveni, seznamte se s Ailoot.