SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor

איך כותבים מיומנות סוכן משלכם

למדו לכתוב מיומנות סוכן מתוך כשל אמיתי: מבנה SKILL.md, שורת התיאור שקובעת מתי היא מופעלת, ובדיקה שמוודאת שהתיקון עובד.

כתיבת מיומנות סוכן (agent skill) מבוססת על כשל אמיתי

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

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

התחלה ממשימה שהסוכן ביצע באופן שגוי פעמיים

פעם אחת היא מקריות. פעמיים הן דפוס, ודפוס מצדיק יצירת קובץ.

להלן כשל שחוזר על עצמו בשרתים אמיתיים. אתם מבקשים מהסוכן להוסיף בלוק reverse proxy ל-nginx. הוא עורך את /etc/nginx/conf.d/app.conf, ואז מריץ את sudo systemctl restart nginx. בעריכה יש שגיאת הקלדה, לכן nginx מסרב לעלות, והאתר מושבת עד שתתקנו זאת:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

אתם מתקנים זאת בצ'אט. בדקו את התצורה בעזרת sudo nginx -t לפני שאתם נוגעים בשירות, ואז החילו אותה בעזרת reload במקום restart. שבוע לאחר מכן, במשימה אחרת, אותה טעות חוזרת. הפעם השנייה היא הסימן.

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

הנחיות הכתיבה של Anthropic מציבות זאת במקום הראשון. הריצו את הסוכן על משימות מייצגות ללא מיומנות, תעדו היכן הוא נכשל, ואז כתבו את ההוראות המינימליות שמתקנות את הכשלים הללו. הכשלים הם המפרט, לכן מיומנות שאינכם יכולים לקשר לכשל כזה היא בדרך כלל מיומנות שאף אחד לא היה זקוק לה. אותו מסנן עובד על מיומנויות שאתם מתקינים במקום לכתוב, ו-27 מיומנויות התוסף של Matt Pocock מתחלקות לאלו שמפתח בודד ב-VPS צריך להתקין ולאלו שמשתלמות רק בצוות. ספריית הבטא הציבורית שלו מפרטת שבע מיומנויות נוספות הניתנות להתקנה שאינן כלולות בתוסף.

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

האנטומיה של Skill

Skill הוא ספרייה המכילה קובץ אחד נדרש.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md נפתח בבלוק frontmatter, הכולל מספר הגדרות הכתובות בפורמט YAML (אותו פורמט תצורה שבו משתמשים קובצי Docker Compose) בין סמני ---, ולאחריו ההוראות בפורמט markdown. להלן ה-Skill המלא עבור הכשל שצוין לעיל.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

קובץ זה מכיל פחות מעשרים שורות והוא מהווה Skill מלא. אלו הם חלקיו:

  • name: עד 64 תווים, אותיות קטנות בלבד, ספרות ומקפים, ללא המילים claude או anthropic. ב-Skill אישי או של פרויקט, הגדרה זו קובעת את הפקודה שתוצג בתפריט /, אלא אם שם זה כבר נמצא בשימוש על ידי פקודה אחרת. שם הספרייה מפעיל גם הוא את ה-Skill, לכן זה מגיב ל-/nginx-config-changes.
  • description: תיאור פעולת ה-Skill ומתי להשתמש בו, עד 1,024 תווים. שורה זו מבצעת את העבודה בפועל, והסעיף הבא עוסק אך ורק בה.
  • גוף הקובץ: ההוראות, הנטענות רק כאשר ה-Skill מופעל בפועל.
  • reference/: קבצים נוספים שהסוכן קורא לפי דרישה. יש לקשר אליהם מתוך SKILL.md ולשמור על קישורים ברמה אחת בלבד, שכן קובץ המקושר מקובץ אחר שקושר נקרא לעיתים קרובות רק בחלקו.
  • scripts/: קבצים שהסוכן מריץ במקום לקרוא. רק הפלט שלהם צורך context, לכן סקריפט של 300 שורות הוא זול מבחינת משאבים.

Skill מתפתח למבנה מלא כאשר ההתנהגות שהוא מתקן עקשנית מספיק כדי לדרוש זאת, ו-ה-Skill הלא-עצלן משקיע את המקום הזה ב-Depth Tree, קבוצת קובצי gates וחוזה PLAN.md כדי למנוע מהסוכן להכריז על סיום עבודה בעוד ענפים שלמים של המשימה נותרו ללא טיפול.

המיקום שבו תציבו את הספרייה קובע למי תהיה גישה ל-Skill.

  • .claude/skills/<name>/SKILL.md במאגר (repository): פרויקט זה בלבד, והוא עובר לכל מי שמשכפל (clone) את המאגר.
  • ~/.claude/skills/<name>/SKILL.md: כל פרויקט במכונה שלכם, ולא של אף אחד אחר.
  • <plugin>/skills/<name>/SKILL.md: מופץ בתוך תוסף (plugin), זמין בכל מקום שבו התוסף מופעל.

צרו אחד באמצעות mkdir -p .claude/skills/nginx-config-changes וכתבו את הקובץ. Claude Code מנטר ספריות אלו, לכן עריכת Skill קיים נכנסת לתוקף בתוך הסשן הפעיל. אם Skill חדש אינו מופיע, הריצו את /reload-skills.

שדה התיאור הוא השורה בעלת ההשפעה הרבה ביותר בקובץ

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

כתוב את התיאור בגוף שלישי. "בודק וטוען מחדש את nginx בצורה בטוחה" עובד. "אני יכול לעזור לך עם nginx" לא עובד, כיוון שהטקסט מוזרק לתוך ה-system prompt, שם גוף ראשון נקרא כאילו המודל מדבר על עצמו.

כלול בתיאור שני דברים: מה המיומנות עושה, והתנאי שבו היא חלה. הצב את מקרה השימוש החשוב ביותר בהתחלה, כיוון ש-Claude Code קוטם את רשומת הרשימה ב-1,536 תווים. קיים שדה אופציונלי בשם when_to_use עבור ביטויי הפעלה נוספים ובקשות לדוגמה, והוא מתווסף לתיאור תחת אותה מגבלה.

לאחר מכן, השתמש במילים שאתה באמת תקליד. description: Helps with nginx לא מתאים לכלום, כי אף אחד לא מקליד "helps with". הגרסה שלעיל מציינת את /etc/nginx, server block, reverse proxy ו-TLS (transport layer security) certificate path, שזה בערך אוצר המילים של כל בקשה שאמורה להפעיל אותה.

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

שמרו על גוף התוכן מצומצם, שכן הוא נשאר בהקשר

כאשר מופעלת מיומנות (skill), התוכן המרונדר שלה נכנס לשיחה כהודעה אחת ונשאר שם למשך שארית הסשן. Claude Code אינו קורא מחדש את הקובץ בתורות מאוחרים יותר. כל שורה שאתם כותבים היא עלות שאתם משלמים עבור כל הסשן, ולא עבור תשובה אחת בלבד.

Anthropic ממליצה לשמור על SKILL.md באורך של פחות מ-500 שורות ולהעביר פרטים לקבצים נפרדים. דחיסה מדגימה מדוע מספר זה אינו שרירותי. כאשר השיחה מסוכמת כדי לפנות הקשר, Claude Code מצרף מחדש את ההפעלה האחרונה ביותר של כל מיומנות, שומר רק את 5,000 הטוקנים הראשונים של כל אחת, וממלא תקציב משולב של 25,000 טוקנים החל מהמיומנות שהופעלה לאחרונה. מיומנות ארוכה עלולה להיקטע באמצע. כמה מיומנויות ארוכות עלולות לדחוק זו את זו החוצה לחלוטין.

לכן, כתבו רק את מה שהמודל עדיין לא יודע. הוא יודע מה זה nginx ומה עושה reverse proxy. הוא לא יודע מהו כלל הבית שלכם לגבי reload לעומת restart, וכלל זה הוא הסיבה היחידה לקיומו של קובץ זה.

אם המיומנות מורה לסוכן להריץ סקריפט ארוז, ציינו את הנתיב עם ${CLAUDE_SKILL_DIR} כך שהוא יתפענח בכל מקום שבו המיומנות מותקנת, ואשרו מראש את אותה פקודה כדי שההרצה לא תיעצר בבקשת הרשאה.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

ההרשאה מכסה את התור שהפעיל את המיומנות ומתנקה כאשר אתם שולחים את ההודעה הבאה שלכם, כך שהיא לא הופכת בשקט להרשאה קבועה.

כיצד לוודא שה־skill מופעל

צפייה בטעינת ה־skill מאשרת שהסוכן מצא אותו. היא אינה מעידה על כך שהתשובה השתנתה. בדקו את שני ההיבטים, ובצעו את הבדיקה בסשן חדש, כיוון שהסשן שבו כתבתם את ה־skill כבר מכיל את כל מה שנאמר במהלך הכתיבה. הקשר (context) שנותר מאחור מסתיר חוסרים בקובץ.

  1. התחילו סשן חדש עם claude בתוך הפרויקט.
  2. הקלידו את הבקשה כפי שהייתם עושים ביום עבודה רגיל, במילים שלכם, מבלי לציין את שם ה־skill.
  3. עקבו אחר ההפעלה. אם ה־skill לא מופעל, תקנו את התיאור. גוף ה־skill אינו הבעיה בשלב זה.
  4. הפעילו אותו ידנית עם /nginx-config-changes כבקרת איכות. התנהגות תקינה בהפעלה ידנית לעומת התנהגות שגויה בהפעלה לפי בקשה מאשרת שמדובר בבעיית טריגר ולא בבעיית הוראות.
  5. הריצו את אותה בקשה כשה־skill כבוי והשוו בין שתי התשובות. בתפריט /skills, סמנו את ה־skill, לחצו על Space כדי להחליף את המצב ל-off, ולאחר מכן על Esc כדי לשמור. פעולה זו כותבת רשומה מסוג skillOverrides לתוך .claude/settings.local.json, ולחיצה נוספת על Space תחזיר את המצב ל-on בסיום.
  6. כתבו מספר בקשות שלא אמורות להפעיל את ה־skill, וודאו שהוא נשאר שקט במקרים אלו.

כדי להפוך את הלולאה הזו לאוטומטית, התקינו את התוסף skill-creator מה-marketplace הרשמי.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

אם פלט ההתקנה מציג Run /reload-plugins to apply., Claude Code מבצע את הטעינה מחדש עבורכם. אם הטעינה מחדש מזהירה שההודעה הבאה שלכם תקרא מחדש את השיחה, הריצו את /reload-plugins --force. לאחר מכן בקשו מ-Claude להעריך את ה־skill שלכם לפי שם. התוסף שומר מקרי בדיקה בתוך evals/evals.json בתיקיית ה־skill ומריץ כל מקרה בסוכן משנה נפרד, כך שכל הרצה מתחילה עם הקשר נקי. לאחר מכן הוא כותב השוואה בין מצב עם ה־skill למצב בלעדיו, וזהו הנתון המהימן: שיפור אחוזי ההצלחה שנמדד מול ה-tokens והזמן שה־skill צורך.

ל־skill יכולה להיות גם הוכחה עצמית במקום להסתמך על הרצת הערכה נפרדת, וזה מה שה־skill שנקרא the Old Coder עושה כאשר הוא גורם לסוכן להחזיר דוח הוכחות שניתן להריץ מחדש בעצמכם.

מצב כשל: ה-skill לעולם לא מופעל

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

  • התיאור מציין מה ה-skill עושה אך לא מציין מתי להשתמש בו, לכן שום דבר בבקשה שלכם לא תואם לו.
  • התיאור נמנע מהמילים שאתם מקלידים. אם אתם אומרים "nginx", התיאור חייב להכיל את המילה nginx.
  • disable-model-invocation: true מוגדר ב-frontmatter. הגדרה זו מוציאה את התיאור לחלוטין מהקשר (context) של המודל, ומשאירה את ה-skill זמין להפעלה רק על ידכם באמצעות /name.
  • תבנית (glob) של paths ב-frontmatter מגבילה את ההפעלה לקבצים תואמים בלבד, והקובץ שאתם עובדים עליו אינו תואם.
  • ה-skill נמצא בתוך ספריית .claude/skills/ מקוננת מתחת לספריית העבודה שלכם. ספריות אלו נטענות רק לאחר שהסוכן קורא או עורך קובץ בתוך תת-הספרייה הזו, או שאתם מוסיפים את תת-הספרייה באמצעות /add-dir; לכן, עד אז ה-skill אינו זמין כלל.

מצב כשל: המיומנות מופעלת ללא הרף

הבעיה ההפוכה היא תיאור רחב מדי, הגורם למיומנות לפעול במשימות שאינן קשורות. "השתמש בעת עבודה על השרת" תואם כמעט לכל בקשה במאגר של שרת. במקרה כזה, גוף המיומנות נטען עבור משימות שאין ביכולתו לסייע בהן, והוא נשאר בהקשר (context) למשך שארית הסשן.

צמצמו את התיאור לתנאי הרלוונטי באמת, וציינו את הקבצים או הפקודות שהיא מכסה. הוסיפו paths glob כאשר המיומנות חלה רק על קבצים מסוימים. עבור כל פעולה בעלת השפעות לוואי (side effects), כגון deploy או commit, הגדירו disable-model-invocation: true והפעילו אותה בעצמכם באמצעות /name. כך הסוכן לעולם לא יחליט על דעת עצמו שהגיע הזמן לבצע deploy.

מצב כשל: המיומנות שייכת לקובץ הכללים שלך

קובץ כללים כגון CLAUDE.md או AGENTS.md נטען בתחילת כל סשן וחלה על כל משימה. גוף של מיומנות (skill) נטען רק כאשר המיומנות מופעלת. תדירות השימוש היא הגורם המכריע. עובדה שתקפה לכל משימה במאגר, כמו מנהל החבילות שבו אתה משתמש, שייכת לקובץ הכללים. נוהל שחל על חלק קטן מהמשימות, כמו כלל ה-nginx לעיל, שייך למיומנות, שם הוא אינו גוזל משאבים בימים שבהם איש אינו עורך את nginx.

הכשל האמיתי הוא הצבת ההוראה בשני המקומות. שני עותקים נוטים להשתנות עם הזמן, וכאשר הסוכן מבצע פעולה שגויה, לא ניתן לדעת באיזה עותק הוא השתמש. בחר בית אחד לכל הוראה. כלל שכבר נמצא בבית אחד בלבד ועדיין מתעלמים ממנו הוא בעיה מסוג אחר, וכדאי לבדוק את המנגנונים שמאחורי הוראה שמתעלמים ממנה לפני שמעבירים אותו למיומנות בתקווה שההעברה תפתור את הבעיה. המדריך הגבול בין מיומנויות, שרתי MCP וקובצי כללים מפרט את המקרים המורכבים יותר, כולל מצבים שבהם הפתרון הנכון הוא שרת MCP (פרוטוקול הקשר מודל) שמספק לסוכן כלי חדש במקום הוראה חדשה.

שתפו את המיומנות לאחר שהוכיחה את עצמה

מיומנות ששורדת שבוע של עבודה אמיתית ראויה להטמעה. מיומנויות פרויקט ב-.claude/skills/ עוברות סקירה כמו קוד ומגיעות יחד עם ה-repository, כך שחבר צוות שמבצע clone מקבל את התיקון שלכם ללא צורך בשלבי הגדרה נוספים. העברת מיומנות בין repositories ללא העתק-הדבק היא אתגר בפני עצמו, המוסבר ב-כיצד לשתף מיומנויות סוכן בין מאגרים.

הערה בנוגע לניידות: Claude Code מקבל רשימה ארוכה של שדות frontmatter, אך התקן של Agent Skills מאפשר שימוש בשישה בלבד: name, description, license, compatibility, metadata ו-allowed-tools. אם תעלו מיומנות ל-claude.ai, או תארזו אותה עבור ה-Skills API, עם תוכן אחר ב-frontmatter, הפעולה תיכשל לחלוטין במקום להתעלם מהשדה:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

היצמדו לששת השדות הללו, ואותו קובץ ייטען ב-Claude Code ובכל כלי אחר שתומך בתקן. המקום שבו הקובץ נטען עדיין קובע מה הוא יכול לבצע, כיוון ש-Cowork רץ בתוך ארגז חול של Anthropic בעוד Claude Code רץ על המכונה שלכם או על ה-VPS, לכן מיומנות ה-nginx שלעיל כדאית להעברה ל-checkout של חבר צוות, אך חסרת תועלת בארגז חול שאינו יכול להגיע לשרת. כתיבת ההנחיות עצמן כך שישרדו מעבר למודל אחר היא משימה נפרדת, ו-כתיבת מיומנויות שעובדות עם כל מודל מכסה זאת.

FAQ

מה צריך להיות האורך של קובץ SKILL.md?

שמרו על אורך של פחות מ-500 שורות, וצפו לכך שרוב המיומנויות השימושיות יהיו קצרות בהרבה. גוף הקובץ נכנס לשיחה כאשר המיומנות מופעלת ונשאר שם לאורך כל הסשן, לכן כל שורה היא עלות מתמשכת ולא חד-פעמית. העבירו חומר עזר ארוך לקבצים נפרדים בתיקיית המיומנות וקשרו אליהם מתוך SKILL.md, ברמה אחת של עומק, כך שהסוכן יקרא אותם רק בעת הצורך. סקריפטים מצורפים מבוצעים במקום להיקרא, לכן העלות שלהם מסתכמת רק בפלט שלהם.

מדוע המיומנות שלי לא מופעלת לעולם?

התיאור הוא הסיבה הנפוצה לכך, כיוון שהוא החלק היחיד מהמיומנות שנמצא בהקשר כאשר המודל מקבל החלטה. ודאו שהתיאור מציין מתי להשתמש במיומנות, לא רק מה היא עושה, ושהוא מכיל את המילים שאתם מקלידים בפועל בבקשות שלכם. אם התיאור נראה תקין, בדקו ב-frontmatter את disable-model-invocation: true, שמסתיר את המיומנות מהמודל לחלוטין, ואת ה-glob ב-paths שמגביל אותה לקבצים שאינכם נוגעים בהם. מיומנות בתיקייה מקוננת .claude/skills/ מתחת לתיקיית ההתחלה שלכם היא סיבה נוספת: היא נטענת רק לאחר שהסוכן קורא או עורך קובץ באותה תת-תיקייה, או שאתם מוסיפים את תת-התיקייה באמצעות /add-dir.

האם זה צריך להיות מיומנות או שורה בקובץ הכללים שלי?

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

איך אדע שמיומנות באמת עזרה?

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

האם אני יכול להשתמש באותו SKILL.md עם סוכן אחר?

כן, כל עוד אתם נשארים בתוך השדות שהתקן Agent Skills מגדיר: name, description, license, compatibility, metadata ו-allowed-tools. Claude Code מקבל שדות רבים נוספים, והוא גם תומך בתכונות גוף כגון הזרקת פקודות shell שכלים אחרים אינם מריצים. העלאת מיומנות עם שדה מחוץ לתקן תיכשל עם שגיאה מפורשת המפרטת את המאפיינים המותרים, לכן החליטו מראש אם מיומנות נועדה להישאר ב-Claude Code או להיות ניידת.

האם המאמר הזה היה מועיל?