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

מה זה סקיל?

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

• SKILL.md (חובה): הוראות ב-Markdown עם YAML frontmatter
• scripts/ (אופציונלי): קוד הרצה (Python, Bash, וכו')
• references/ (אופציונלי): תיעוד שנטען לפי הצורך
• assets/ (אופציונלי): תבניות, פונטים, אייקונים

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

עקרונות יסוד

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

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

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

עבודה משולבת

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

ניידות

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

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

מבנה הקבצים

your-skill-name/
├── SKILL.md              # חובה - קובץ הסקיל הראשי
├── scripts/              # אופציונלי - קוד הרצה
│   ├── process_data.py
│   └── validate.sh
├── references/           # אופציונלי - תיעוד
│   ├── api-guide.md
│   └── examples/
└── assets/               # אופציונלי - תבניות
    └── report-template.md

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

שם SKILL.md:

• חייב להיות בדיוק SKILL.md (רגיש לאותיות גדולות/קטנות)
• אין וריאציות מקובלות (SKILL.MD, skill.md, וכו')

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

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

ללא README.md:

• אל תכללו 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
• כללו ביטויים ספציפיים שמשתמשים עשויים להגיד

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

• license: MIT, Apache-2.0
• compatibility: דרישות סביבה (עד 500 תווים)
• metadata: שדות מותאמים אישית (author, version, mcp-server)

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

# טוב - ספציפי ומעשי
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. אפשר גם להשתמש ביוצר הסקילס כדי ליצור ולשפר סקילס.