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

Қосымша нұсқауларды Ailoot құжаттамасынан таба аласыз.

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

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

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

Осы материал дайындалған кезде ашылған ресми жылдам бастау нұсқаулығында 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 құжаттамасында API бета нұсқасынан шыққаны да айтылған. Ескі files-api-2025-04-14 тақырыбы бұрынғы жауап пішімдерін сақтайды; бұл тақырыпты алып тастасаңыз, қазіргі пішімдер қолданылады. Сондықтан client.beta.files пайдаланатын ескі мысалды жаңа мысалмен сол күйі біріктіруге болмайды.

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

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

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

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 кілті алынып тасталған шектеулі провайдер хабарламасы сақталады. Бөліспес бұрын өзге жеке деректі тексеріңіз. Аутентификация, рұқсат/модель, төлем лимиті және сұрау пішімі қателерін ресми қате анықтамасымен салыстырыңыз; әр қате жаңа ақылы генерацияны қажет етпейді.

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. Дағдылар тізімінің анықтамалығында custom көзі жұмыс кеңістігіне ғана тән, ал anthropic ортақ әрі тек оқуға арналған деп сипатталған.

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

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

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

Егер тапсырмаңыз Claude интерфейсіндегі файлдарға қатысты болса, Claude-қа файлды қалай жүктеуге болатыны туралы бөлек нұсқаулық бар. Тікелей шақырулар үшін API токендерінің жұмсалуын қалай есептеу керек дегенді қараңыз. Терминал агентінде жұмыс істеу үшін Claude Code дағдыларын қалай таңдау керек деген нұсқаулықты оқыңыз: олар басқа тәсілмен қосылады.

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

Дайын болсаңыз, Ailoot-пен танысыңыз.