המדריך המלא לבניית סקיל

מה זה סקיל?

סקיל הוא תיקייה שמכילה:

• SKILL.md (חובה): קובץ ההוראות הראשי, ב-Markdown עם YAML frontmatter
• SKILL_HE.md (חובה ב-Skills IL): גרסה בעברית של ההוראות
• metadata.json (חובה ב-Skills IL): מטא-דאטה דו-לשוני (שם, תיאור, תגיות, קטגוריה)
• scripts/ (אופציונלי): קוד הרצה (Python, Bash, וכו׳)
• references/ (אופציונלי): תיעוד שנטען לפי הצורך
• assets/ (אופציונלי): תבניות, פונטים, אייקונים

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

עקרונות יסוד

חשיפה מדורגת (Progressive Disclosure)

סקילס בנויים בשלוש רמות:

• רמה ראשונה (YAML frontmatter): תמיד נטען ל-system prompt של הסוכן. נותן לסוכן מספיק מידע כדי להחליט מתי להפעיל את הסקיל.
• רמה שנייה (גוף SKILL.md): נטען כשהסוכן מזהה שהסקיל רלוונטי למשימה. מכיל את ההוראות המלאות.
• רמה שלישית (קבצים מקושרים): קבצים נוספים בתיקייה (references/, scripts/) שהסוכן טוען רק כשהוא צריך אותם.

הסבירו את ה"למה"

סקיל טוב לא רק אומר לסוכן מה לעשות, אלא גם למה. כשהסוכן מבין את הסיבה, הוא יכול להתאים את עצמו למצבים שלא חשבתם עליהם מראש. במקום "השתמשו בפורמט DD/MM/YYYY", כתבו "השתמשו בפורמט DD/MM/YYYY כי זה הפורמט המקובל בישראל, ושימוש בפורמט אמריקאי עלול לגרום לטעויות בתאריכים".

סוגי סקילס

יש שני סוגים עיקריים:

• סקילס תהליך (Workflow Skills): רצף שלבים לביצוע משימה. לדוגמה: "איך להגיש דוח מע״מ". הסקילס האלה ניידים מאוד בין סוכנים כי הם מבוססים על טקסט בלבד.
• סקילס יכולת (Capability Skills): מסתמכים על כלים ספציפיים של הסוכן (כמו הרצת Bash, גישה לקבצים, כלי MCP). הסקילס האלה עשויים לעבוד אחרת בין סוכנים, תלוי בכלים הזמינים.

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

הסקיל שלכם לא לבד

סוכן AI יכול לטעון כמה סקילס במקביל. הסקיל שלכם צריך לעבוד טוב לצד סקילס אחרים, בלי להניח שהוא היחיד שרץ.

ניידות

סקילס עובדים בכל סוכני ה-AI הנתמכים: Claude Code, Cursor, GitHub Copilot, Windsurf, OpenCode, Codex, OpenClaw ו-Antigravity. צרו סקיל פעם אחת והוא עובד בכל הפלטפורמות.

כדי למקסם ניידות:

• תארו כוונות, לא כלים - כתבו "בדקו את הקובץ לאיתור שגיאות סינטקס" במקום "הריצו eslint src/"
• ארזו סקריפטים - אם הסקיל דורש פעולות מורכבות, הכניסו אותן לסקריפט בתיקיית scripts/ במקום להניח שלסוכן יש כלי מסוים
• ציינו תלויות בפירוש - אם הסקיל דורש MCP או כלי חיצוני, כתבו את זה ב-compatibility ובהוראות

למדריך מקיף על ניידות בין סוכנים, ראו את מדריך תאימות רב-סוכנית.

דרישות טכניות

מבנה הקבצים

כללים קריטיים

שם SKILL.md:

• חייב להיות בדיוק SKILL.md (case-sensitive)
• שום וריאציה אחרת לא תעבוד (SKILL.MD, skill.md, וכו׳)

שם תיקיית הסקיל:

• השתמשו ב-kebab-case: notion-project-setup
• ללא רווחים: Notion Project Setup
• ללא קווים תחתונים: notion_project_setup
• ללא אותיות גדולות: NotionProjectSetup

בלי README.md בתיקיית הסקיל:

• כל התיעוד נכנס ל-SKILL.md או ל-references/
• כשמפיצים ב-GitHub, צרו README ברמת הריפו בלבד (מחוץ לתיקיית הסקיל)

YAML Frontmatter

על בסיס ה-frontmatter הסוכן מחליט אם להפעיל את הסקיל או לא. חשוב לכתוב אותו נכון.

פורמט מינימלי

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

שדות חובה

name (חובה):

• kebab-case בלבד
• ללא רווחים או אותיות גדולות
• צריך להתאים לשם התיקייה

description (חובה):

• חייב לכלול שני דברים:
  • מה הסקיל עושה
  • מתי להשתמש בו (תנאי הפעלה)
• עד 1024 תווים
• ללא תגיות XML
• כללו ביטויים שמשתמשים אומרים בפועל (trigger phrases)

שדות אופציונליים

• license: MIT, Apache-2.0
• compatibility: דרישות סביבה (עד 500 תווים)

דוגמאות לתיאורים טובים

# טוב - ספציפי ומעשי
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files, asks
  for "design specs" or "design-to-code handoff".

# טוב - כולל trigger phrases
description: Manages Linear project workflows including sprint
  planning, task creation, and status tracking. Use when user
  mentions "sprint", "Linear tasks", or "project planning".

# רע - מעורפל מדי
description: Helps with projects.

# רע - חסרי triggers
description: Creates sophisticated documentation systems.

הגבלות אבטחה

אסור ב-frontmatter:

• תגיות XML (< או >)
• סקילס עם "claude" או "anthropic" בשם (שמורים)

כתיבת הוראות אפקטיביות

מבנה מומלץ

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
**Cause:** [Why it happens]
**Solution:** [How to fix]

שיטות עבודה מומלצות

היו ספציפיים ומעשיים:

# טוב
Run \`python scripts/validate.py --input {filename}\` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# רע
Validate the data before proceeding.

כללו טיפול בשגיאות:

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running
2. Confirm API key is valid
3. Try reconnecting

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

שמרו על SKILL.md ממוקד בהוראות הליבה. תיעוד מפורט? העבירו ל-references/ וקשרו אליו.

שימושים נפוצים

1. יצירת מסמכים ותוצרים

ליצירת תוצרים באיכות אחידה: מסמכים, מצגות, אפליקציות, עיצובים, קוד.

• תבניות סגנון ובראנד מוטמעות
• מבנים קבועים לפלט אחיד
• רשימות בדיקה לפני סיום

2. אוטומציה של תהליכים

לתהליכים שחוזרים על עצמם עם כמה שלבים.

• תהליכים צעד אחרי צעד, עם בדיקה בכל שלב
• תבניות למבנים נפוצים
• שיפור חוזר עד שמגיעים לתוצאה

3. העשרת MCP

כשרוצים להוסיף ידע ותהליכים בנוסף לכלים שה-MCP מספק.

• הרצת כמה קריאות MCP בסדר הנכון
• הוספת ידע מקצועי
• טיפול בשגיאות נפוצות של MCP

איך יודעים שהסקיל עובד טוב?

מספרים

• הסקיל מופעל ב-90% מהבקשות הרלוונטיות
• משלים את העבודה ב-X קריאות כלים
• 0 קריאות API שנכשלות

תחושה

• המשתמש לא צריך לכוון את הסוכן בכל שלב
• התהליך רץ חלק בלי תיקונים
• תוצאות עקביות בין סשנים

דרישות Skills IL

אם אתם רוצים לפרסם את הסקיל ב-Skills IL, יש כמה דרישות נוספות מעבר לסטנדרט הבסיסי.

metadata.json

קובץ חובה שמכיל את המטא-דאטה הדו-לשוני של הסקיל. הוא נפרד מה-frontmatter של SKILL.md כי חלק מהסוכנים (למשל Claude Desktop) לא תומכים בשדות מטא-דאטה בתוך ה-YAML.

{
  "author": "github-username",
  "version": "1.0.0",
  "category": "developer-tools",
  "tags": {
    "he": ["אוטומציה", "כלי פיתוח"],
    "en": ["automation", "dev-tools"]
  },
  "display_name": {
    "he": "שם הסקיל בעברית",
    "en": "Skill Name in English"
  },
  "display_description": {
    "he": "תיאור קצר בעברית",
    "en": "Short description in English"
  },
  "supported_agents": ["claude-code", "cursor", "github-copilot", "windsurf", "opencode", "codex", "openclaw", "antigravity", "gemini-cli"]
}

שדות חובה:

• display_name ו-display_description - בשתי השפות, עברית שנשמעת טבעי (לא תרגום מילולי)
• tags - מערכים באורך זהה בעברית ובאנגלית, בלי ערכים ריקים
• category - ה-slug של הקטגוריה (למשל tax-and-finance, developer-tools)
• supported_agents - רשימת הסוכנים שהסקיל תומך בהם
• author - שם המשתמש ב-GitHub
• version - לפי semver (למשל 1.0.0)

SKILL_HE.md

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

בדיקות אוטומטיות

כל ריפו קטגוריה מריץ validate-skill.sh ב-CI. הבדיקות כוללות:

1. קובץ SKILL.md קיים (case-sensitive)
2. ה-frontmatter תקין עם name ו-description
3. שם ב-kebab-case שתואם לשם התיקייה
4. ה-description מכיל trigger phrase (למשל "Use when", "When user")
5. גוף SKILL.md עד 5,000 מילים
6. אין README.md בתיקיית הסקיל
7. אין "claude" או "anthropic" בשם
8. אין סודות hardcoded
9. metadata.json קיים עם display_name דו-לשוני
10. SKILL_HE.md קיים

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

הגשה לפלטפורמה

אחרי שהסקיל מוכן ועובר את הבדיקות, הגישו אותו לבדיקת אבטחה ופרסום ב-Skills IL. אפשר גם להשתמש ביוצר הסקילס כדי ליצור ולשפר סקילס.