ΣύνδεσηΚλείστε μια ενημέρωση

Κεφάλαιο 2.20

Δεξιότητες (Skills)

Πώς να γράψετε, να δοκιμάσετε και να δημοσιεύσετε μια δεξιότητα του Skills Engine, πού εμφανίζεται μόλις τεθεί σε λειτουργία και πώς διαφέρουν οι δεξιότητες manifest σε ένα πρόσθετο (plugin). Περιλαμβάνει ένα ολοκληρωμένο παράδειγμα σύνοψης κατανομής θέσεων ελλιμενισμού για τη Harrow Port Authority.

Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

17 λεπτά ανάγνωσης

Ο Tomás Reilly, ο μηχανικός πλατφόρμας στη Harrow Port Authority, με ρώτησε τον περασμένο μήνα γιατί οι υπεύθυνοι προγραμματισμού θέσεων ελλιμενισμού έπαιρναν διαφορετική απάντηση κάθε φορά που ρωτούσαν τον βοηθό «ποιος είναι σε ποια θέση αύριο και τι άλλαξε;». Η απάντηση ήταν ότι κανείς δεν είχε πει στον βοηθό πώς μοιάζει μια καλή απάντηση. Μια δεξιότητα του Skills Engine το έλυσε σε ένα απόγευμα: οι υπεύθυνοι προγραμματισμού λαμβάνουν πλέον την ίδια σύνοψη τριών μερών κάθε φορά, με τον πίνακα θέσεων ελλιμενισμού πρώτο, τις αλλαγές από το τελευταίο πλάνο από κάτω και τις συγκρούσεις τελευταίες. Αυτό το κεφάλαιο παρουσιάζει αναλυτικά αυτήν τη δεξιότητα από την αρχή μέχρι το τέλος και στη συνέχεια καλύπτει το άλλο είδος δεξιότητας, αυτό που βρίσκεται στο manifest ενός plugin.

Δύο είδη δεξιοτήτων

Το Nexus χρησιμοποιεί τη λέξη «δεξιότητα» (skill) για δύο διαφορετικά πράγματα, τα οποία κατασκευάζονται με διαφορετικό τρόπο.

Δεξιότητα του Skills Engine Δεξιότητα manifest
Τι είναι Ένα πακέτο SKILL.md στη βιβλιοθήκη δεξιοτήτων Μια αυστηρά τυποποιημένη εγγραφή στον πίνακα skills[] ενός plugin
Ποιος τη γράφει Οποιοσδήποτε έχει το δικαίωμα, στο εργαλείο δημιουργίας ή στον δικό του επεξεργαστή κειμένου Ένας προγραμματιστής, μέσα σε ένα plugin
Τι περιέχει Οδηγίες, τα εργαλεία που μπορεί να καλέσει, προαιρετικά αρχεία και σενάρια (scripts) Ένα σχήμα εισόδου και εξόδου, ένα επίπεδο (tier) και τα πεδία που χρειάζεται αυτό το επίπεδο
Πώς φτάνει στην πλατφόρμα Επικυρώνεται, μεταφορτώνεται και δημοσιεύεται στο Skills Engine Μεταγλωττίζεται από το manifest και συγχρονίζεται στο μητρώο δεξιοτήτων
Τι την εκτελεί Ο βοηθός, πράκτορες (agents), ροές εργασίας, κουμπιά AI (τεχνητής νοημοσύνης), το Claude Code Αποστολή (dispatch) από το UNO (τη μηχανή ροής εργασιών)
Τυπική χρήση «Συνόψισε το πλάνο θέσεων ελλιμενισμού με τον ίδιο τρόπο κάθε φορά» «Εκτέλεσε τον υπολογιστή διάδοσης τροχιάς μας σε αυτό το πέρασμα»

Το υπόλοιπο του κεφαλαίου τα εξετάζει ξεχωριστά. Αν μια παράγραφος αναφέρει τη λέξη «δεξιότητα» από μόνη της, πρόκειται για δεξιότητα του Skills Engine.

Μέρος 1: δεξιότητες του Skills Engine

Τι είναι μια δεξιότητα

Μια δεξιότητα είναι ένας φάκελος. Το αρχείο SKILL.md της αναφέρει τον σκοπό της δεξιότητας και τον τρόπο εκτέλεσης της εργασίας· δίπλα του βρίσκονται τυχόν αρχεία που χρειάζεται η εργασία και τυχόν σενάρια που εκτελεί. Η μηχανή φορτώνει μια δεξιότητα σε τρία επίπεδα: το όνομα και την περιγραφή πάντα, τις οδηγίες όταν μια εργασία απαιτεί τη δεξιότητα, και τα αρχεία μόνο όταν τα χρειάζεται κάποιο βήμα. Γι' αυτό μια εγκατάσταση μπορεί να διαθέτει διακόσιες δεξιότητες και να μην επιβαρύνεται σχεδόν καθόλου γι' αυτές μέχρι να χρησιμοποιηθεί κάποια.

skills/<slug>/
├── SKILL.md      # required: YAML frontmatter, then the instructions
├── skill.yaml    # optional: engine metadata (triggers, aliases, tags, capabilities)
└── scripts/      # optional: bundled with the skill as components

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

Frontmatter του SKILL.md

Το frontmatter είναι κώδικας YAML ανάμεσα σε δύο γραμμές --- στην αρχή του αρχείου. Η μορφή απαιτεί τρία πεδία. Η ίδια η επικύρωση μπλοκάρει τη διαδικασία μόνο για λίγα πράγματα: την απουσία ονόματος ή περιγραφής, και ένα slug ή έναν τύπο εργασίας που χρησιμοποιείται ήδη. Οτιδήποτε άλλο το αναφέρει ως προειδοποίηση.

Πεδίο Τύπος Υποχρεωτικό Τι περιέχει
name συμβολοσειρά ναι Το μοναδικό αναγνωριστικό, σε μορφή kebab-case
description συμβολοσειρά ναι Τι κάνει η δεξιότητα, έως 500 χαρακτήρες το πολύ. Η βιβλιοθήκη και ο μηχανισμός αντιστοίχισης το διαβάζουν, επομένως γράψτε το για έναν αναγνώστη που προσπαθεί να αποφασίσει αν αυτή είναι η κατάλληλη δεξιότητα
allowed-tools συμβολοσειρά ή λίστα ναι Τα εργαλεία που μπορεί να καλέσει η δεξιότητα. Μπορεί μόνο να περιορίσει τη λίστα επιτρεπόμενων (allow-list) εκείνου που την εκτελεί
triggers λίστα όχι Εντολές κάθετου (slash commands) που καλούν απευθείας τη δεξιότητα
capabilities λίστα όχι Δομημένες δυνατότητες, καθεμία με ένα name, ένα description και προαιρετικά input_schema, output_schema και examples
version συμβολοσειρά όχι Μια σημασιολογική έκδοση (semantic version)· 1.0.0 όταν παραλείπεται
visibility συμβολοσειρά όχι private, team ή public
status συμβολοσειρά όχι draft, testing ή published

Διατηρήστε τις οδηγίες κάτω από περίπου 5.000 tokens. Να είστε συγκεκριμένοι και να δίνετε παραδείγματα. Κάθε δεξιότητα πρέπει να κάνει μία εργασία καλά· αν πιάσετε τον εαυτό σας να γράφει «και επίσης», πιθανότατα έχετε δύο δεξιότητες.

skill.yaml

Το skill.yaml περιέχει όσα χρειάζεται η μηχανή για την ανακάλυψη και τη βιβλιοθήκη, ώστε το SKILL.md να παραμένει ευανάγνωστο. Τα πεδία που διαβάζει η μηχανή περιλαμβάνουν τα name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools και capabilities. Μια δυνατότητα μπορεί να φέρει query_patterns, τις διατυπώσεις που πρέπει να της στέλνει ο μηχανισμός αντιστοίχισης. Υπάρχουν επίσης υποδείξεις για τον προϋπολογισμό πόρων της ίδιας της μηχανής: complexity, estimated_tokens και required_services.

scripts/

Οτιδήποτε κάτω από το scripts/ ενσωματώνεται αυτούσιο στη δεξιότητα ως στοιχείο (component). Ένα σενάριο εκτελείται, δεν διαβάζεται ποτέ στο περιβάλλον (context) του μοντέλου, και εκτελείται σε απομονωμένο περιβάλλον (sandbox). Χρησιμοποιήστε το όταν ένα βήμα αφορά αριθμητικούς υπολογισμούς ή ανάλυση (parsing) που ένα μοντέλο δεν θα έπρεπε να κάνει «με το μυαλό του».

Ορατότητα και κατάσταση

Η ορατότητα καθορίζει ποιος μπορεί να βρει τη δεξιότητα: το private είστε εσείς, το team είναι η ομάδα σας και το public είναι όλοι στον οργανισμό που εξυπηρετεί η βιβλιοθήκη. Στην κονσόλα η ίδια επιλογή εμφανίζεται ως «Only me», μια ομάδα όπως «Customs desk» ή ολόκληρος ο οργανισμός, ενώ μια δεξιότητα μπορεί επίσης να κοινοποιηθεί σε ένα πακέτο τομέα (domain pack) μέσω της διαδικασίας αξιολόγησης του ίδιου του πακέτου.

Η κατάσταση δείχνει σε ποιο στάδιο του κύκλου ζωής της βρίσκεται η δεξιότητα.

Κατάσταση Σημασία
draft Εργασία σε εξέλιξη· μη ανιχνεύσιμη
testing Υπό επικύρωση, με περιορισμένη πρόσβαση
published Διαθέσιμη για γενική χρήση
deprecated Έχει αντικατασταθεί· οδεύει προς απόσυρση

Μόλις δημοσιευτεί μια έκδοση, δεν αλλάζει ποτέ. Στην κονσόλα, τα «live», «canary» και «shadow» είναι ετικέτες πάνω σε εκδόσεις, και η επιστροφή σε προηγούμενη έκδοση μετακινεί μια ετικέτα. Οι εκτελέσεις που βρίσκονται σε εξέλιξη ολοκληρώνονται στην έκδοση με την οποία ξεκίνησαν.

Νέα δεξιότητα · 2 Οδηγίες και εργαλεία
Νέα δεξιότητα · 2 Οδηγίες και εργαλεία
Το δεύτερο βήμα του εργαλείου δημιουργίας δείχνει το προσχέδιο του SKILL.md, τα αρχεία δίπλα του και πότε φορτώνεται το καθένα, καθώς και τα εργαλεία που μπορεί να καλέσει η δεξιότητα. Σε μια δεξιότητα ελέγχου δεν προσφέρεται κανένα εργαλείο εγγραφής, και μια δεξιότητα μπορεί μόνο να περιορίσει τη λίστα επιτρεπόμενων εκείνου που την εκτελεί.

Από έναν φάκελο σε μια ενεργή δεξιότητα

Πέντε σενάρια npm στο αποθετήριο του Skills Engine μεταφέρουν μια δεξιότητα από τον επεξεργαστή κειμένου σας στη βιβλιοθήκη και αποδεικνύουν ότι έφτασε.

Εντολή Τι κάνει
npm run skill:validate skills/<slug> Ελέγχει τον κώδικα (lint) του πακέτου. Η δημοσίευση απαιτεί μηδέν σφάλματα
npm run skill:upload skills/<slug> Επικυρώνει και δημοσιεύει σε ένα βήμα· είναι ταυτοδύναμη (idempotent)
npm run skill:upload skills/<slug> --dry-run Επικυρώνει και εμφανίζει το πλάνο χωρίς να γράψει τίποτα
npm run skill:publish -- --dry-run skills/<slug> Η δημοσίευση χαμηλότερου επιπέδου πίσω από τη μεταφόρτωση, ίδια διοχέτευση (pipeline)
npm run skill:reconcile Συγκρίνει τις δεξιότητες στο αποθετήριό σας με αυτές που υπάρχουν στη βιβλιοθήκη και στο μητρώο δεξιοτήτων
npm run skill:live:verify Ελέγχει μια δημοσιευμένη δεξιότητα από την αρχή μέχρι το τέλος στην ενεργή εγκατάσταση

Η δημοσίευση γράφει δύο εγγραφές, και έχουν και οι δύο σημασία. Η μία είναι η ίδια η δεξιότητα, με το σώμα του SKILL.md, τις δυνατότητες, τα στοιχεία και το ιστορικό ποιότητας· αυτήν διαβάζουν η βιβλιοθήκη, η ανακάλυψη και η αντιστοίχιση. Η άλλη είναι η εγγραφή μητρώου ως προς την οποία η μηχανή ροής εργασιών επιλύει μια αποστολή (dispatch). Μια δεξιότητα που έφτασε μόνο στο μητρώο εκτελείται, αλλά είναι αόρατη στη βιβλιοθήκη μέχρι να τη μεταφορτώσετε.

Η δημοσίευση είναι ταυτοδύναμη (idempotent). Μια αμετάβλητη δεξιότητα δεν προκαλεί καμία ενέργεια (no-op), ενώ μια υπάρχουσα δεξιότητα αντιστοιχίζεται μέσω του slug της και ενημερώνεται επιτόπου, χωρίς να επαναδημιουργείται ποτέ. Αν μεταφορτώσετε τα ίδια byte με μια έκδοση που έχει ήδη δημοσιευτεί, θα λάβετε πίσω εκείνη την έκδοση με CONTENT_HASH_ALREADY_PUBLISHED, όχι διπλότυπο.

Το skill:reconcile αντιπαραβάλλει τις δεξιότητες του αποθετηρίου σας με τη βιβλιοθήκη, το μητρώο και το απόθεμα της μηχανής ροής εργασιών, και αναφέρει οτιδήποτε υπάρχει στο ένα μέρος αλλά όχι στο άλλο. Το skill:live:verify προχωρά παραπέρα στην ενεργή εγκατάσταση: ελέγχει ότι υπάρχουν και οι δύο εγγραφές και δείχνουν η μία στην άλλη με το ίδιο hash περιεχομένου, ότι γίνεται δεκτή μια δοκιμαστική αποστολή (dry-run dispatch) του τύπου εργασίας της δεξιότητας, ότι η δεξιότητα εμφανίζεται στη λίστα και στις λεπτομέρειες της βιβλιοθήκης, ότι μπορεί να κληθεί, και ότι το ίχνος ελέγχου (audit trail) συνδέει τη δημοσίευση, την αποστολή και την εκτέλεση μεταξύ τους μέσω του slug και του αναγνωριστικού αιτήματος.

Από έναν σταθμό εργασίας, η μεταφόρτωση φτάνει στην υπηρεσία γνώσης της εγκατάστασης, nexus-graphrag, μέσω προώθησης θύρας (port-forward), και απαιτεί το κλειδί υπηρεσίας του Skills Engine στο περιβάλλον. Φορτώστε το κλειδί χωρίς να εμφανιστεί στην οθόνη (echo):

kubectl -n nexus port-forward svc/nexus-graphrag 8090:8090
read -rs GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
export GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
GRAPHRAG_URL=http://localhost:8090 npm run skill:upload skills/berth-allocation-summary

Μέσα στη συστοιχία (cluster), σε μια εργασία διοχέτευσης (pipeline job), η προεπιλεγμένη διεύθυνση επιλύεται από μόνη της και το GRAPHRAG_URL δεν χρειάζεται. Λάβετε το κλειδί μέσω της διαδικασίας διαχείρισης απορρήτων του οργανισμού σας. Δεν πρέπει ποτέ να μπαίνει στο αποθετήριο, στο ιστορικό του κελύφους (shell history) σας ή στην έξοδο μιας εντολής.

Δοκιμές, έγκριση και θέση σε παραγωγή

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

Έλεγχος Τι κάνει
Περιπτώσεις δοκιμής (Test cases) Κάθε περίπτωση πρέπει να περάσει επιτυχώς πριν η δεξιότητα προωθηθεί για έγκριση. Μια περίπτωση μπορεί να αφαιρεθεί μόνο με αιτιολόγηση, την οποία βλέπουν οι εγκρίνοντες.
Δοκιμαστική εκτέλεση σε λειτουργία shadow Η δεξιότητα εκτελείται σε παλαιότερες εργασίες, όπου κανείς δεν βλέπει τις απαντήσεις, και τα αποτελέσματά της συγκρίνονται με αυτά που είχε αποφασίσει ένας άνθρωπος τότε.
Τυφλή αξιολόγηση από ένα μοντέλο άλλης οικογένειας Αναζητά έναν έλεγχο που παραλείφθηκε, μια επινοημένη πηγή και μια εμφυτευμένη οδηγία την οποία ακολούθησε η δεξιότητα ενώ δεν έπρεπε.

Έπειτα ακολουθεί η έγκριση. Μια δεξιότητα που προσθέτει ένα εργαλείο εγγραφής δεσμεύεται μέχρι να την εγκρίνουν δύο άτομα με τα passkey τους, και το άτομο που την πρότεινε δεν μπορεί να είναι ένα από αυτά (PUBLISH_NEEDS_APPROVAL). Στη συνέχεια τίθεται σε λειτουργία shadow, έπειτα σε canary για μία μονάδα πίσω από καθορισμένες πύλες (gates), και τέλος για όλους. Αν δεν πληρούται κάποια πύλη canary, το canary σταματά από μόνο του και όλοι παραμένουν στην προηγούμενη έκδοση· η πρόωρη διάθεσή της σε όλους απαιτεί αιτιολόγηση και δεύτερο εγκρίνοντα (CANARY_GATE_NOT_MET).

Στην έκδοση Community, το εργαλείο δημιουργίας, η βιβλιοθήκη, οι εκδόσεις και οι δοκιμές είναι όλα διαθέσιμα, και ο κάτοχος δημοσιεύει μόνος του μόλις περάσουν οι δοκιμές. Η λειτουργία canary, η έγκριση από δύο άτομα, ο συγχρονισμός plugin και η συγχώνευση διπλοτύπων διατίθενται στην έκδοση Enterprise.

Νέα δεξιότητα · 4 Δημοσίευση
Νέα δεξιότητα · 4 Δημοσίευση
Η δημοσίευση δείχνει γιατί μια δεξιότητα είναι δεσμευμένη, ποιος πρέπει να συμφωνήσει και πώς τίθεται σε παραγωγή: εγκεκριμένη, σε λειτουργία shadow, σε λειτουργία canary πίσω από καθορισμένες πύλες, και έπειτα για όλους. Αυτός που προτείνει την αλλαγή δεν μπορεί να την εγκρίνει ο ίδιος, και η τελευταία έκδοση παραμένει έτοιμη για επαναφορά.

Πού εμφανίζονται οι δεξιότητες

Η ίδια δημοσιευμένη δεξιότητα φτάνει στους χρήστες σε πέντε σημεία.

  1. Ο βοηθός αντιστοιχίζει ένα αίτημα σε μια δεξιότητα με βάση την περιγραφή, τα εναύσματα (triggers) και τα μοτίβα ερωτημάτων της, και ακολουθεί τις οδηγίες της δεξιότητας.
  2. Οι πράκτορες και οι ροές εργασίας καλούν δεξιότητες ως βήματα. Ένα βήμα ροής εργασίας κατονομάζει τη δεξιότητα· η εκτέλεση καταγράφει ποια έκδοση χρησιμοποίησε.
  3. Τα κουμπιά AI στις οθόνες εκτελούν το καθένα από μία δεξιότητα. Ένας διαχειριστής μπορεί να ανοίξει το «Σχετικά με αυτό το κουμπί» (About this button) για να δει τη δεξιότητα που εκτελεί ένα κουμπί, τι διαβάζει και ποιος την άλλαξε τελευταία, και μπορεί να απενεργοποιήσει το κουμπί χωρίς να πειράξει τη δεξιότητα.
  4. Το IDE (ολοκληρωμένο περιβάλλον ανάπτυξης) σας και το Claude Code έχουν πρόσβαση στη βιβλιοθήκη μέσω του Workbench και δεκατριών εργαλείων MCP (Model Context Protocol): μεταξύ αυτών τα list_skills, get_skill, match_prompt, discover_skills, invoke_skill, record_execution, create_skill, import_skill, get_generation_job και sync_skills_local. Κάθε κλήση εκτελείται με τα στοιχεία του ατόμου που την ξεκίνησε, εντός της δικής του λίστας επιτρεπόμενων.
  5. Η ίδια η βιβλιοθήκη δεξιοτήτων, όπου οι χρήστες περιηγούνται, εκτελούν και προτείνουν αλλαγές σε δεξιότητες, και οι διαχειριστές βλέπουν τον κάτοχο, τους χρήστες, τις εκτελέσεις και τη δαπάνη κάθε δεξιότητας.

Ό,τι κι αν εκτελεί μια δεξιότητα, η δεξιότητα δεν μπορεί να διευρύνει αυτά που επιτρέπεται να κάνει εκείνος που την εκτελεί: καλεί μόνο εργαλεία εντός της λίστας επιτρεπόμενων του εκτελούντος και διαβάζει μόνο όσα επιτρέπεται να ανοίξει το συγκεκριμένο άτομο (SKILL_CANNOT_WIDEN_TOOLS). Μια εκτέλεση χωρίς διαδρομή μοντέλου απορρίπτεται αντί να γίνει εικασία (SKILLS_ENGINE_BINDING_MISSING)· ο μηχανισμός αποστολής (dispatcher) επιλέγει τη διαδρομή από τη ρύθμιση μοντέλων του ίδιου του οργανισμού.

Σχετικά με αυτό το κουμπί
Σχετικά με αυτό το κουμπί
Το «Σχετικά με αυτό το κουμπί» (About this button) δείχνει τη δεξιότητα που εκτελεί ένα κουμπί AI, τις τρεις πηγές που διαβάζει, ποιος την έγραψε και την αξιολόγησε, και τι άλλαξε η τελευταία έκδοση. Η απενεργοποίηση του κουμπιού το αφαιρεί από παντού ταυτόχρονα· η δεξιότητα και κάθε προηγούμενη απάντηση παραμένουν.

Παράδειγμα εφαρμογής: σύνοψη κατανομής θέσεων ελλιμενισμού για τη Harrow

Οι υπεύθυνοι προγραμματισμού της Harrow είχαν ήδη δύο εργαλεία μόνο για ανάγνωση στη λίστα επιτρεπόμενων από το plugin προγραμματισμού θέσεων ελλιμενισμού της ίδιας της Harrow: το berth-plan.read επιστρέφει το πλάνο για μια ημερομηνία, και το vessel-call.read επιστρέφει μια προσέγγιση πλοίου με το παράθυρο άφιξης και το μήκος του. Η δεξιότητα δεν χρειάζεται τίποτα άλλο. Δεν κάνει ποτέ εγγραφές, επομένως δεν χρειάζεται ποτέ δύο εγκρίνοντες.

---
name: berth-allocation-summary
description: Summarise tomorrow's berth plan at Harrow for the planning desk. Use when someone asks who is on which berth, what moved since the last plan, or where two calls clash.
allowed-tools: berth-plan.read, vessel-call.read
triggers:
  - /berth-summary
capabilities:
  - name: summarise_berth_plan
    description: The berth table, the changes since the last plan and any clashes, for one date
version: 1.0.0
visibility: team
status: draft
---

# Berth allocation summary

## When to use
A planner asks about the berth plan for a date, or asks what changed.

## Steps
1. Read the plan for the date with berth-plan.read. If no date is given, use tomorrow.
2. For each call on the plan, read it with vessel-call.read.
3. Write the berth table first: berth, vessel, arrival window, length overall.
4. Then list what moved since the previous plan, one line per change, with the reason the plan records.
5. Then list clashes: two calls whose windows overlap on one berth, or a vessel longer than the berth.
6. Cite the plan's version for every line. Never guess a time the plan doesn't give.

## Output
Three headed sections, in this order: Berths, Changes, Clashes. Write "No clashes" when there are none.

Το skill.yaml δίπλα του δίνει στη βιβλιοθήκη ένα εμφανιζόμενο όνομα, μια κατηγορία και τις διατυπώσεις που πρέπει να δρομολογεί εδώ ο μηχανισμός αντιστοίχισης:

# skill.yaml, beside SKILL.md
name: berth-allocation-summary
display_name: "Berth allocation summary"
version: "1.0.0"
status: draft
visibility: team
category: operations
tags:
  - berths
  - planning
triggers:
  - "/berth-summary"
allowed_tools:
  - berth-plan.read
  - vessel-call.read
capabilities:
  - name: "summarise_berth_plan"
    description: "Berth table, changes since the last plan and clashes, for one date"
    query_patterns:
      - "who is on which berth tomorrow"
      - "what moved on the berth plan"
      - "any berth clashes on *"

Έπειτα οι εντολές, από τον ριζικό κατάλογο (root) του αποθετηρίου:

npm run skill:validate skills/berth-allocation-summary
npm run skill:upload skills/berth-allocation-summary --dry-run
npm run skill:upload skills/berth-allocation-summary

Ο Tomás πρόσθεσε έξι περιπτώσεις δοκιμής στο εργαλείο δημιουργίας: μια συνηθισμένη ημέρα, μια ημέρα με καθυστερημένη άφιξη που μετακίνησε δύο προσεγγίσεις, μια ημέρα με πραγματική σύγκρουση, μια ημερομηνία χωρίς πλάνο ακόμα, ένα πλοίο πολύ μακρύ για τη θέση ελλιμενισμού του, και ένα αίτημα που προσπαθούσε να κάνει τη δεξιότητα να προτείνει μια νέα θέση ελλιμενισμού (δεν θα έπρεπε· δεν διαθέτει εργαλείο εγγραφής). Η δοκιμαστική εκτέλεση αναπαρήγαγε είκοσι παλαιότερα πλάνα σε λειτουργία shadow. Μόλις πέρασαν οι περιπτώσεις, ένας αξιολογητής στο τμήμα προγραμματισμού την ενέκρινε και τέθηκε σε παραγωγή για την ομάδα προγραμματισμού. Ο βοηθός απαντά πλέον στην ερώτηση με την ίδια μορφή κάθε φορά, και το κουμπί AI των υπευθύνων προγραμματισμού στη σελίδα του πλάνου θέσεων ελλιμενισμού εκτελεί την ίδια δεξιότητα.

Μέρος 2: δεξιότητες manifest

Μια δεξιότητα manifest είναι η μονάδα υπολογιστικής ισχύος που δημοσιεύει ένα plugin. Δηλώνεται στο skills[] του manifest, επικυρώνεται από το SDK (software development kit) όταν εκτελείτε το create-nexus-plugin validate, μεταγλωττίζεται στο σώμα του μητρώου από το compileRegistry, και συγχρονίζεται στο μητρώο δεξιοτήτων. Δεν γράφετε ποτέ κώδικα SQL μητρώου με το χέρι, επομένως η εγγραφή που αποστέλλει η πλατφόρμα και ο περιγραφέας (descriptor) που δηλώσατε δεν μπορούν να αποκλίνουν μεταξύ τους.

Κάθε δεξιότητα manifest χρειάζεται τα id, displayName, description, tier, classification, inputSchema και outputSchema. Δηλώστε επίσης το timeoutMs: είναι ένας ακέραιος αριθμός από 1.000 έως 21.600.000 (ένα δευτερόλεπτο έως έξι ώρες), και μια τιμή εκτός αυτού του εύρους απορρίπτεται με TIMEOUT_OUT_OF_BOUNDS. Το dataResidency είναι any, eu ή us, με προεπιλογή το any.

Το id είναι σε μορφή lower_snake, και το κλειδί αποστολής του μητρώου είναι ο τύπος εργασίας με χώρο ονομάτων (namespaced) <plugin name>.<skill id>, έτσι ώστε δύο plugin να μπορούν να έχουν και τα δύο μια δεξιότητα summarise χωρίς σύγκρουση. Ορίστε η μία δεξιότητα του προτύπου, συνοπτικά:

{
  "id": "sentiment_score",
  "displayName": "Sentiment score",
  "description": "Deterministic lexicon-based sentiment score for a piece of text.",
  "tier": "host_callback",
  "classification": "tenant",
  "dataResidency": "any",
  "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 } }, "required": ["text"] },
  "outputSchema": { "type": "object", "properties": { "score": { "type": "number" } }, "required": ["score"] },
  "hostCallback": {
    "service": "my-plugin",
    "port": 8080,
    "path": "/internal/skills/sentiment_score",
    "maxRequestBytes": 262144,
    "maxResponseBytes": 16384,
    "tenantHeader": "X-Organization-ID"
  },
  "timeoutMs": 10000
}

Τα πέντε επίπεδα (tiers)

Το επίπεδο δεν είναι απλώς μια ετικέτα. Κάθε επίπεδο έχει τα δικά του πεδία, και ένα πεδίο που ανήκει σε άλλο επίπεδο απορρίπτεται με FIELD_NOT_FOR_TIER αντί να παραβλεφθεί σιωπηλά.

Βαθμίδα Απαιτεί Καλεί μοντέλο Ποιος την εκτελεί
host_callback hostCallback: το Service σας, τη θύρα του, μια διαδρομή και τα δύο όρια byte Όχι Η πλατφόρμα στέλνει με POST την είσοδο στο δικό σας Service, εντός του namespace σας
plugin_queue queueName, γραμμένο ως <plugin name>.<name> Όχι Ο δικός σας worker, αντλώντας από την ουρά σας
tool_using systemPrompt και tools[]· επίπεδο εμπιστοσύνης core ή verified Ναι Η πλατφόρμα, μέσω του AI Provider Router· κάθε κλήση εργαλείου εκτελείται μέσω ενός εγκεκριμένου εκτελεστή (executor)
llm_only systemPrompt· επίπεδο εμπιστοσύνης core ή verified Ναι Η πλατφόρμα, μία κλήση μέσω του AI Provider Router
map map.perItemJobType, κατονομάζοντας μια άλλη δεξιότητα του ίδιου manifest που δεν είναι map Μόνο μέσω του στόχου της Η πλατφόρμα εκτελεί τον στόχο μία φορά ανά στοιχείο και συγκεντρώνει τα αποτελέσματα

Κανένα από τα δύο επίπεδα μοντέλου δεν κατονομάζει πάροχο ή μοντέλο. Ο δρομολογητής επιλέγει και τα δύο από τη δεξαμενή πόρων του οργανισμού που κάνει την αποστολή. Ένα εργαλείο σε μια δεξιότητα tool_using κατονομάζει έναν από τους έξι εκτελεστές: standing_service_call (το δικό σας Service), graphrag, graphrag_query, graphrag_search, h3 ή web_search. Οποιοσδήποτε άλλος απορρίπτεται με EXECUTOR_NOT_PERMITTED. Οι τρεις εκτελεστές γραφήματος γνώσης (knowledge-graph) δέχονται μόνο τα ονόματα εργαλείων graphrag_query και graphrag_search, επειδή ο εκτελεστής τρέχει όποια λειτουργία έχει το όνομα του εργαλείου.

Στο μητρώο υπάρχουν δύο επίπεδα που ένα plugin δεν μπορεί να δηλώσει: οι αλυσίδες (chains) και οι δεξιότητες που εκτελούνται μόνες τους γράφονται μόνο από την πλατφόρμα. Ένας συγχρονισμός που κατονομάζει κάποιο από αυτά απορρίπτεται εξ ολοκλήρου.

Ποιο επίπεδο να χρησιμοποιήσετε

  • host_callback όταν η εργασία είναι μια συνάρτηση της εισόδου που υπολογίζει ο δικός σας κώδικας: μια βαθμολογία, ένας υπολογισμός, μια αναζήτηση στο δικό σας σχήμα. Είναι το απλούστερο στη δοκιμή και η προεπιλογή του προτύπου. Προστατέψτε τη διαδρομή επανάκλησης (callback route): μια διαδρομή σε ένα manifest δεν είναι μυστικό, και η διαδρομή πρέπει να επαληθεύει την κλήση της πλατφόρμας και να λαμβάνει τον οργανισμό από αυτήν, ποτέ από το σώμα του αιτήματος. Δηλώστε την ως auth: internal και προσαρτήστε το requireService (Fastify) ή το serviceMiddleware (Express) σε αυτήν. Ο μηχανισμός προστασίας (guard) απορρίπτει ένα token που εκδόθηκε για οποιονδήποτε άλλον. Απαντήστε γρήγορα και φροντίστε ώστε μια δεύτερη παράδοση της ίδιας εργασίας να είναι αβλαβής.
  • plugin_queue για πιο χρονοβόρες εργασίες τις οποίες περιμένει ένας χρήστης, όπου ο δικός σας worker ελέγχει τον κύκλο ζωής. Ο worker πρέπει να μεταφέρει την εκτέλεση σε κατάσταση running όταν ξεκινά και σε μια τερματική κατάσταση όταν ολοκληρώνεται· ένας worker που απλώς δημοσιεύει το αποτέλεσμά του αφήνει την εκτέλεση να εμφανίζει queued για πάντα.
  • llm_only όταν μία κλήση μοντέλου με σταθερή προτροπή συστήματος (system prompt) κάνει τη δουλειά, και το plugin σας είναι core ή verified.
  • tool_using όταν το μοντέλο χρειάζεται να καλεί εργαλεία σε βρόχο (loop), και πάλι μόνο σε core ή verified.
  • map όταν θέλετε η πλατφόρμα να αναπτύξει παράλληλα (fan out) μία από τις άλλες δεξιότητές σας πάνω σε μια λίστα.

Η δεξιότητα διάδοσης τροχιάς μου στην Corrán Orbital είναι host_callback. Το plugin μας είναι community, επομένως τα επίπεδα μοντέλου δεν αποτέλεσαν ποτέ επιλογή, και δεν μου λείπουν: ένας υπολογιστής διάδοσης που θα έδινε διαφορετική απάντηση την Τρίτη θα ήταν χειρότερος κι από άχρηστος.

Έγκριση πριν από κάθε εκτέλεση

Μια δεξιότητα manifest που δεν πρέπει ποτέ να εκτελείται μόνο με την εντολή μιας μηχανής το δηλώνει:

"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }

Το required είναι πάντα true· μια δεξιότητα που δεν χρειάζεται έγκριση παραλείπει το μπλοκ. Το reason είναι αυτό που βλέπει ο εγκρίνων, 1 έως 500 χαρακτήρες μετά την αφαίρεση κενών (trimming), και οποιαδήποτε άλλη μορφή απορρίπτεται με APPROVAL_INVALID. Μια αποστολή της δεξιότητας τότε δεσμεύεται: η αποστολή απαντά 202 με status: "awaiting_approval" και ένα waitpointId, και μόνο η έγκριση ενός κατονομαζόμενου ατόμου την αποδεσμεύει, για μία φορά. Μια αποστολή δέσμης (batch), map ή αλυσίδας (chain) μιας δεσμευμένης δεξιότητας απορρίπτεται με SKILL_APPROVAL_NOT_HOLDABLE, επειδή μια παράλληλη ανάπτυξη (fan-out) δεν μπορεί να θέσει σε αναμονή τα επιμέρους στοιχεία της. Εμφανίστε την απάντηση αναμονής και αφήστε τον εγκρίνοντα να αποφασίσει· μην κάνετε αποστολή και μετά ζητάτε συγκατάθεση.

Συγχρονισμός στο μητρώο

Κάθε συγχρονισμός είναι δηλωτικός (declarative) και ελέγχεται ως σύνολο. Στέλνετε το πλήρες σύνολο δεξιοτήτων κάθε φορά: μια δεξιότητα που παραλείπετε απενεργοποιείται, ενώ το ιστορικό εκτελέσεών της παραμένει. Μία ελαττωματική δεξιότητα απορρίπτει ολόκληρο τον συγχρονισμό με SYNC_CONTRACT_VIOLATION, εμφανίζοντας όλες τις παραβάσεις μαζί και χωρίς να γραφτεί τίποτα, έτσι ώστε ένα plugin να μην ενημερώνεται ποτέ κατά το ήμισυ. Το Κεφάλαιο 2.22, Το περιβάλλον εκτέλεσης (runtime) των plugin, καλύπτει την κλήση συγχρονισμού και τον τρόπο με τον οποίο η πλατφόρμα γνωρίζει ποιο plugin καλεί.

Δεξιότητες στο IDE και στο Claude Code
Δεξιότητες στο IDE και το Claude Code
Το «Δεξιότητες στο IDE και στο Claude Code» δείχνει τα ίδια βήματα επικύρωσης, μεταφόρτωσης και δημοσίευσης από το τερματικό μιας προγραμματίστριας, με το προσχέδιο σε αναμονή έγκρισης επειδή η δημιουργός του δεν μπορεί να εγκρίνει τη δική της αλλαγή.

Επιλογή μεταξύ των δύο ειδών

Αν η εργασία είναι «πες αυτό με τον ίδιο τρόπο κάθε φορά», πρόκειται για δεξιότητα του Skills Engine. Αν η εργασία είναι «εκτέλεσε τον κώδικά μου και δώσε μου την απάντησή του», πρόκειται για δεξιότητα manifest. Οι περισσότερες πραγματικές εργασίες καταλήγουν να είναι και τα δύο: η σύνοψη θέσεων ελλιμενισμού της Harrow είναι μια δεξιότητα του Skills Engine της οποίας τα εργαλεία προέρχονται από ένα plugin, και τα εργαλεία του plugin δηλώνονται τα ίδια στο manifest του. Η δεξιότητα του Skills Engine είναι η πιο οικονομική από τις δύο για να αλλάξει, κάτι που αποτελεί καλό λόγο για να κρατήσετε τη διατύπωση και την κρίση εκεί και τους αριθμητικούς υπολογισμούς στο plugin.

Το κόστος είναι υπαρκτό και στις δύο περιπτώσεις. Μια δεξιότητα του Skills Engine δεν είναι έτοιμη όταν το SKILL.md διαβάζεται ωραία· είναι έτοιμη όταν οι περιπτώσεις δοκιμής της περνούν επιτυχώς, η δοκιμαστική της εκτέλεση συμφωνεί με αυτά που αποφάσισαν οι άνθρωποι, και κάποιος άλλος εκτός από εσάς την έχει εγκρίνει. Υπολογίστε μία εβδομάδα για μια δεξιότητα που κάνει εγγραφές, το μεγαλύτερο μέρος της οποίας αφορά τη λειτουργία canary.