Agent Skills στο Claude API: πώς να χρησιμοποιήσετε μια έτοιμη δεξιότητα χωρίς το Claude Code

Μπορείτε να βρείτε πρόσθετες οδηγίες στην τεκμηρίωση του Ailoot.

Τι θα χρειαστείτε#

Αυτός ο οδηγός αφορά την απευθείας κλήση του API από ένα πρόγραμμα και όχι την εγκατάσταση μιας δεξιότητας στο Claude Code. Χρειάζεστε ένα κλειδί API του Claude, πρόσβαση στο επιλεγμένο μοντέλο και Python 3. Ο παρακάτω κώδικας χρησιμοποιεί την τυπική βιβλιοθήκη της Python και HTTP, επομένως δεν εξαρτάται από την έκδοση SDK που έχετε εγκαταστήσει. Το κλειδί περνά μέσω της μεταβλητής περιβάλλοντος ANTHROPIC_API_KEY· μην το βάλετε στο κείμενο του προγράμματος ή σε μια συνομιλία.

Το API προσφέρει έτοιμες δεξιότητες της Anthropic: pptx για παρουσιάσεις, xlsx για υπολογιστικά φύλλα, docx για έγγραφα Word και pdf για αρχεία PDF. Συνδέονται με χρήση του type: "anthropic". Αυτός ο οδηγός χρησιμοποιεί μια έτοιμη δεξιότητα, χωρίς να ανεβάζει κάποια προσαρμοσμένη.

Το επίσημο quickstart, όπως ήταν όταν ετοιμάστηκε αυτό το υλικό, χρησιμοποιεί τον συνδυασμό claude-opus-5-5 και code_execution_20260521. Αυτός είναι ο συνδυασμός που χρησιμοποιείται παρακάτω. Το παράδειγμα έχει ελεγχθεί ως προς την τεκμηρίωση· δεν αποτελεί αναφορά εκτέλεσης επί πληρωμή κλήσης API.

Ποιες κεφαλίδες beta χρειάζονται#

Το παράδειγμα ακολουθεί το τρέχον HTTP συμβόλαιο του quickstart: οι κεφαλίδες είναι x-api-key, anthropic-version: 2023-06-01 και content-type: application/json· δεν αποστέλλει anthropic-beta. Μη συνδυάζετε μοντέλο, μέθοδο κλήσης και μορφή απόκρισης από διαφορετικές γενιές της τεκμηρίωσης.

Η τεκμηρίωση του Files API αναφέρει επίσης ότι το API δεν βρίσκεται πλέον σε beta. Η παλιά κεφαλίδα files-api-2025-04-14 διατηρεί τις παλιές μορφές απόκρισης· η αφαίρεση της κεφαλίδας τις αλλάζει στις τρέχουσες μορφές. Γι' αυτό ένα παλιό παράδειγμα που χρησιμοποιεί client.beta.files δεν μπορεί απλώς να συνδυαστεί με ένα νέο.

Εδώ δεν μεταφέρουμε μια υπάρχουσα υπηρεσία από το παλιό συμβόλαιο beta. Αν έχετε ήδη μια τέτοια υπηρεσία, ελέγξτε πρώτα τις κεφαλίδες και τις μορφές απόκρισής της. Η λέξη 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 για παραγόμενα αρχεία και απέτυχε μόνο η λήψη, διατηρήστε την απόκριση και διαγνώστε τα μεταδεδομένα ή τη λήψη του αρχείου με την ίδια εξουσιοδοτημένη πρόσβαση στο workspace. Μην εκτελέσετε ξανά την παραγωγή μόνο για να κατεβάσετε υπάρχον αποτέλεσμα. Αν η έκβαση του αιτήματος είναι άγνωστη, κρατήστε το αναγνωριστικό του και εξακριβώστε την κατάστασή του πριν στείλετε νέα παραγωγή. Μόνο αφού τεκμηριώσετε ότι χρειάζεται νέα παραγωγή, αλλάξτε την τοπική γραμμή εξόδου σε αχρησιμοποίητη διαδρομή, π.χ. out = Path("skill-output-attempt-2"), και κρατήστε το exist_ok=False. Ο νέος φάκελος αποτρέπει την αντικατάσταση· δεν αποτρέπει διπλή χρέωση API.

Ποια δικαιώματα πρόσβασης σε αρχεία χρειάζονται#

Το Files API συσχετίζει τα αρχεία με έναν χώρο εργασίας και όχι με έναν μεμονωμένο χρήστη της εφαρμογής σας ή με μια συνομιλία. Σύμφωνα με την τεκμηρίωση, οποιοδήποτε κλειδί API έχει πρόσβαση σε αυτόν τον χώρο εργασίας μπορεί να αποκτήσει πρόσβαση στα αρχεία που έχουν ανεβεί εκεί. Το παράδειγμα χρησιμοποιεί το ίδιο κλειδί για τη λήψη και τη δημιουργία. Μην αποδέχεστε ποτέ file_id από τελικούς χρήστες ή άλλες μη έμπιστες πηγές. Αποθηκεύστε αυτά τα αναγνωριστικά στον διακομιστή και διατηρείτε στην εφαρμογή σας την αντιστοίχιση μεταξύ χρηστών και αρχείων τους.

Ελέγξτε ξεχωριστά τα μεταδεδομένα του αρχείου: πρέπει να περιέχουν downloadable: true. Η τεκμηρίωση επιτρέπει τη λήψη αρχείων που δημιουργήθηκαν από δεξιότητες ή από το εργαλείο εκτέλεσης κώδικα· τα αρχεία που ανεβάζετε έχουν downloadable: false και μια απόπειρα λήψης επιστρέφει 400. Η πρόσβαση στον χώρο εργασίας και η δυνατότητα λήψης ενός συγκεκριμένου αρχείου είναι ξεχωριστές προϋποθέσεις.

Για μια εφαρμογή πολλών χρηστών, η τεκμηρίωση του Files API συνιστά ξεχωριστό χώρο εργασίας για κάθε πελάτη ως όριο απομόνωσης αρχείων. Αυτή η σύσταση αφορά συγκεκριμένα τα αρχεία· μην την επεκτείνετε σε όλες τις οντότητες και τα δικαιώματα χωρίς να ελέγξετε το σχετικό API.

Έτοιμες δεξιότητες και προσαρμοσμένες δεξιότητες#

Οι έτοιμες δεξιότητες έχουν τα αναγνωριστικά pptx, xlsx, docx και pdf. Στην αναφορά για τη λίστα δεξιοτήτων, η πηγή custom περιγράφεται ως ιδιωτική για τον χώρο εργασίας, ενώ η anthropic είναι κοινόχρηστη και μόνο για ανάγνωση.

Το version: "latest" στο πρώτο παράδειγμα σημαίνει την πιο πρόσφατη δημοσιευμένη έκδοση της δεξιότητας. Για μια αναπαραγώγιμη ενσωμάτωση, λάβετε υπόψη ότι αυτή η επιλογή μπορεί να αλλάξει· για να μεταβείτε σε σταθερή έκδοση, πρέπει να επιλέξετε μια υπάρχουσα έκδοση της δεξιότητας που χρησιμοποιείτε και όχι ένα επινοημένο αναγνωριστικό από παράδειγμα.

Περιορισμοί και επόμενο βήμα#

Το παράδειγμα καλύπτει μόνο τη δημιουργία παρουσίασης με μια έτοιμη δεξιότητα και τη λήψη της. Η μεταφόρτωση προσαρμοσμένων δεξιοτήτων, η διαγραφή τους και η πρόσβαση σε υπηρεσίες τρίτων δεν έχουν δοκιμαστεί εδώ. Αυτές οι εργασίες απαιτούν ξεχωριστό έλεγχο του σχετικού API.

Αν η εργασία σας αφορά αρχεία στη διεπαφή του Claude, υπάρχει ξεχωριστός οδηγός για το πώς να ανεβάσετε ένα αρχείο στο Claude. Για απευθείας κλήσεις, δείτε πώς να υπολογίσετε τη χρήση διακριτικών API. Για εργασία σε τερματικό agent, διαβάστε πώς να επιλέξετε δεξιότητες Claude Code: συνδέονται με διαφορετικό τρόπο.

Για τον πρώτο έλεγχο, αρκεί μία έτοιμη δεξιότητα pptx: ελέγξτε την απόκριση, κατεβάστε ένα αρχείο που επιτρέπεται να ληφθεί και ανοίξτε το. Προσθέστε προσαρμοσμένες δεξιότητες και διαχωρισμό πρόσβασης μεταξύ πελατών μετά από αυτόν τον έλεγχο.

Όταν είστε έτοιμοι, γνωρίστε το Ailoot.