איך לכתוב מיומנות סוכן (Agent Skill) מותאמת אישית

כתיבת מיומנות סוכן (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 עצמה מציבות זאת במקום הראשון. הריצו את הסוכן על משימות מייצגות ללא מיומנות, תעדו היכן הוא נכשל, ואז כתבו את ההוראות המינימליות שמתקנות את הכשלים הללו. הכשלים הם המפרט, לכן מיומנות שאינכם יכולים לקשר לכשל כזה היא בדרך כלל מיומנות שאף אחד לא היה זקוק לה.

האנטומיה של 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.

• .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 קיים נכנסת לתוקף בתוך הסשן הפעיל. יצירת ספריית 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 שורות ולהעביר פרטים לקבצים נפרדים. דחיסה מדגימה מדוע מספר זה אינו שרירותי. כאשר השיחה מסוכמת כדי לפנות הקשר (context), 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 כבר מכיל את כל מה שנאמר במהלך הכתיבה. ההקשר שנותר מסתיר חוסרים בקובץ.

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

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

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

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

מצב כשל: המיומנות (skill) לעולם אינה מופעלת

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

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

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

הבעיה ההפוכה היא תיאור רחב מדי, הגורם למיומנות לפעול גם במשימות שאינן קשורות. "השתמש בעת עבודה על השרת" תואם כמעט לכל בקשה במאגר (repository) של שרת. כתוצאה מכך, גוף המיומנות נטען במשימות שאין ביכולתו לסייע בהן, והוא נשאר בהקשר (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 מקבל את התיקון שלך ללא צורך בשלבי הגדרה נוספים. העברת מיומנות בין מאגרים ללא העתק-הדבק היא אתגר בפני עצמו, המוסבר ב-כיצד לשתף מיומנויות סוכן בין מאגרים.

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

FAQ

מהו האורך המומלץ לקובץ SKILL.md?

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

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

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

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

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

איך אדע אם מיומנות אכן עזרה?

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

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

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