בניית מיומנויות

מדריך זה מלווה אתכם ביצירת מיומנות Triggerfish מאפס -- מכתיבת קובץ SKILL.md ועד בדיקה וקבלת אישור.

מה תבנו

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

אנטומיה של מיומנות

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

my-skill/
  SKILL.md           # נדרש: frontmatter + הוראות
  template.md        # אופציונלי: תבניות שהמיומנות מפנה אליהן
  helper.ts          # אופציונלי: קוד תמיכה

לקובץ SKILL.md יש שני חלקים:

1. YAML frontmatter (בין מפרידי ---) -- מטא-נתונים על המיומנות
2. גוף markdown -- ההוראות שהסוכן קורא

שלב 1: כתיבת ה-Frontmatter

ה-frontmatter מצהיר מה המיומנות עושה, מה היא צריכה, ואילו מגבלות אבטחה חלות.

---
name: github-triage
description: >
  Triage GitHub notifications and issues. Categorize by priority,
  summarize new issues, and flag PRs needing review.
classification_ceiling: CONFIDENTIAL
requires_tools:
  - exec
network_domains:
  - api.github.com
---

שדות נדרשים

שדה	תיאור	דוגמה
name	מזהה ייחודי. אותיות קטנות, מקפים למרחבים.	github-triage
description	מה המיומנות עושה ומתי להשתמש בה. 1-3 משפטים.	ראו לעיל

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

שדה	תיאור	ברירת מחדל
classification_ceiling	רמת רגישות נתונים מקסימלית	PUBLIC
requires_tools	כלים שהמיומנות צריכה גישה אליהם	[]
network_domains	דומיינים חיצוניים שהמיומנות ניגשת אליהם	[]

שדות נוספים כמו version, category, tags ו-triggers ניתנים להוספה לתיעוד ושימוש עתידי. טוען המיומנויות מתעלם בשקט משדות שאינו מזהה.

בחירת תקרת סיווג

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

רמה	מתי להשתמש	דוגמאות
PUBLIC	משתמשים רק בנתונים זמינים לציבור	חיפוש רשת, תיעוד API ציבורי, מזג אוויר
INTERNAL	עובדים עם נתוני פרויקט פנימיים	ניתוח קוד, סקירת תצורה, תיעוד פנימי
CONFIDENTIAL	מטפלים בנתונים אישיים או פרטיים	סיכום דוא"ל, התראות GitHub, שאילתות CRM
RESTRICTED	ניגשים לנתונים רגישים ביותר	ניהול מפתחות, ביקורות אבטחה, תאימות

אם תקרת המיומנות שלכם עולה על התקרה המוגדרת של המשתמש,

ה-API של כתיבת המיומנויות ידחה אותה. השתמשו תמיד ברמה המינימלית הנדרשת. :::

שלב 2: כתיבת ההוראות

גוף ה-markdown הוא מה שהסוכן קורא כדי ללמוד כיצד לבצע את המיומנות. הפכו אותו לפעיל וספציפי.

תבנית מבנה

# שם המיומנות

משפט מטרה בשורה אחת.

## מתי להשתמש

- תנאי 1 (משתמש מבקש X)
- תנאי 2 (מופעל על ידי cron)
- תנאי 3 (מילת מפתח רלוונטית מזוהה)

## שלבים

1. פעולה ראשונה עם פרטים ספציפיים
2. פעולה שנייה עם פרטים ספציפיים
3. עיבוד ועיצוב התוצאות
4. מסירה לערוץ המוגדר

## פורמט פלט

תארו כיצד יש לעצב את התוצאות.

## טעויות נפוצות

- אל תעשו X כי Y
- תמיד בדקו Z לפני שממשיכים

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

• התחילו עם המטרה: משפט אחד שמסביר מה המיומנות עושה
• כללו "מתי להשתמש": עוזר לסוכן להחליט מתי להפעיל את המיומנות
• היו ספציפיים: "שלוף את הודעות הדוא"ל שלא נקראו מ-24 השעות האחרונות" עדיף על "קבל דוא"ל"
• השתמשו בדוגמאות קוד: הראו קריאות API מדויקות, פורמטי נתונים, דפוסי פקודות
• הוסיפו טבלאות: עיון מהיר לאפשרויות, נקודות קצה, פרמטרים
• כללו טיפול בשגיאות: מה לעשות כאשר קריאת API נכשלת או נתונים חסרים
• סיימו עם "טעויות נפוצות": מונע מהסוכן לחזור על בעיות ידועות

שלב 3: בדיקת גילוי

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

import { createSkillLoader } from "../src/skills/loader.ts";

const loader = createSkillLoader({
  directories: ["skills/bundled"],
  dirTypes: { "skills/bundled": "bundled" },
});

const skills = await loader.discover();
const mySkill = skills.find((s) => s.name === "github-triage");
console.log(mySkill);
// { name: "github-triage", classificationCeiling: "CONFIDENTIAL", ... }

בדקו ש:

• המיומנות מופיעה ברשימת הגילוי
• name תואם ל-frontmatter
• classificationCeiling נכון
• requiresTools ו-networkDomains מאוכלסים

כתיבה עצמית של הסוכן

הסוכן יכול ליצור מיומנויות באופן תכנותי באמצעות ה-API של SkillAuthor. כך הסוכן מרחיב את עצמו כאשר מתבקש לעשות משהו חדש.

זרימת העבודה

1. משתמש:  "אני צריך שתבדוק ב-Notion משימות חדשות כל בוקר"
2. סוכן:   משתמש ב-SkillAuthor ליצירת מיומנות במרחב העבודה שלו
3. מיומנות: נכנסת למצב PENDING_APPROVAL
4. משתמש:  מקבל התראה, סוקר את המיומנות
5. משתמש:  מאשר → המיומנות הופכת פעילה
6. סוכן:   מחבר את המיומנות ללוח זמנים של cron בוקר

שימוש ב-API של SkillAuthor

import { createSkillAuthor } from "triggerfish/skills";

const author = createSkillAuthor({
  skillsDir: workspace.skillsPath,
  userCeiling: "CONFIDENTIAL",
});

const result = await author.create({
  name: "notion-tasks",
  description: "Check Notion for new tasks and summarize them daily",
  classificationCeiling: "INTERNAL",
  requiresTools: ["browser"],
  networkDomains: ["api.notion.com"],
  content: `# בודק משימות Notion

## מתי להשתמש

- טריגר cron בוקר
- משתמש שואל על משימות ממתינות

## שלבים

1. שלוף משימות מ-Notion API באמצעות אסימון האינטגרציה של המשתמש
2. סנן משימות שנוצרו או עודכנו ב-24 השעות האחרונות
3. סווג לפי עדיפות (P0, P1, P2)
4. עצב כסיכום נקודות תבליט תמציתי
5. מסור לערוץ המוגדר
`,
});

if (result.ok) {
  console.log(`Skill created at: ${result.value.path}`);
  console.log(`Status: ${result.value.status}`); // "PENDING_APPROVAL"
}

מצבי אישור

מצב	משמעות
PENDING_APPROVAL	נוצרה, ממתינה לסקירת בעלים
APPROVED	בעלים אישר, המיומנות פעילה
REJECTED	בעלים דחה, המיומנות לא פעילה

אבטחה הסוכן אינו יכול לאשר מיומנויות בעצמו. זה נאכף ברמת

ה-API. כל המיומנויות שנכתבו על ידי הסוכן דורשות אישור מפורש של הבעלים לפני הפעלה. :::

סריקת אבטחה

לפני הפעלה, מיומנויות עוברות סורק אבטחה הבודק דפוסי הזרקת prompt:

• "Ignore all previous instructions" -- הזרקת prompt
• "You are now a..." -- הגדרה מחדש של זהות
• "Reveal secrets/credentials" -- ניסיון חילוץ נתונים
• "Bypass security/policy" -- עקיפת אבטחה
• "Sudo/admin/god mode" -- הסלמת הרשאות

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

טריגרים

מיומנויות יכולות להגדיר טריגרים אוטומטיים ב-frontmatter שלהן:

triggers:
  - cron: "0 7 * * *" # כל יום ב-7 בבוקר
  - cron: "*/30 * * * *" # כל 30 דקות

המתזמן קורא הגדרות אלו ומעיר את הסוכן בזמנים המצוינים לביצוע המיומנות. ניתן לשלב טריגרים עם שעות שקט ב-triggerfish.yaml למניעת ביצוע בתקופות מסוימות.

דוגמה מלאה

הנה מיומנות מלאה למיון התראות GitHub:

github-triage/
  SKILL.md

---
name: github-triage
description: >
  Triage GitHub notifications and issues. Categorize by priority,
  summarize new issues, flag PRs needing review. Use when the user
  asks about GitHub activity or on the hourly cron.
classification_ceiling: CONFIDENTIAL
requires_tools:
  - exec
network_domains:
  - api.github.com
---

# מיון GitHub

סקירה וסיווג התראות GitHub, issues ו-pull requests.

## מתי להשתמש

- משתמש שואל "מה קורה ב-GitHub?"
- טריגר cron שעתי
- משתמש שואל על פעילות ב-repo ספציפי

## שלבים

1. שלוף התראות מ-GitHub API באמצעות אסימון המשתמש
2. סווג: PRs הדורשים סקירה, issues חדשים, אזכורים, כשלי CI
3. תעדף לפי תווית: bug > security > feature > question
4. סכם פריטים מובילים עם קישורים ישירים
5. סמן כל דבר שמוקצה למשתמש

## פורמט פלט

### PRs הדורשים סקירה
- [#123 Fix auth flow](link) — מוקצה לך, בן יומיים

### Issues חדשים (שעה אחרונה)
- [#456 Login broken on mobile](link) — bug, עדיפות גבוהה

### אזכורים
- @you אוזכרת בדיון #789

## טעויות נפוצות

- אל תשלפו את כל ההתראות — סננו לפי פרמטר `since` לשעה האחרונה
- תמיד בדקו מגבלות קצב לפני ביצוע קריאות API מרובות
- כללו קישורים ישירים לכל פריט לפעולה מהירה

רשימת בדיקה למיומנות

לפני שמחשיבים מיומנות כמוכנה:

• [ ] שם התיקייה תואם ל-name ב-frontmatter
• [ ] התיאור מסביר מה ומתי להשתמש
• [ ] תקרת הסיווג היא הרמה הנמוכה ביותר שעובדת
• [ ] כל הכלים הנדרשים מופיעים ב-requires_tools
• [ ] כל הדומיינים החיצוניים מופיעים ב-network_domains
• [ ] ההוראות קונקרטיות ושלב-אחר-שלב
• [ ] דוגמאות הקוד משתמשות בדפוסי Triggerfish (סוגי Result, פונקציות יצרן)
• [ ] פורמט הפלט מצוין
• [ ] מקטע טעויות נפוצות כלול
• [ ] המיומנות ניתנת לגילוי על ידי הטוען (נבדק)