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

> Jak připojit hotovou dovednost pptx k rozhraní Claude API: container.skills, nástroj pro spouštění kódu, kontrola odpovědi a stažení prezentace prostřednictvím Files API.

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


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Hlavní poznatek z této části">

Hlavní poznatek

Hotové Agent Skills pro dokumenty lze používat přímo přes Claude API: zadejte dovednost v `container.skills` a povolte `code_execution`. Pro první požadavek použijte kompatibilní kombinaci modelu a nástroje z oficiálního příkladu. Vygenerovaný soubor stáhněte samostatně pomocí jeho `file_id`; příklad používá pro požadavek i stažení stejný klíč API.

</div>



Další pokyny najdete v [dokumentaci Ailoot](https://ailoot.ai/docs/).

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

```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": "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](https://platform.claude.com/docs/en/api/errors); 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í](https://platform.claude.com/docs/en/api/skills/list.md) 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](https://ailoot.ai/blog/cs/claude-file-upload/). Přímá volání pokrývá [návod na výpočet využití tokenů API](https://ailoot.ai/blog/cs/api-token-usage-calculation/). Pro práci v terminálovém agentovi si přečtěte [jak vybrat dovednosti Claude Code](https://ailoot.ai/blog/cs/choose-claude-code-skills/): 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](https://ailoot.ai/).

## Časté otázky

### Proč samotné file_id nestačí k dokončení prezentace?

ID dokazuje vrácení souboru, ne jeho použitelnost jako prezentace. V metadatech ověřte `downloadable: true`, stáhněte jej s oprávněním k pracovnímu prostoru a otevřením zkontrolujte formát, počet snímků a text.

### Mohu stáhnout každý soubor nahraný do Claude Files API?

Ne. Průvodce rozlišuje vytvořené soubory označené `downloadable: true` a nahrané soubory s `downloadable: false`. Přístup k pracovnímu prostoru a oprávnění stáhnout konkrétní soubor jsou oddělené kontroly; nepřijímejte libovolná ID souborů od koncových uživatelů.


## Ailoot · Společnost a její portfolio projektů

Ailoot staví na dlouhodobých provozních zkušenostech, široké klientské základně, stabilních službách a průběžném sledování KPI.

Společnost a její portfolio projektů: miliony zákazníků; měsíční tržby v miliardách.

Ailoot využívá tyto provozní zkušenosti k poskytování přístupu přes API k funkcím AI v produktech zákazníků, agentech, aplikacích a automatizacích.