Agent Skills ב-Claude API: איך להשתמש ב-skill מוכן מראש בלי Claude Code

תוכלו למצוא הוראות נוספות בתיעוד של Ailoot.

מה צריך כדי להפעיל Agent Skills דרך Claude API?#

המדריך הזה מיועד לקריאה ישירה ל-API מתוך תוכנית, ולא להתקנת skill ב-Claude Code. תצטרכו מפתח Claude API, גישה למודל שנבחר ו-Python 3. הקוד שלהלן משתמש בספרייה הסטנדרטית של Python וב-HTTP, ולכן אינו תלוי בגרסת ה-SDK שהתקנתם. המפתח מועבר דרך משתנה הסביבה ANTHROPIC_API_KEY; אל תכניסו אותו לטקסט התוכנית או לשיחה.

ה-API מציע skills מוכנים מראש של Anthropic: ‏pptx למצגות, xlsx לגיליונות אלקטרוניים, docx למסמכי Word ו-pdf לקובצי PDF. מחברים אותם באמצעות type: "anthropic". המדריך הזה משתמש ב-skill מוכן מראש, בלי להעלות skill מותאם אישית.

ה-מדריך ההתחלה המהירה הרשמי, שנפתח בעת הכנת החומר הזה, משתמש בשילוב 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 אינה מספיקה כשלעצמה: תיעוד Files API מסביר בנפרד כיצד מתנהגות גרסאות SDK שונות.

יצירת מצגת והורדת הקובץ#

הדוגמה שולחת משימה ליצירת חמש שקופיות על אנרגיה מתחדשת, שומרת את התגובה כולה בקובץ skill-response.json ואז מחלצת את המזהים של הקבצים שנוצרו. היא אינה מקבלת נתיב שמירה מתגובת המודל: הקבצים נשמרים בתיקייה מקומית חדשה בשם 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, את מזהה הבקשה כשסופק ואת הודעת הספק באורך מוגבל, לאחר הסרת מפתח ה-API שהוגדר. בדקו אם ההודעה מכילה מידע פרטי נוסף לפני שיתוף. השוו שגיאות אימות, הרשאות או מודל, מגבלות חיוב ושגיאות במבנה הבקשה למדריך השגיאות הרשמי; לא כל כשל מחייב יצירה נוספת בתשלום.

אם skill-response.json כבר מכיל ערכי file_id של קבצים שנוצרו ורק ההורדה נכשלה, שמרו את התגובה ואבחנו את שלב מטא-נתוני הקובץ או ההורדה באמצעות אותה הרשאת גישה לסביבת העבודה. אל תריצו שוב את מקטע היצירה רק כדי להוריד פלט קיים. אם תוצאת הבקשה אינה ידועה, שמרו את מזהה הבקשה ובררו את מצבה לפני שליחת יצירה נוספת. רק לאחר שהחלטתם שנדרשת יצירה חדשה, שנו את שורת הפלט המקומי לנתיב פנוי, למשל out = Path("skill-output-attempt-2"), והשאירו exist_ok=False. תיקייה חדשה מונעת דריסה; היא אינה מונעת חיוב API כפול.

אילו הרשאות דרושות לקבצים#

Files API משייך קבצים לסביבת עבודה, ולא למשתמש מסוים ביישום שלכם או לשיחה. לפי התיעוד, כל מפתח API שיש לו גישה לאותה סביבת עבודה יכול לגשת לקבצים שהועלו אליה. הדוגמה משתמשת באותו מפתח להורדה וליצירה. לעולם אל תקבלו file_id ממשתמשי קצה או ממקורות אחרים שאינם מהימנים. אחסנו את המזהים האלה בשרת ונהלו ביישום שלכם את המיפוי בין משתמשים לקבצים שלהם.

בדקו את המטא-נתונים של הקובץ בנפרד: הם חייבים להכיל downloadable: true. התיעוד מתיר להוריד קבצים שנוצרו באמצעות skills או כלי הרצת הקוד; לקבצים שאתם מעלים יש downloadable: false, וניסיון להוריד אותם מחזיר 400. גישה לסביבת העבודה והיכולת להוריד קובץ מסוים הן דרישות נפרדות.

ליישום מרובה משתמשים, תיעוד Files API ממליץ על סביבת עבודה נפרדת לכל לקוח כגבול לבידוד הקבצים. ההמלצה הזאת מתייחסת במפורש לקבצים; אל תחילו אותה על כל הישויות וההרשאות בלי לבדוק את ה-API הרלוונטי.

Skills מוכנים מראש ו-skills מותאמים אישית#

ל-skills המוכנים מראש יש המזהים pptx, ‏xlsx, ‏docx ו-pdf. במפרט העזר של רשימת ה-skills, המקור custom מתואר כפרטי לסביבת העבודה, ואילו anthropic משותף וקריאה בלבד.

בדוגמה הראשונה, version: "latest" פירושו הגרסה האחרונה שפורסמה של ה-skill. לשילוב שניתן לשחזור, זכרו שהבחירה הזאת עשויה להשתנות; כדי לעבור לגרסה קבועה, יש לבחור גרסה קיימת של ה-skill שבו אתם משתמשים, ולא מזהה מומצא מתוך דוגמה.

מגבלות והשלב הבא#

הדוגמה עוסקת רק ביצירת מצגת באמצעות skill מוכן מראש ובהורדתה. העלאת skills מותאמים אישית, מחיקתם וגישה לשירותי צד שלישי לא נבדקו כאן. המשימות האלה מחייבות בדיקה נפרדת של ה-API הרלוונטי.

אם המשימה שלכם כוללת קבצים בממשק Claude, יש מדריך נפרד על העלאת קובץ ל-Claude. לקריאות ישירות, ראו כיצד לחשב את השימוש באסימוני API. לעבודה בסוכן טרמינל, קראו כיצד לבחור skills ל-Claude Code: הם מתחברים בדרך אחרת.

לבדיקה הראשונה, מספיק skill מוכן מראש אחד של pptx: בדקו את התגובה, הורידו קובץ שמותר להוריד ופתחו אותו. הוסיפו skills מותאמים אישית והפרדת גישה בין לקוחות אחרי הבדיקה הזאת.

כשתהיו מוכנים, הכירו את Ailoot.