Agent Skills ו-SKILL.md: חשיפה הדרגתית, במדידה

פרק 14 קבע את הכלל לחצי השני של הקורס הזה — חיבורים, ניסיונות חוזרים וביטול הם TypeScript — והכריז על חמישה חריגים. זה אחד מהם, והסיבה אינה העדפה.

skill הוא קובץ Markdown. לא קובץ שמגדיר תוכנה, לא קובץ שתוכנה מקמפלת: מסמך שהמודל קורא, באותו אופן שבו הוא קורא את ההודעה שהקלדת. לתת לפרק הזה שפת תכנות היה אומר לא להבין את הפורמט, ואי-ההבנה הזאת היא הנפוצה ביותר לגבי skills. כל מה שבהמשך הוא Markdown ו-YAML, ועוד סקריפט shell קטן אחד שקיים בדיוק כדי להראות איפה קוד כן ולא שייך בתוך skill.

הנה הוראה אמיתית: איך חברה אחת כותבת את הערות הגרסה שלה. זו פרוצדורה, לא העדפה — יש לה סדר פעולות, טקסונומיה, קול, תבנית וסקריפט שאוסף את חומר הגלם.

שימו את כולה ב-system prompt, כמו שרוב הצוותים עושים, והחשבון של פרק 16 משתלט. system prompt הוא קידומת, ועל קידומת משלמים בכל קריאה. נמדד עם o200k_base על התיקייה שנכתבה לפרק הזה:

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

זול פי עשרים וארבע כשהוא בשימוש, וזול פי שלושים ושבע כשהוא לא. התעריפים הם של פרק 16: $2.00 למיליון input tokens.

עכשיו ההתנגדות הכנה, כי פרק שהיה מדלג עליה היה פרסומת. prompt caching כמעט סוגר את פער הכסף. system prompt יציב ונמצא ראשון, מה שהופך אותו למועמד המטמון הטוב ביותר שיש; ב-$0.20 למיליון עבור קלט cached, אותם 68,640 token עולים $0.0168 במקום $0.1373. עדיין פי שלושה מה-skill, אבל כבר לא סדר גודל אחר.

הכסף מעולם לא היה הטיעון החזק ביותר. זה כן:

Caching הופך קידומת קבועה לזולה יותר. הוא לא הופך אותה לקטנה יותר.

בתור 40, גרסת ה-system-prompt עדיין מחזיקה 1,716 token של מדיניות הערות גרסה בתוך החלון בזמן שיחה על משהו אחר לגמרי, ומתחרה על מה שפרק 24 קרא תקציב ה-attention של המודל. לגרסת ה-skill יש 46. עשו cache לדבר הלא נכון וקניתם הנחה על הסחת דעת.

כנוסחה, עם $n$ תורות, $L_1$ המטא-דאטה, $L_2$ הגוף, $L_3$ החבילה כולה ו-$R$ קבוצת הקבצים המצורפים שנקראו בפועל:

כל הפרק הזה הוא ההבדל בין להכפיל את האיבר השני ב-$n$ לבין להכפיל אותו באחד או באפס.

skill הוא תיקייה. המפרט קצר מספיק כדי להציג אותו בשלמותו:

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md חייב להתחיל ב-YAML frontmatter, ונדרשים בדיוק שני שדות: name ו-description.¹ ארבעה נוספים אופציונליים, ולא מוגדרים אחרים:

הנה skill הערות הגרסה, בשלמותו, עם גוף של פחות משלושים שורות:

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

קראו מה הגוף הזה. הוא לא המדיניות — הוא תוכן עניינים עם סדר פעולות. המדיניות נמצאת בשלושה קבצים שהוא מציין בשמם ולא כולל. והצעד הראשון מעביר עבודה לסקריפט, כי הקוד של סקריפט לעולם לא נכנס ל-context window בכלל: רק הפלט שלו כן.²

למודל הטעינה יש שם ושלושה שלבים. המפרט מציג אותם עם תקציב token צמוד:¹

1. מטא-דאטה, בערך 100 token: name ו-description, נטענים בהפעלה עבור כל skill מותקן.
2. הוראות, מומלץ פחות מ-5,000 token: גוף ה-SKILL.md, נטען כשה-skill מופעל.
3. משאבים, לפי הצורך: קבצים מצורפים, נטענים רק כשמשהו דורש אותם.

תיעוד הייחוס מוסיף עמודה רביעית לאותה טבלה — מתי נטען, עלות token, תוכן — והשורה החשובה היא השלישית: כלום עד שניגשים אליו.³ גם המשפט שמסכם את כל הפרק נמצא שם:

קבצים לא צורכים context עד שניגשים אליהם, ולכן Skills יכולים לכלול תיעוד API מקיף, מערכי נתונים גדולים או דוגמאות נרחבות. אין קנס context על תוכן מצורף שלא נעשה בו שימוש.³

הטבלה הנמדדת בראש הפרק הזה היא בדיקה של הטענה הזאת מול חמישה skills שאף אחד לא כתב בשביל המאמר הזה. שתי שורות ראויות לקריאה זו מול זו.

ל-next-best-practices יש גוף של 966 token שמקשר לתשעה-עשר קבצים המחזיקים 19,374 token. בקשו ממנו לתקן שגיאת hydration וה-agent קורא את הגוף פלוס hydration-error.md: 1,409 token מתוך 20,340, יחס של פי ארבעה-עשר, ושמונה-עשר הקבצים האחרים לעולם לא נפתחים.

ל-next-cache-components יש גוף של 2,334 token ואין לו קבצים מצורפים בכלל. זה skill תקין וכתוב היטב, ואין לו רמה 3 לחשוף. זו המגבלה הכנה של הטכניקה: חשיפה הדרגתית חוסכת רק אם יש משהו לדחות. skill שהידע שלו לא מתפרק משלם את כל הגוף שלו בהפעלה, והמנוף היחיד שנותר הוא לא להפעיל אותו.

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

המפרט אומר זאת באמצעות דוגמה טובה ודוגמה גרועה, והגרועה היא ארבע מילים: description: Helps with PDFs.¹ שווה למדוד את זה במקום לקבל את זה כמובן מאליו.

שישה skills, כל אחד עם תיאור סביר שאומר מה הוא עושה ומתי להשתמש בו. עשרים וארבע בקשות, ארבע לכל skill, מנוסחות כפי שאדם היה מנסח אותן ולעולם לא מציינות את שם ה-skill. המודל רואה את שש השורות ב-system prompt שלו וחייב לענות בשם אחד או ב-NONE. Greedy decoding, כדי שיהיה ניתן לשחזר. ואז אותן עשרים וארבע בקשות עם אותם שישה skills, כשהתיאורים קוצצו לנושא החשוף שלהם.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

קראו קודם את המרווחים, כפי שפרק 4 התעקש ופרק 29 יתעקש שוב: הם חופפים, ועשרים וארבעה מקרים לא יכולים לדרג שתי מערכות על סמך הצבירות שלהן בלבד. ההשוואה המזווגת היא מה שמכריע, והיא הכלי של פרק 15: מתוך עשרת המקרים שבהם שני הזרועות חלקו זו על זו, תשעה הלכו לתיאורים העשירים ואחד לרזים. זה עומד בסף המקובל.

עכשיו קראו את השורה האחרונה, שהיא הממצא האמיתי. עם תיאורים רזים המודל ענה NONE בתשע מתוך עשרים וארבע בקשות. לא ה-skill הלא נכון: אין skill. הנה ארבע מהן, מילה במילה:

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

skill sql-review מושלם היה מותקן, עם גוף ודוגמאות וצ׳קליסט, והוא מעולם לא נפתח, שלוש פעמים ברצף, על שלוש השאלות שהוא נכתב בשבילן. רמות 2 ו-3 לא רלוונטיות ל-skill שרמה 1 לעולם לא מגיעה אליו.

עלות התיקון: 214 token, ההפרש בין 295 ל-81, מפוזר על פני שישה skills. זה הממצא של פרק 18 שמגיע מהצד השני. שם, שינוי רק של תיאור כלי לקח עיצוב תאריכים מ-2 נכונים מתוך 24 ל-24 מתוך 24. כאן, שינוי רק של תיאור skill לוקח הפעלה מ-10 מתוך 24 ל-18. בשני המקרים התיקון הזול ביותר במערכת הוא משפט, ובשני המקרים המשפט חייב לציין את ה-trigger ולא רק את הנושא: לא מה הדבר, אלא מה המשתמש בדיוק אמר כשהוא רלוונטי.

הסתייגות אחת שהפרק הזה חייב לסטנדרטים של עצמו. זה מודל של חצי מיליארד פרמטרים, ומודל frontier מנתב הרבה יותר טוב מ-75%. קראו את המנגנון, לא את הגודל: אות הניתוב הוא משפט אחד באורכו, לא משנה איזה מודל קורא אותו, ואף מודל לא יכול לבחור על סמך מידע שלא שמתם במשפט הזה.

הכשל השני הוא ההפך מהראשון. ה-skill נמצא, הרמות מפוצלות נכון, וה-agent קורא את כולו בכל זאת.

vercel-react-best-practices הוא skill שבנוי באמת היטב. הגוף שלו, 1,670 token, הוא טבלת עדיפויות של שמונה קטגוריות ועיון מהיר שמונה 70 קובצי כללים, שורה אחת לכל אחד. הכללים נמצאים בדיסק לידו: 70 קבצים, הקטן 132 token, החציון 319, הגדול 1,052. שאלו אותו שאלה אחת על barrel imports והעלות הכנה היא הגוף פלוס קובץ אחד — פחות מ-2,400 token מול חבילה של 53,670.

ואז השורה האחרונה בגוף אומרת כך:

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md הוא 26,362 token. אלה 70 קובצי הכללים משורשרים: הסכום שלהם הוא 25,784, וההפרש הוא הכותרות ביניהם. כך שה-skill מציע ל-agent בחירה בין קריאת כלל חציוני אחד ב-319 token לבין קריאת אותו תוכן, כולו, במחיר גבוה פי שמונים ושלושה — והוא מציע את הבחירה הזאת במשפט בלי עלות צמודה ובלי תנאי מתי לקחת אותה.

זה לא באג והקובץ לא שגוי; מסמך מקומפל באמת שימושי לאדם, ול-agent שהתבקש לבצע ביקורת על בסיס קוד שלם. זה קובץ רמה 3 עם הזמנה ברמה 2, והלקח מכליל מעבר ל-skill הזה: כל נתיב שיוצא מתוך SKILL.md צריך לומר מה הוא עולה ומתי הוא שווה את זה, כי למודל אין דרך לדעת ששם קובץ יקר פי שמונים ושלושה משם הקובץ שמעליו.

אותה תיקייה נושאת לקח קטן יותר על התיישנות. הגוף אומר ״70 כללים על פני 8 קטגוריות״ ומונה 70; תיקיית rules/ מחזיקה 72 קבצים, מתוכם שניים הם scaffolding ‏(_template.md ו-_sections.md); וה-sidecar metadata.json אומר ״40+ כללים״. שלוש ספירות של אותה קבוצה בתיקייה אחת, אחת מהן נכונה, אחת מהן אריתמטית, ואחת נשארה מגרסה קודמת. skill הוא מסמך, ומסמכים נרקבים בדיוק כמו הערת קוד שסטתה מהקוד שלצידה — עם ההבדל שאת זה קוראת מכונה שלא תרים גבה.

המפרט הפתוח מגדיר שישה שדות frontmatter. מימוש הייחוס, Claude Code, מקבל עשרים.² כדאי להכיר בשם חמש קבוצות, כי שם הפורמט מפסיק להיות רק מסמך:

ארגומנטים (arguments, argument-hint) מאפשרים לאדם להעביר ערכים שמוחלפים בתוך הגוף, וזה מה שהופך skill לשימושי כפקודת slash. תחימה (paths) מגבילה הפעלה לקבצים שתואמים glob. והזרקת context דינמית היא זו שמשנה את המודל המנטלי: שורה בצורה !`git diff HEAD` רצה לפני שהגוף נשלח, והפלט שלה מוחלף בתוך הטקסט. המסמך הוא תבנית, וחלק ממנו מחושב בזמן הקריאה.

עכשיו המלכודת, והיא נאמרת באותו תיעוד: מחוץ ל-Claude Code — במוצר הווב, דרך Skills API, באריזה — רק ששת השדות המוגדרים מותרים, וכל שדה אחר הוא שגיאה קשיחה בהעלאה.² כך ש-skill שעובד מושלם במוצר אחד נכשל בהתקנה במוצר אחר של אותו ספק, והוא נכשל ב-frontmatter ולא במשהו שאפשר לבדוק על ידי קריאת הפרוזה. אם אתם מתכוונים ש-skill יהיה נייד, ששת השדות הם כל התקציב. אם לא, אמרו זאת ב-compatibility, שקיים בדיוק בשביל זה.

ארבעה דברים מתבלבלים זה עם זה כל הזמן, והבלבול אינו דקדוק מילוני: בחירה שגויה עולה כסף בכל תור, או עולה לכם בערבות שחשבתם שיש לכם.

שתי השורות המודגשות הן כל ההבחנה. skill נקרא; כלי מופעל. skill הוא פרוזה שמגיעה ל-context window ומתחרה על attention עם כל מה שיש שם; המודל יכול לפעול לפיה, לקרוא אותה לא נכון או להתעלם ממנה, ושום דבר במערכת לא שם לב. כלי הוא קריאה שיוצאת לגמרי מידי המודל: הקוד שלכם מקבל ארגומנטים, מאמת אותם, בודק הרשאות ומחליט. פרק 18 ניסח זאת כך שהמודל מציע והקוד שלכם קובע, וזו בדיוק החלוקה שאין ל-skill.

אז שישה מקרים אמיתיים, מוכרעים:

ההיסטוריה קצרה, מתוארכת באופן חריג היטב, והיא החלק שכמעט אף אחד לא מספר.

Agent Skills פורסמו ב-16 באוקטובר 2025 כפיצ׳ר של ספק אחד, והוגדרו בהכרזה כ״תיקיות מאורגנות של הוראות, סקריפטים ומשאבים ש-agents יכולים לגלות ולטעון דינמית כדי לבצע טוב יותר משימות ספציפיות״, עם שלוש הרמות המתוארות באנלוגיה שכדאי לשמור: ״כמו מדריך מאורגן היטב שמתחיל בתוכן עניינים, ממשיך לפרקים ספציפיים, ולבסוף לנספח מפורט״.⁴

ב-18 בדצמבר 2025 אותו עמוד עודכן כדי להכריז על הפורמט כסטנדרט פתוח, עם מפרט משלו ב-agentskills.io, ממשל פתוח לתרומות, ו-validator ייחוס.³ נכון לקריאה ב-7 בספטמבר 2026, חלון הראווה של לקוחות הסטנדרט מונה ארבעים ושישה מוצרים — עורכים, טרמינלים, פלטפורמות ענן וסביבות ריצה מובייל, כולל agents לקידוד של Anthropic, OpenAI, Google ו-Mistral — וכל אחד מקשר לתיעוד ההתקנה שלו.¹

ההתכנסות עם MCP נעשית בגלוי, עם מספרים שאפשר לבדוק:

החלק המעניין הוא הסגירה, לא ההצעות. SEP-2076 ביקש פרימיטיב רביעי לצד כלים, משאבים ו-prompts. ה-working group שנוצרה ממנו החליטה שהתשובה היא לא: skills נוסעים על פרימיטיב המשאבים שכבר קיים, כהרחבה opt-in.⁵ פרק 26 מדד את אותו אינסטינקט ביומן השינויים של הפרוטוקול עצמו, שבו sampling, roots ו-logging הוצאו משימוש במקום להישמר. גוף תקינה שמסיר הצעה שהוא עצמו חיבר מתנהג היטב, והסיבה לספר את הסיפור הזה עם המספרים מול העיניים היא שהסיכומים שתקראו במקומות אחרים עדיין מתארים skills כ-MCP primitive.

עכשיו אתם יכולים לכתוב SKILL.md, לפצל אותו לשלוש רמות שמחזירות את עלותן, לקרוא את ה-frontmatter של skill של מישהו אחר ולדעת אילו שדות לא ישרדו העלאה למקום אחר, ולענות על השאלה שכל הפרק נבנה סביבה — system prompt, skill, כלי או server — עם סיבה ולא עם הרגל.

מה שאתם לא יכולים לעשות הוא לדעת אם שלכם עובד.

כל טענה בפרק הזה שהייתה חשובה הייתה מדידה, והחשובה ביותר הייתה דיוק: 18 מתוך 24 מול 10 מתוך 24, עם מרווח על כל אחד ומבחן מזווג ביניהם, כי שתי צבירות שחופפות לא מכריעות כלום. הכלי הזה הושאל. תיאור של skill הוא מפתח ניתוב, הגוף שלו הוא פרוצדורה שהמודל עשוי לבצע או לא, ושתי התכונות האלה הן דברים שאפשר לגלות רק על ידי הרצת הדבר פעמים רבות וציון מה שחזר — כלומר golden set, grader שכתבתם לפני הריצה, והמדד ששואל אם זה עבד בכל פעם ולא לפחות פעם אחת.

פרק 29 הוא זה, והוא נפתח במספר שהשיטה של הפרק הזה תלויה בו: agent שמצליח שבע פעמים מתוך עשר נראה כמו 70%, וה-pass^10 שלו — הסיכוי שהוא יצליח בכל העשר — הוא אפס. הוא גם מודד שלושה graders על אותם מאתיים תמלילים ומקבל 0%, 13% ו-26% בלי ליצור מחדש token אחד. לפני שתבטחו במשפט שזה עתה כתבתם לתוך description, אתם צריכים את הכלי שיכול לומר לכם שהוא גרוע יותר מזה שהחלפתם.

כל ספירת token בפרק הזה הופקה מקומית עם tiktoken 0.14.0 ו-encoding ‏o200k_base, ב-7 בספטמבר 2026: על חמשת ה-skills של צד שלישי שמפורטים בתחילת הפרק הזה, ועל skill ‏release-notes שנכתב לפרק הזה, שהטקסט המלא שלו משוחזר בחלקו למעלה. רמה 1 נמדדת כשורה היחידה - name: description ש-host מרנדר לתוך ה-system prompt; רמה 2 היא גוף ה-SKILL.md אחרי ה-frontmatter; רמה 3 היא כל קובץ אחר בתיקייה. העלויות משתמשות בתעריפים הנמדדים של פרק 16 עבור gpt-5.6-terra, ‏$2.00 למיליון input tokens ו-$0.20 למיליון input tokens ב-cache, מיושמים על הספירות האלה — זו אריתמטיקה על token שנמדדו, לא תצפיות בחשבון חי. לא בוצעה קריאת API בתשלום כדי לכתוב את הפרק הזה.

ניסוי ההפעלה הריץ Qwen/Qwen2.5-0.5B-Instruct ב-half precision על GPU צרכני אחד, greedy decoding, ‏24 בקשות על פני שישה skills, פעמיים — פעם עם תיאורים שמציינים מה ה-skill עושה ומתי הוא חל, ופעם עם תיאורים שקוצצו לנושא חשוף בסגנון ה״דוגמה הגרועה״ של המפרט עצמו. המרווחים הם Wilson ב-95%; ההשוואה המזווגת היא exact sign test דו-צדדי על עשרת המקרים הדיסקורדנטיים; מרווח Wilson הוא של פרק 4 וה-exact paired sign test הוא של פרק 15, שניהם בשימוש חוזר ללא שינוי. קראו את הגדלים כתכונה של מודל קטן מאוד ואת השיטה כניתנת להעברה.

חמשת ה-skills שנמדדו כאן הם חבילות צד שלישי, לא נכתבו לפרק הזה: next-best-practices ו-next-cache-components מ-vercel-labs/next-skills, ו-vercel-composition-patterns, ‏vercel-react-best-practices ו-vercel-react-native-skills מ-vercel-labs/agent-skills. הספירות הפנימיות שלהם — 70 קובצי כללים, AGENTS.md ב-26,362 token, ‏metadata.json מתוארך לינואר 2026 וטוען ל-״40+ כללים״ — נקראו מהקבצים בדיסק ב-7 בספטמבר 2026 והן תכונות של אותה גרסה שפורסמה, לא ביקורת על המחברים שלה: כל אחת מהן היא סוג ה-drift שמופיע בכל עץ תיעוד שנערך לעיתים קרובות יותר משהוא נספר.