רשימת תיוג של 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 מטפלים יותר טוב ב־state חי, קל יותר להחזיק אותם מעודכנים, ומשתלבים באופן טבעי עם סקילים שמטפלים בקבלת ההחלטות.

חלוקה נקייה:

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

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

בסיס אבטחה

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

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

• אף פעם אל תכניסו secrets. SKILL.md, metadata.json, וכל מה שב־references/ וב־scripts/ מופץ כמו שהוא. מפתחות API, מחרוזות חיבור ל־DB, טוקנים אישיים שייכים לסביבה של המשתמש (env vars, keychain של מערכת ההפעלה), לא לתיקיית הסקיל. אם הסקריפט שלכם צריך מפתח API, תתעדו את שם משתנה הסביבה בגוף ותנו למשתמש להגדיר אותו אצלו.
• תהיו זהירים עם מה ש־scripts/ עושה. הסוכן יקרא לסקריפטים שלכם כשהגוף יגיד לו. סקריפט שעושה rm -rf או קריאת רשת עם נתוני משתמש עושה את זה על המכונה של המשתמש ובהרשאות שלו. תגבילו את הסקריפטים לחישוב דטרמיניסטי, parsing, וקריאות רשת מתועדות במפורש.
• תתייחסו ל־references/ כחלק מה־prompt. כל דבר שה־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 טובים היא לקרוא קומץ סקילים שמפתחים אחרים פרסמו. חלק מהקטלוגים הציבוריים נותנים לדפדף לפי מספר התקנות, וזה proxy גס ל"הסקיל הזה מעוצב טוב מספיק כדי שאנשים באמת ישתמשו בו". לסקילים בקונטקסט ישראלי, agentskills.co.il הוא קטלוג כזה. לנישות אחרות, מצאו את הקטלוג הקהילתי שמתאים.

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

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

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