# Claude API-дегі Agent Skills: Claude Code қолданбай дайын дағдыны пайдалану жолы

> Дайын pptx дағдысын Claude API-ге қалай қосуға болады: container.skills, кодты орындау құралы, жауапты тексеру және Files API арқылы презентацияны жүктеп алу.

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


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Осы бөлімнің негізгі түйіні">

Негізгі түйін

Құжаттарға арналған дайын Agent Skills дағдыларын тікелей Claude API арқылы пайдалануға болады: `container.skills` ішінде дағдыны көрсетіп, `code_execution` құралын қосыңыз. Алғашқы сұрауыңызда ресми мысалдағы үйлесімді модель мен құрал жұбын пайдаланыңыз. Жасалған файлды оның `file_id` мәнін пайдаланып бөлек жүктеп алыңыз; мысалда сұрау мен жүктеп алу үшін бірдей API кілті қолданылады.

</div>



Қосымша нұсқауларды [Ailoot құжаттамасынан](https://ailoot.ai/docs/) таба аласыз.

## Сізге не қажет болады

Бұл нұсқаулық дағдыны Claude Code-қа орнатуға емес, API-ді тікелей бағдарламадан шақыруға арналған. Сізге Claude API кілті, таңдалған модельге қолжетімділік және Python 3 қажет. Төмендегі код Python стандартты кітапханасы мен HTTP-ті пайдаланады, сондықтан орнатылған SDK нұсқасына тәуелді емес. Кілт `ANTHROPIC_API_KEY` орта айнымалысы арқылы беріледі; оны бағдарлама мәтініне немесе әңгімеге енгізбеңіз.

API дайын Anthropic дағдыларын ұсынады: презентациялар үшін `pptx`, электрондық кестелер үшін `xlsx`, Word құжаттары үшін `docx` және PDF файлдары үшін `pdf`. Олар `type: "anthropic"` арқылы қосылады. Бұл нұсқаулықта дайын дағды пайдаланылады, арнайы дағды жүктелмейді.

Осы материал дайындалған кезде ашылған [ресми жылдам бастау нұсқаулығында](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart.md) `claude-opus-5-5` және `code_execution_20260521` жұбы қолданылған. Төменде де осы жұп пайдаланылады. Бұл мысал құжаттамамен салыстырып тексерілген; ол ақылы API шақыруы жасалғанын білдірмейді.

## Қандай beta тақырыптары қажет

Мысал жылдам бастау нұсқаулығындағы қолданыстағы HTTP келісімшартын ұстанады: тақырыптар — `x-api-key`, `anthropic-version: 2023-06-01` және `content-type: application/json`; `anthropic-beta` жіберілмейді. Әртүрлі буын құжаттамасындағы модельді, шақыру тәсілін және жауап пішімін араластырмаңыз.

[Files API құжаттамасында](https://platform.claude.com/docs/en/build-with-claude/files.md) API бета нұсқасынан шыққаны да айтылған. Ескі `files-api-2025-04-14` тақырыбы бұрынғы жауап пішімдерін сақтайды; бұл тақырыпты алып тастасаңыз, қазіргі пішімдер қолданылады. Сондықтан `client.beta.files` пайдаланатын ескі мысалды жаңа мысалмен сол күйі біріктіруге болмайды.

Бұл жерде қолданыстағы сервисті ескі beta келісімшартынан көшіріп жатқан жоқпыз. Егер сізде сондай сервис болса, алдымен оның тақырыптары мен жауап пішімдерін тексеріңіз. SDK әдісінің атауында `beta` сөзі болуы өздігінен жеткіліксіз: Files API құжаттамасында SDK-ның әртүрлі нұсқалары қалай жұмыс істейтіні бөлек түсіндіріледі.





## Презентация жасап, файлды жүктеп алу

Мысал жаңартылатын энергия туралы бес слайд жасау тапсырмасын жібереді, бүкіл жауапты `skill-response.json` файлына сақтайды да, жасалған файлдардың ID мәндерін бөліп алады. Ол модель жауабындағы сақтау жолын пайдаланбайды: файлдар `skill-output` атты жаңа жергілікті қалтаға сақталады. Егер бұл қалта бұрыннан бар болса, алдыңғы нәтижені үстінен жазбау үшін бағдарлама тоқтайды. Қалта API сұрауынан бұрын жасалады, сондықтан сәтсіз шақырудан кейін де қалады. Қайта әрекет етпес бұрын сол талпынысты қарап, сақтаңыз; қайталау іске қосылуы үшін ғана қалтаны жоймаңыз.

```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": "Жаңартылатын энергия туралы таңдаулы тілімде 5 слайдтан тұратын презентация жасаңыз.",
    }],
    "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)
```

`result-1.pptx` сияқты атаулар осы презентация тапсырмасы үшін таңдалған. Файл кеңейтімі оның ішінде не барын дәлелдемейді: жүктеп алынған құжатты ашып, пішімін, слайдтар санын және мәтінін тексеріңіз. HTTP 200 жауабын немесе `file_id` барын ғана сәтті нәтиже деп қабылдамаңыз.

Бағдарлама жауаптың тоқтау себебі — `stop_reason` мәнін басып шығарады және жауапты толық тексеру үшін сақтайды. Ол әңгімені жалғастырмайды және ақылы сұрауды автоматты түрде қайталамайды. Жүктеп алынған файл бүкіл тапсырма орындалды дегенді білдірмейді: тағы сұрау қажет пе, соны шешпес бұрын сақталған жауап пен құжаттың өзін тексеріңіз.

Сәтсіз әрекеттен кейін бар болса `skill-error.json` файлын қараңыз. Онда HTTP мәртебесі, берілген сұрау ID мәні және бапталған API кілті алынып тасталған шектеулі провайдер хабарламасы сақталады. Бөліспес бұрын өзге жеке деректі тексеріңіз. Аутентификация, рұқсат/модель, төлем лимиті және сұрау пішімі қателерін [ресми қате анықтамасымен](https://platform.claude.com/docs/en/api/errors) салыстырыңыз; әр қате жаңа ақылы генерацияны қажет етпейді.

`skill-response.json` ішінде жасалған `file_id` бар болып, тек жүктеу үзілсе, жауапты сақтап, сол рұқсат етілген workspace қолжетімділігімен метадерек пен жүктеу қадамын тексеріңіз. Бар нәтижені жүктеу үшін генерацияны қайта жібермеңіз. Сұрау нәтижесі белгісіз болса, ID мәнін сақтап, жаңа генерацияға дейін мәртебесін анықтаңыз. Жаңа генерация қажет деп шешкеннен кейін ғана бос жол беріңіз, мысалы `out = Path("skill-output-attempt-2")`, әрі `exist_ok=False` қалсын. Жаңа қалта жергілікті файлдың үстіне жазуды тоқтатады, бірақ қайталанған төлемді өздігінен болдырмайды. `FileExistsError` — жергілікті қалта қақтығысы, API жауабы емес.

## Қандай файл рұқсаттары қажет

Files API файлдарды қолданбаңыздың жеке пайдаланушысымен немесе әңгімемен емес, жұмыс кеңістігімен байланыстырады. Құжаттамаға сәйкес, сол жұмыс кеңістігіне қолжетімді кез келген API кілті оған жүктелген файлдарға қол жеткізе алады. Мысалда жүктеп алу үшін де генерациядағы кілт қолданылады. `file_id` мәнін соңғы пайдаланушылардан немесе басқа сенімсіз көздерден ешқашан қабылдамаңыз. Бұл ID мәндерін серверде сақтап, өз қолданбаңызда пайдаланушылар мен олардың файлдары арасындағы сәйкестікті жүргізіңіз.

Файл метадеректерін бөлек тексеріңіз: онда `downloadable: true` болуы керек. Құжаттама дағдылар немесе кодты орындау құралы жасаған файлдарды жүктеп алуға рұқсат етеді; өзіңіз жүктеген файлдарда `downloadable: false` болады және жүктеп алуға әрекеттенгенде 400 қатесі қайтарылады. Жұмыс кеңістігіне қолжетімділік пен нақты файлды жүктеп алу мүмкіндігі — бөлек талаптар.

Бірнеше пайдаланушысы бар қолданба үшін Files API құжаттамасы файлдарды оқшаулау шекарасы ретінде әр клиентке бөлек жұмыс кеңістігін ұсынады. Бұл ұсыныс нақты файлдарға қатысты; тиісті API-ді тексермей тұрып оны барлық нысандар мен рұқсаттарға таратпаңыз.

## Дайын дағдылар және арнайы дағдылар

Дайын дағдылардың ID мәндері — `pptx`, `xlsx`, `docx` және `pdf`. [Дағдылар тізімінің анықтамалығында](https://platform.claude.com/docs/en/api/skills/list.md) `custom` көзі жұмыс кеңістігіне ғана тән, ал `anthropic` ортақ әрі тек оқуға арналған деп сипатталған.

Бірінші мысалдағы `version: "latest"` дағдының соңғы жарияланған нұсқасын білдіреді. Қайта өндіруге болатын интеграция үшін бұл таңдау өзгеруі мүмкін екенін ескеріңіз; бекітілген нұсқаға ауысу үшін мысалдағы ID-ді ойдан шығармаңыз, пайдаланатын дағдыңыздың бұрыннан бар нұсқасын таңдаңыз.

## Шектеулер және келесі қадам

Мысал тек дайын дағды арқылы презентация жасап, оны жүктеп алуды қамтиды. Арнайы дағдыларды жүктеу, оларды жою және үшінші тарап қызметтеріне қол жеткізу мұнда тексерілмеген. Бұл тапсырмалар тиісті API-ді бөлек тексеруді қажет етеді.

Егер тапсырмаңыз Claude интерфейсіндегі файлдарға қатысты болса, [Claude-қа файлды қалай жүктеуге болатыны](https://ailoot.ai/blog/kk/claude-file-upload/) туралы бөлек нұсқаулық бар. Тікелей шақырулар үшін [API токендерінің жұмсалуын қалай есептеу керек](https://ailoot.ai/blog/kk/api-token-usage-calculation/) дегенді қараңыз. Терминал агентінде жұмыс істеу үшін [Claude Code дағдыларын қалай таңдау керек](https://ailoot.ai/blog/kk/choose-claude-code-skills/) деген нұсқаулықты оқыңыз: олар басқа тәсілмен қосылады.

Алғашқы тексеру үшін бір дайын `pptx` дағдысы жеткілікті: жауапты тексеріп, жүктеуге рұқсат етілген файлды жүктеп алыңыз да, ашыңыз. Арнайы дағдылар мен клиенттер арасындағы қолжетімділікті бөлуді сол тексеруден кейін қосыңыз.





Дайын болсаңыз, [Ailoot-пен танысыңыз](https://ailoot.ai/).

## Жиі қойылатын сұрақтар

### file_id болуы презентацияның дайын екенін неге дәлелдемейді?

ID файл қайтарылғанын көрсетеді, бірақ оның жарамды презентация екенін дәлелдемейді. Метадеректен `downloadable: true` мәнін тексеріп, workspace рұқсатымен жүктеңіз. Файлды ашып, пішімін, слайд санын және мәтінін тексеріңіз.

### Claude Files API-іне жүктелген кез келген файлды кері жүктей аламын ба?

Жоқ. Нұсқаулық `downloadable: true` деп белгіленген жасалған файлдарды `downloadable: false` деп белгіленген жүктелген файлдардан ажыратады. Workspace-ке кіру мен нақты файлды жүктеу құқығы бөлек тексеріледі; соңғы пайдаланушыдан еркін файл ID қабылдамаңыз.


## Ailoot · Компания және оның жобалар портфелі

Ailoot жинақталған жұмыс тәжірибесіне, кең клиенттік базаға, тұрақты қызметке және KPI көрсеткіштерін үздіксіз бақылауға сүйенеді.

Компания және оның жобалар портфелі: миллиондаған клиент; ай сайынғы сату көлемі миллиардтармен есептеледі.

Ailoot осы тәжірибені клиенттердің өнімдерінде, агенттерінде, қолданбаларында және автоматтандыруларында жасанды интеллект мүмкіндіктеріне API арқылы қол жеткізуді қамтамасыз етуге пайдаланады.