הרחבת המפרט (metadata.json + תוכן דו־לשוני)

הפרק הזה מציג דפוס הרחבה אחד נפוץ: קבצי הלוויין metadata.json ו־SKILL_HE.md של קטלוג skills-il הציבורי. קטלוגים אחרים עושים את זה אחרת. הלקח הוא הדפוס, לא המפתחות הספציפיים. אם הסקיל שלכם פרטי לגמרי, אפשר לדלג על הפרק הזה לחלוטין.

למה metadata.json ולא YAML מקונן

ה־YAML parser המחמיר של Claude Desktop דחה את המפתח המקונן metadata: ש־skills-il השתמש בו במקור בתוך frontmatter של SKILL.md, וסירב לטעון את הסקיל בכלל. הפתרון היה למשוך את כל מה ש־skills-il צריך לתוך קובץ נפרד בשם metadata.json ליד SKILL.md. עכשיו Claude Desktop (שקורא רק את ה־frontmatter של SKILL.md) טוען נקי, וצינור הקטלוג של skills-il (שקורא את metadata.json) מקבל את המידע הדו־לשוני וקטלוגי שהוא צריך. ה־frontmatter נשאר מינימלי: name, description, license, וזהו.

שדות metadata.json

{
  "name": "israeli-id-validator",
  "version": "1.2.0",
  "license": "MIT",
  "display_name": {
    "he": "מאמת תעודת זהות",
    "en": "Israeli ID Validator"
  },
  "display_description": {
    "he": "אמתו תעודת זהות ישראלית בעזרת אלגוריתם ספרת הביקורת. שמיש לטפסים, נתוני בדיקה, וזיהוי תעודות לא תקינות לפני שליחה.",
    "en": "Validate Israeli national ID numbers using the check-digit algorithm. Useful for forms, test data, and catching bad IDs before submission."
  },
  "audience": "developers",
  "level": "beginner",
  "tags": {
    "he": ["תעודת זהות", "אימות", "ישראל"],
    "en": ["israeli-id", "validation", "checksum"]
  },
  "supported_agents": ["claude-code", "cursor", "windsurf", "claude-desktop"]
}

• display_name הוא הכותרת הדו־לשונית שמוצגת ב־UI של הקטלוג. עברית קודם.
• display_description הוא הקופי השיווקי הדו־לשוני. הגרסה העברית חייבת להישמע כמו עברית טבעית, לא כמו תרגום (פרק 6 מרחיב).
• audience הוא אחד מ: developers, non-technical, professionals, mixed. קובע את הפילטר בקטלוג ואת רגיסטר הכתיבה הדיפולטי.
• level הוא אחד מ: beginner, intermediate, advanced.
• tags חייב לכלול מערכים מקבילים בעברית ובאנגלית. הקטלוג מסנן לפי התגיות באנגלית. המערך בעברית הוא לתצוגה ב־UI העברי.
• supported_agents חייב להשתמש ב־slug קנוני: claude-code (לא claude), gemini-cli (לא gemini), cursor, windsurf, claude-desktop. slug שגוי מציג עיגול אייקון אפור ריק בכרטיס הסקיל (אין ולידציה על זה בזמן sync, תבדקו את הכרטיס שלכם ב־dev לפני push).

SKILL_HE.md: קובץ הליווי בעברית

כל סקיל ב־skills-il שולח תרגום לעברית בשם SKILL_HE.md ליד SKILL.md. שני הקבצים חולקים את אותה צורת YAML frontmatter (עם טקסט תיאור בעברית), אותו מבנה גוף (כותרות פרקים מתורגמות), ואותן הפניות לתמונות.

הטבעיות של העברית היא ההבדל האיכותי הכי גדול בין הסקילים עם הכי הרבה התקנות לבין הזנב הארוך. הטעות הכי נפוצה כאן היא לכתוב SKILL.md, להעביר אותו בתרגום LLM, להדביק את הפלט לתוך SKILL_HE.md, ולשלוח. התוצאה נקראת כמו אנגלית בתעתיק: סדר המילים שגוי, קלקות בכל מקום ("שכבת האסטרטגיה" ל־"the strategy layer", "שתי שאלות עוגן" ל־"two anchor questions"), ויש אי־הסכמות במין ("זו לא ייעוץ" צריך להיות "זה לא ייעוץ"). קוראים ישראלים מזהים את זה מיד.

הפתרון: אחרי הטיוטה הראשונה שה־LLM הפיק, שדובר עברית ילידי (או pass עריכה ייעודי) יעבור על הטקסט לטבעיות. תסתכלו על הסגנון של ערכי "כל זכות" בשפה פשוטה, על הסברי TheMarker, או על בלוגים ישראליים פופולריים בתחום שלכם.

הפניה לסקילים אחרים בפרוזה עברית

כשהגוף של SKILL_HE.md שלכם צריך להפנות לסקיל אחר (למשל כדי להמליץ על סקיל קשור שהמשתמש אולי ירצה), השתמשו בשם התצוגה העברי ואחריו ה־slug בסוגריים, ולא ב־slug החשוף ב־kebab-case בתוך backticks. דוגמה:

• לא נכון (עברית): התקינו את הסקיל israeli-pension-advisor
• נכון (עברית): התקינו את הסקיל יועץ פנסיה ישראלי (israeli-pension-advisor)

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

דוגמה ללימוד: hebrew-seo-geo-toolkit

התקינו את ערכת SEO ו־GEO בעברית (hebrew-seo-geo-toolkit) דרך npx skills-il add marketing-growth/hebrew-seo-geo-toolkit והשוו בין SKILL.md, SKILL_HE.md ו־metadata.json שלו. זה סקיל דו־לשוני עם הרבה התקנות (220+) שעבר איטרציה לפי פידבק מהמשתמשים. התיאור בעברית נקרא טבעי, התגיות מקבילות כמו שצריך, והגוף מכסה דאגות SEO ו־GEO ספציפיות לישראל שאף כלי SEO גנרי לא היה מטפל בהן. זה הרפרנס ל"איך סקיל דו־לשוני באיכות גבוהה נראה".

הטעות הכי נפוצה בפרק 3: תרגום מילולי מאנגלית לעברית שנקרא שבור לקוראים ישראלים. הפתרון: לכתוב את SKILL_HE.md כאילו הוא המקור, לא התרגום. חשיבה Hebrew first מפיקה סקילים יותר טובים בצורה דרמטית.