הפרק הזה מציג דפוס הרחבה אחד נפוץ: קובץ metadata.json בתור sidecar ליד SKILL.md. השדות הספציפיים למטה הם הקונבנציות של קטלוג ציבורי אחד (agentskills.co.il) ושימושיים כדוגמת עבודה. קטלוגים אחרים בוחרים שדות אחרים, וחלק מהם מוותרים על ה־sidecar לגמרי לטובת שדה locale ב־frontmatter או תיקיות לפי קוד שפה. הלקח הוא דפוס ה־SIDECAR, לא הסכמה הספציפית. אם הסקיל שלכם פרטי לגמרי, אפשר לדלג על הפרק הזה לחלוטין.
למה sidecar JSON ולא YAML מקונן
ה־YAML parser המחמיר של Claude Desktop דוחה מפתחות מקוננים בתוך frontmatter של SKILL.md לחלוטין, ומסרב לטעון את הסקיל בכלל. לכן הדפוס המקובל הוא להשאיר את ה־frontmatter של SKILL.md מינימלי (name, description, license, וזהו) ולמשוך את כל המטא־דאטה שספציפית לקטלוג לקובץ נפרד בשם metadata.json ליד SKILL.md. סביבות שקוראות רק את ה־frontmatter של SKILL.md (כמו Claude Desktop) טוענות נקי. כלי הקטלוג שקוראים את metadata.json מקבלים את המידע הקטלוגי שהם צריכים.
דוגמת שדות metadata.json
{
"name": "id-validator",
"version": "1.2.0",
"license": "MIT",
"display_name": "ID Validator",
"display_description": "Validate national ID numbers using a check-digit algorithm. Useful for forms, test data, and catching bad IDs before submission.",
"audience": "developers",
"level": "beginner",
"tags": ["id", "validation", "checksum"],
"supported_agents": ["claude-code", "cursor", "windsurf", "claude-desktop"],
"recommended_skills": ["currency-formatter", "date-validator"]
}
display_name הוא הכותרת בקטלוג.display_description הוא הקופי השיווקי בקטלוג.audience בדרך כלל אחד מ: developers, non-technical, professionals, mixed. קובע את הפילטר בקטלוג ואת רגיסטר הכתיבה הדיפולטי.level בדרך כלל אחד מ: beginner, intermediate, advanced.tags הוא מערך מחרוזות. הקטלוגים מסננים לפי זה.supported_agents משתמש ב־slug קנוני: claude-code (לא claude), gemini-cli (לא gemini), cursor, windsurf, claude-desktop. slug שגוי מציג עיגול אייקון ריק על הכרטיסים ברוב ה־UI של הקטלוגים.recommended_skills הוא מערך של slugs שקטלוגים בדרך כלל מציגים כ"סקילים קשורים" בעמוד הפרטים. תבחרו סקילים שמשתמשים באמת צריכים לצד שלכם, לא קישורים פרסומיים. סקיל לאימות תעודות זהות שממליץ על פורמטר טלפונים זה הגיוני. סקיל לאימות תעודות זהות שממליץ על סקיל שיווק לא קשור זה ספאם.
הערה על קטלוגים רב־לשוניים: חלקם מקבלים אובייקטים { he, en } ל־display_name, display_description ו־tags במקום מחרוזות שטוחות, כדי שהקטלוג יציג קופי שונה לכל שפה. זאת קונבנציה ספציפית לכל קטלוג, לא הצורה הדיפולטית. תבדקו את הסכמה של קטלוג היעד לפני שאתם מניחים אחת מהצורות.
הטעות הכי נפוצה בפרק 3: לנחש את הסכמה של ה־sidecar בקטלוג היעד במקום לקרוא את מדריך התרומה שלו. קטלוגים שונים משתמשים בשמות שדה שונים לאותו מושג (audience מול target_users, tags מול keywords, מחרוזות שטוחות מול אובייקטים {he, en}). תשיגו את הסכמה המדויקת מהקטלוג לפני הכתיבה. אחרת תכתבו את ה־sidecar מחדש בזמן ההגשה.