הפרק הזה מציג דפוס הרחבה אחד נפוץ: קובץ 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 מחדש בזמן ההגשה.