references/ מול scripts/ (מתי להשתמש במה)

references/: קבצים סטטיים שה־LLM קורא לפי דרישה

references/ מחזיק קבצים שה־LLM יכול לקרוא כשהוא צריך אותם: הסברים ב־Markdown, טבלאות lookup ב־JSON, נתוני דוגמה, קבצי template, מפרטי תמונות. ה־LLM קורא את אלה דרך כלי קריאת קבצים. הוא לא מריץ אותם.

שימושים טיפוסיים:

• טבלאות lookup: מערך של קידומות אזור ישראליות ממופות לערים, שמור כ־JSON, נקרא כשה־LLM צריך לזהות את מקור מספר טלפון
• תוכן רפרנס ארוך: הסבר בן 2000 מילים על תהליך הגשת מס בישראל, שנשאר מחוץ ל־SKILL.md (שצריך להישאר קצר וממוקד ניתוב) ונמשך פנימה רק כשה־LLM נתקל בשאלה ספציפית
• Templates: חוזי דוגמה, טפסי דוגמה, boilerplate שה־LLM מתאים אישית למשתמש
• מפרטי תמונות: prompts ליצירת איורים, שמורים בנפרד מהגוף

ערך טוב ב־references/ הוא משהו שה־LLM צריך רק לפעמים, ובמקרה שלו טעינה לקונטקסט מראש תבזבז tokens.

scripts/: קוד הרצה שה־LLM יכול להריץ

scripts/ מחזיק קוד שהסוכן יכול להריץ: validators, parsers, חישובים דטרמיניסטיים, קריאות רשת. הסוכן מפעיל סקריפטים דרך כלי ה־shell של הסביבה (Bash ב־Claude Code, המקבילה בסביבות אחרות), קורא stdout/stderr, ומשלב את הפלט המפורסר בתשובה שלו. אין מנגנון "function-call" מובנה לסקריפטים במפרט של Skills. סקריפטים הם executables רגילים שהסוכן מריץ וקורא.

שימושים טיפוסיים:

• חישוב דטרמיניסטי שה־LLM לא צריך לעשות מחדש: אלגוריתם ספרת ביקורת Luhn לתעודות זהות ישראליות (ה־LLM היה גוזר אותו מחדש בצורה לא עקבית אחרת)
• Parsers: פונקציה שלוקחת טקסט גולמי של תלוש משכורת ישראלי ומחזירה פירוט מובנה ב־JSON
• חיפושים חיצוניים שדורשים API key: פונקציה שקוראת ל־API ממשלתי כדי לחפש פרטי רישום עסק
• קריאות רשת: scraping של טבלה ציבורית, קריאה ל־RSS feed

סקריפטים חייבים להיות עצמאיים (להגדיר את כל התלויות בכותרת הסקריפט), לכלול הערת שימוש ברורה בראש, ולכתוב ל־stdout בפורמט צפוי שה־LLM יכול לפרסר.

עץ ההחלטה

כשיש לכם תוכן שתומך בסקיל, שאלו:

1. האם זה חישוב דטרמיניסטי שה־LLM עלול לגזור מחדש שגוי? ← scripts/
2. האם זה דורש API key, קריאת רשת, או כתיבה למערכת קבצים? ← scripts/
3. האם זה lookup סטטי, template, או הסבר ארוך שה־LLM צריך רק לפעמים? ← references/
4. האם זה חוק או דוגמה קצרה ורלוונטית תמיד? ← inline בגוף SKILL.md
5. האם זה חוק ארוך ורלוונטי תמיד שה־LLM חייב לדעת תמיד? ← כנראה לא צריך להיות בסקיל. תשקלו system prompt או סקיל אחר שיכסה את זה

גודל קובץ ומבנה

תשמרו על קבצי references/ מתחת ל־5000 מילים כל אחד (~20KB). אם צריך יותר, פצלו לכמה קבצים ותנו ל־LLM לבחור את הנכון. קבצי scripts/ צריכים להיות עצמאיים: סקריפט בודד מתחת ל־~200 שורות קל לתחזוקה. כל דבר גדול יותר כנראה צריך להתפצל או להפוך לחבילה אמיתית.

תימנעו מ:

• הדבקה של טבלת lookup בת 50 שורות לתוך הגוף של SKILL.md. תעבירו את זה ל־references/<table-name>.json ותפנו אליו מהגוף ("ראו references/area-codes.json").
• כתיבה של סקריפט Python בתוך הגוף של SKILL.md כקטע קוד. תעבירו את זה ל־scripts/<name>.py ותפנו אליו.
• שמירה של קבצים בינאריים (PNG, ZIP) ב־references/, אלא אם הם נתוני דוגמה שה־LLM מפרסר אותם ספציפית. תמונות קטלוג חיות במונורפו של האתר, לא בתיקיית הסקיל.

דוגמה ללימוד: ה־scripts/ של israeli-id-validator

הסקיל מאמת תעודת זהות (israeli-id-validator), שמותקן דרך npx skills-il add developer-tools/israeli-id-validator, שולח קובץ TypeScript קטן ב־scripts/ שמיישם את אלגוריתם ספרת הביקורת Luhn לתעודות זהות ישראליות. הגוף של SKILL.md מתאר מתי להשתמש באלגוריתם. המתמטיקה הדטרמיניסטית עצמה יושבת בסקריפט. זאת הדוגמה הקלאסית ל"חישוב דטרמיניסטי שייך ל־scripts/".

לדוגמה משלימה, התקינו את מפרמט טלפון ישראלי (israeli-phone-formatter) דרך npx skills-il add developer-tools/israeli-phone-formatter ותראו איך הוא משתמש ב־references/ כדי לשמור את טבלת ה־lookup של קידומות ישראליות (סלולרי, קווי, שירותים מיוחדים) בלי להדביק אותן לגוף.

הטעות הכי נפוצה בפרק 4: הדבקת טבלת lookup ארוכה לתוך הגוף של SKILL.md במקום ל־references/. סימפטום: הגוף הוא 80 אחוז טבלה ו־20 אחוז חוקי החלטה אמיתיים. פתרון: תעבירו את הטבלה לקובץ JSON ב־references/ ותפנו אליו מהגוף. ניצול ה־tokens משתפר, והגוף חוזר להיות קריא כלוגיקת החלטה.