הסוכן לא מקשיב להנחיות הסקיל? למה קודקס (Codex) סוטה מהוראות ואיך מחזקים אותן

Codex לא קורא את הסקיל שלכם מראש. בתחילת העבודה הוא רואה רק את השם ואת התיאור של כל סקיל, וטוען את ההנחיות המלאות רק כשהוא מחליט שהמשימה מתאימה להן. לכן כשהסקיל יושב בתיקייה ש-Codex לא סורק, כשהתיאור שלו עמום, או כשנכתב בו כלל קשיח שהיה צריך לשבת ב-AGENTS.md, הסוכן "סוטה". מה שמחזק את הציות: לשים את הסקיל בנתיב הנכון, לכתוב תיאור שאומר בדיוק מתי להפעיל אותו, להפעיל אותו במפורש עם $ במשימות קריטיות, ולהעביר את הכללים שאסור לשבור ל-AGENTS.md.

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

איך קודקס (Codex) מחליט אם להשתמש בסקיל

לפי התיעוד הרשמי של OpenAI על בניית סקילים (נבדק ב-2026-10-15), סקיל הוא תיקייה עם קובץ SKILL.md. בראש הקובץ חייבים להופיע שני שדות: name ו-description. סקילים יכולים להיטען בשתי דרכים:

• הפעלה מפורשת: ב-Codex CLI או בתוסף ל-IDE מקלידים $ או מריצים /skills, ובוחרים את הסקיל.
• הפעלה מרומזת: Codex בוחר את הסקיל בעצמו, כשהמשימה תואמת את התיאור שלו.

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

ויש גם מגבלת מקום. לפי אותו עמוד תיעוד (נבדק ב-2026-10-15), הרשימה הראשונית תופסת לכל היותר 2% מחלון ההקשר, או 8,000 תווים כשגודל החלון לא ידוע. כשיש הרבה סקילים, Codex מקצר קודם כול את התיאורים, ועלול להשמיט סקילים מהרשימה לגמרי. ההגדרה skills.max_context_tokens מגדילה את התקציב עד 10,000 טוקנים.

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

חמש סיבות שהסוכן "סוטה" מהסקיל

1. הסקיל לא נמצא בנתיב ש-Codex סורק

Codex טוען סקילים מקומיים רק מהמקומות האלה (לפי התיעוד, נבדק ב-2026-10-15):

קובץ SKILL.md בתיקייה כמו "המסמכים שלי/סקילים" הוא בשביל Codex מסמך רגיל. הוא יכול לקרוא אותו אם תבקשו, אבל הוא לא יופיע ברשימת הסקילים ולא יופעל לבד. Codex כן עוקב אחרי קיצורי דרך (symlinks), כך שאפשר להשאיר את הסקיל במקומו ולקשר אליו מהנתיב הנכון.

2. התיאור לא תואם את הניסוח של הבקשות שלכם

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

3. יותר מדי סקילים

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

4. הוראות סותרות

לפי התיעוד של AGENTS.md (נבדק ב-2026-10-15), Codex משרשר את קובצי ההנחיות משורש הפרויקט ועד התיקייה הנוכחית, וקובץ קרוב יותר גובר על מוקדם ממנו. אם AGENTS.md אומר דבר אחד והסקיל אומר דבר אחר, יצרתם בעצמכם את ה"סטייה". אותו דבר כשהבקשה בשיחה סותרת את הסקיל: בפועל אין לכם שליטה על הוראה מבין השתיים שתגבר.

5. ערכתם באמצע סשן

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

איך מחזקים את ההנחיות: שבעה צעדים

1. העבירו את הסקיל לנתיב הנכון. לסקיל של פרויקט: .agents/skills/<שם-הסקיל>/SKILL.md בתוך הריפו. לסקיל אישי שעובד בכל הפרויקטים: $HOME/.agents/skills. אחר כך הקלידו $ ובדקו שהסקיל מופיע ברשימה.

2. כתבו את התיאור מחדש: מתי כן ומתי לא. התבנית שהתיעוד מציג היא "Explain exactly when this skill should and should not trigger". בפועל זה נראה כך:

   ---
   name: release-notes
   description: הפעל בכל בקשה לכתוב או לעדכן הערות גרסה, changelog או סיכום שינויים לפני שחרור. לא להפעיל לתיעוד API או ל-README.
   ---
   

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

3. במשימות קריטיות, הפעילו במפורש. $release-notes בתחילת הבקשה מבטל את ההימור. הסוכן לא צריך להחליט אם הסקיל רלוונטי, כי אמרתם לו.

4. העבירו כללים קשיחים ל-AGENTS.md. AGENTS.md נקרא בכל ריצה. הסקיל נקרא רק כשהוא נבחר. כלל שאסור לשבור לא יכול להיות תלוי בבחירה:

   # כללים קבועים
   - אסור לדחוף ישירות ל-main. כל שינוי בענף נפרד.
   - לפני שמסיימים משימה: להריץ npm test ולדווח על התוצאה.
   - בכל בקשה להערות גרסה: להשתמש בסקיל $release-notes.
   

   השורה האחרונה היא החשובה ביותר: AGENTS.md יכול להפנות לסקיל, וכך גם ההפעלה המרומזת מקבלת גיבוי. הקובץ הגלובלי יושב ב-~/.codex/AGENTS.md, ובכל תיקייה בפרויקט אפשר להוסיף קובץ משלה. שימו לב למגבלה: Codex מפסיק להוסיף קבצים כשהתוכן המשותף מגיע ל-32 KiB (ברירת המחדל של project_doc_max_bytes, לפי התיעוד, נבדק ב-2026-10-15).

5. צמצמו את מספר הסקילים שמתחרים זה בזה. סקיל שאתם מפעילים רק ביד לא צריך להתחרות על המקום. בקובץ agents/openai.yaml שבתיקיית הסקיל מגדירים תחת policy את allow_implicit_invocation: false, והפעלה מפורשת עם $ ממשיכה לעבוד. סקיל שלא בשימוש בכלל מכבים ב-~/.codex/config.toml עם רשומת [[skills.config]] ו-enabled = false, ומפעילים את Codex מחדש.

6. העבירו בדיקות לסקריפט. לסקיל יכולה להיות תיקיית scripts/. הנחיה כמו "ודא שכל קובץ מתחיל בכותרת רישיון" היא בקשה לסוכן. סקריפט שבודק את זה ונכשל אם לא היא עובדה. כל מה שאפשר לבדוק בקוד, עדיף שייבדק בקוד ולא ייזכר על ידי המודל.

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

איפה לשים כל הוראה

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

איך בודקים שזה באמת עובד

התיעוד של OpenAI מציע שלוש בדיקות, ושווה להריץ את כולן אחרי כל שינוי:

1. בקשו מהסוכן לסכם את ההנחיות שלו. מפעילים את Codex מתיקיית השורש של הפרויקט ושואלים מה ההנחיות שקיבל. הוא אמור לפרט את ההנחיות הגלובליות ואת הנחיות הפרויקט לפי סדר הקדימות. אם הכלל שלכם לא מופיע, הוא לא נטען.
2. בדקו את היומן. הפעלה עם codex -c log_dir=... יוצרת יומן טקסט שבו אפשר לראות אילו קבצים נטענו בפועל. כדי לבדוק תיקיית משנה, משתמשים ב---cd.
3. בדקו את התיאור מול בקשות אמיתיות. התיעוד ממליץ להריץ בקשות לדוגמה ולוודא שהסקיל הנכון מופעל. כתבו חמש בקשות כמו שאתם באמת מנסחים אותן, ובדקו כמה מהן הפעילו את הסקיל בלי $.

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

ומה זה אומר למי שעובד עם כמה סוכנים

סקילים בנויים לפי תקן פתוח של סקילים לסוכנים, ולכן ההיגיון כאן דומה מאוד למה שקורה בקלוד. מי שכבר בנה סקילים בקלוד (Claude Skills) יזהה את אותה בעיה בדיוק: תיאור חלש הוא סקיל שלא נטען. ומי שמריץ את Claude Code ו-Codex על אותו פרויקט, כמו במדריך להרצה במקביל עם Git Worktrees, צריך להקפיד שהכללים הקבועים יהיו מנוסחים אותו דבר אצל שני הסוכנים, כדי שלא יעבדו לפי שני ספרי חוקים שונים.

שורה תחתונה

חזרה לשאלה מהקבוצה. הסוכן לא "סוטה" מההנחיות. ברוב המקרים הוא פשוט לא קרא אותן, כי לא ידע שהן קיימות או לא חשב שהן רלוונטיות למשימה. סקיל הוא הצעה שהסוכן רשאי לקבל, AGENTS.md הוא כלל שהוא קורא בכל ריצה, וסקריפט הוא בדיקה שלא תלויה באף אחד מהם.

שלושה דברים לעשות כבר היום: להעביר את הסקיל ל-.agents/skills, לכתוב מחדש את התיאור עם "מתי כן ומתי לא", ולהעביר את שלושת הכללים החשובים ביותר ל-AGENTS.md.

מי שרוצה לעבור על זה בצורה מסודרת, כולל איך מנסחים משימה לסוכן ואיך בודקים את מה שחזר, יכול להיעזר בקורס קודקס (OpenAI Codex) 2026: למסור משימות לסוכן, ולבדוק מה חזר, ב-9.90 שקלים. להיכרות רחבה יותר עם הסביבה, יש גם מדריך ChatGPT Work ו-Codex בעברית.

מקורות

• OpenAI: בניית סקילים (Build skills) (נבדק ב-2026-10-15)
• OpenAI: הגדרת הסוכן עם AGENTS.md (נבדק ב-2026-10-15)