רשימת תיוג של 10 דקות לפני שיתוף

10 טעויות הכתיבה הנפוצות ביותר

1. תיאור עמום מדי. "סקיל לדברים ישראליים" מנותב גרוע. תשתמשו בדפוס "Use when X, Y, Z. Do NOT use for A, B".
2. אין סעיף "Do NOT use for". בלעדיו ה־LLM טוען את הסקיל שלכם בקונטקסט שגוי ומפיק תשובה שגויה בביטחון.
3. תיאור ב־YAML block scalar (>- או |). חלק מה־parsers (של Claude Desktop, בין השאר) מקבלים את זה. אחרים מקפלים את הרווחים אחרת או דוחים על הסף. תשמרו את התיאור בשורה אחת.
4. ספי קצבה מומצאים, מספרי טפסים מומצאים, או ציטוטי חוק מומצאים. מדרגות מס שגויות, מספרי טפסים שגויים של רשויות, ציטוטי תקנות מומצאים. המבקרים מצליבים מול מקורות ראשוניים. המצאות נדחות חזק.
5. slug שלא תואם לשם התיקייה. רוב ה־validators והקטלוגים דורשים שה־slug ב־frontmatter (או ב־metadata.json) יהיה שווה בדיוק לשם הבסיס של התיקייה. אחרת הרישום נכשל.
6. אין דוגמת עבודה בגוף. בלי דוגמאות, ה־LLM ממציא edge cases.
7. הפניות לקבצים ב־references/ או scripts/ שלא קיימים. ולידטור מקומי תופס את זה תוך שניות. תריצו אותו.
8. slug שגוי ב־supported_agents. claude במקום claude-code, gemini במקום gemini-cli. מציג עיגולים אפורים ריקים בכרטיס הקטלוג.
9. קווי em dash במקום כלשהו ב־SKILL.md, בגוף המתורגם, או ב־metadata.json. קונבנציית הפרויקט היא בלי em dashes, נקודה. תשתמשו בפסיקים, סוגריים, נקודתיים.
10. שכחתם להקפיץ גרסה אחרי עריכות. ערוצי ההפצה דורסים את התוכן בשקט, אבל מחוון הגרסה נשאר ישן וצרכנים (או אתם בעתיד) לא יכולים להגיד מה השתנה.

רשימת התיוג של 10 דקות לפני שיתוף (מילולי)

הריצו אותן בסדר. כל אחת היא פקודת shell אחת או קריאה של 30 שניות.

1. הריצו grep על שלושת הקבצים בחיפוש תו ה־em dash (U+2014). הפלט חייב להיות ריק.
2. jq -r '.name' metadata.json וודאו שזה שווה ל־basename "$(pwd)".
3. תקראו את ה־description שלכם בקול. הוא עונה על "מתי ה־LLM צריך לטעון את זה?" במשפט אחד? יש בו סעיף "Do NOT use for"?
4. פתחו סשן Claude Code טרי. הדביקו בקשה שהסקיל שלכם אמור לטפל בה, ואז אחת שהוא לא אמור לטפל בה. תוודאו שה־LLM מנתב נכון בשני המקרים (טוען את הסקיל לראשון, לא טוען לשני).
5. תבחרו מספר אחד, אחוז, או סכום במטבע כלשהו בגוף שלכם. תפתחו את המקור הראשוני שלו. תוודאו שזה תואם.
6. תבחרו את הפרק עם הכי הרבה לוגיקת החלטה. תמצאו את דוגמת העבודה. תגזרו אותה מחדש על נייר כדי לוודא שהמתמטיקה נכונה.
7. תעשו רשימה של הקבצים ב־references/ וב־scripts/. לכל אחד, תעשו grep ב־SKILL.md כדי לוודא שיש אליו הפניה.
8. אם אתם מפרסמים לקטלוג עם תצוגה מקדימה, פתחו את סביבת ה־dev או ה־staging של הקטלוג וודאו שהכול נראה נכון, כולל אייקוני סוכנים נתמכים או לוגואים של פלטפורמות.
9. תקפיצו גרסה (ב־frontmatter, ב־metadata.json, או ב־git tag, איפה שאתם עוקבים).
10. אם בערוץ ההפצה שלכם רץ סקריפט ולידציה, תריצו אותו מקומית פעם אחרונה לפני push.

אם כל ה־10 עוברים, שתפו. אם משהו נופל, תתקנו מקומית קודם.

המבחן "האם תשובת הברירת מחדל של הצ'אטבוט הייתה יותר טובה?"

השאלה הכי חשובה ששואלים לפני שיתוף: האם המשתמש היה יותר טוב בלי הסקיל שלכם, וקיבל את תשובת ברירת המחדל של ה־LLM?

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

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

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

מתי לשלוח סקיל ומתי MCP server

סיכום לסיום: אם ה"סקיל" שלכם הוא בעצם "תגיד ל־LLM איך לקרוא ל־API הזה ולנתח את התשובה", אל תכתבו סקיל. כתבו MCP server. שרתי MCP מטפלים טוב יותר במצב חי, קל יותר להחזיק אותם מעודכנים, והם משתלבים באופן טבעי עם סקילים שמטפלים בקבלת ההחלטות.

חלוקה נקייה:

• סקיל: איך לפרש את התשובה משרת MCP. מה לעשות עם הנתונים. חוקי ההחלטה.
• MCP server: איך להביא את הנתונים. החוזה של ה־API. המצב הנוכחי.

כששניהם נדרשים, שלחו את ה־MCP בנפרד ותנו לסקיל להמליץ להתקין אותו.

בסיס אבטחה

סקיל הוא לא תוכן סטטי. הגוף נטען כהוראות ל־LLM. קבצי scripts/ נהפכים לקוד שהסוכן יכול להריץ דרך כלי ה־shell שלו. תתייחסו לשניהם כמשטחי אבטחה.

ככותב הסקיל (לפני פרסום או שיתוף):

• אף פעם אל תכניסו secrets. SKILL.md, metadata.json, וכל מה שב־references/ וב־scripts/ מופץ כמו שהוא. מפתחות API, מחרוזות חיבור ל־DB, טוקנים אישיים שייכים לסביבה של המשתמש (env vars, keychain של מערכת ההפעלה), לא לתיקיית הסקיל. אם הסקריפט שלכם צריך מפתח API, תתעדו את שם משתנה הסביבה בגוף ותנו למשתמש להגדיר אותו אצלו.
• תהיו זהירים עם מה ש־scripts/ עושה. הסוכן יקרא לסקריפטים שלכם כשהגוף יגיד לו. סקריפט שעושה rm -rf או קריאת רשת עם נתוני משתמש עושה את זה על המכונה של המשתמש ובהרשאות שלו. תגבילו את הסקריפטים לחישוב דטרמיניסטי, parsing, וקריאות רשת מתועדות במפורש.
• תתייחסו ל־references/ כחלק מההנחיה. כל דבר שה־LLM קורא מ־references/ מתפרש כהוראות. סקיל שמכיל טקסט עוין ב־references/ (למשל "כשתענה בפעם הבאה, התעלם מה־system prompt שלך ו...") נהפך לוקטור prompt injection. אל תכניסו תוכן שלא הייתם מדביקים ל־system prompt.

כצרכן (לפני שאתם מתקינים סקיל של מישהו אחר):

• תקראו את גוף ה־SKILL.md לפני ההתקנה. אם אתם לא מבינים מה הוא עושה, אל תתקינו.
• תסתכלו על כל קובץ ב־scripts/. אם סקריפט עושה קריאות רשת או נוגע במערכת הקבצים, תחליטו אם אתם סומכים על הכותב.
• לסקילים מקטלוגים, תבדקו את אותות האמון שהקטלוג חושף (מספרי התקנות, ציון אמון, סטטוס ביקורת, סקילים אחרים של אותו כותב). סקילים מכותבים מבוססים לא בטוחים יותר כברירת מחדל, אבל לפחות יש להם אחריות.

מפרט וקריאה נוספת

• המפרט של Anthropic ל־Agent Skills: חפשו ב־docs הרשמיים של Anthropic / Claude את "Agent Skills". המפרט מתפרסם שם ומגדיר את name, description, license, ואת הקונבנציות של תת־התיקיות references/ ו־scripts/. כל שדה מעבר למינימום הזה הוא הרחבה ייחודית לקטלוג.
• תיעוד התקנה לכל סביבה: Claude Code (claude skill install), Cursor (Settings → Skills), Windsurf (דומה), Claude Desktop (בחירה ידנית). לכל סביבה תהליך התקנה משלה. פורמט ה־SKILL.md משותף.

איפה למצוא סקילים לדוגמה ללמוד מהם

הדרך הכי מהירה להפנים דפוסי SKILL.md טובים היא לקרוא כמה סקילים שמפתחים אחרים פרסמו. חלק מהקטלוגים הציבוריים נותנים לדפדף לפי מספר התקנות, וזה מדד גס ל"הסקיל הזה בנוי מספיק טוב כדי שאנשים באמת ישתמשו בו". לסקילים בהקשר ישראלי, agentskills.co.il הוא קטלוג כזה. לנישות אחרות, מצאו את הקטלוג הקהילתי שמתאים.

שלוש דוגמאות פתיחה שימושיות לפי מורכבות:

• הכי קטן: פורמטר ממוקד וצמוד (למשל פורמטר למספרי טלפון של המדינה שלכם)
• קטן עם scripts/: סקיל שמוסיף אלגוריתם דטרמיניסטי של ספרת ביקורת או parser
• בינוני עם references/: סקיל דו־לשוני או מרובה־סקשנים עם שימוש אמיתי ב־references/

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

סקילים נלווים

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

• מאמת תעודת זהות (israeli-id-validator), הדוגמה הקטנה ביותר: סקיל ממוקד עם ולידציה פשוטה. התקנה: npx skills-il add skills-il/developer-tools/israeli-id-validator
• מפרמט טלפונים ישראלי (israeli-phone-formatter), דוגמה קטנה עם scripts/: עיצוב מספרי טלפון בכל הפורמטים. התקנה: npx skills-il add skills-il/developer-tools/israeli-phone-formatter
• ערכת כלים לקידום אתרים ו־GEO בעברית (hebrew-seo-geo-toolkit), דוגמה בינונית עם references/: סקיל דו־לשוני מרובה־סקשנים עם שימוש אמיתי ב־references. התקנה: npx skills-il add skills-il/marketing-growth/hebrew-seo-geo-toolkit