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

לדוגמה עבודה של זיקוק כזה, 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), זמין בכל מקום שבו התוסף מופעל.

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

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

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

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

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

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

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

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

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

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