📘 תיעוד 43

יצירת תוספים

צור תוספים מותאמים אישית כדי להרחיב את Claude Code עם skills, agents, hooks ושרתי MCP.

תוספים מאפשרים לך להרחיב את Claude Code עם פונקציונליות מותאמת אישית שניתן לשתף בין פרויקטים וצוותים. מדריך זה עוסק ביצירת תוספים משלך עם skills, agents, hooks ושרתי MCP.

מעוניין להתקין תוספים קיימים? ראה גילוי והתקנת תוספים. למפרט טכני מלא, ראה הפניה לתוספים.

#מתי להשתמש בתוספים לעומת תצורה עצמאית

Claude Code תומך בשתי דרכים להוספת skills, agents ו-hooks מותאמים אישית:

טיפ: התחל עם תצורה עצמאית בתוך .claude/ לצורך איטרציה מהירה, ולאחר מכן המר לתוסף כשאתה מוכן לשתף.

#התחלה מהירה

מדריך מהיר זה מלווה אותך ביצירת תוסף עם skill מותאם אישית. אתה תיצור manifest (קובץ התצורה שמגדיר את התוסף שלך), תוסיף skill, ותבדוק אותו מקומית באמצעות הדגל --plugin-dir.

#דרישות מוקדמות

• Claude Code מותקן ומאומת

#צור את התוסף הראשון שלך

1. צור את ספריית התוסף: כל תוסף נמצא בספרייה משלו המכילה את ה-skills, ה-agents, או ה-hooks שלך, ולעיתים גם manifest מסוג .claude-plugin/plugin.json. המיקום אינו משנה עבור מדריך מהיר זה, מכיוון שתפנה את Claude Code אל הספרייה באמצעות --plugin-dir בשלב הבדיקה. צור אותה בכל מקום נוח, כגון תיקיית scratch או ספריית פרויקטים:

   העתק

   mkdir my-first-plugin

   השלבים הבאים רצים מתוך ספריית האב ומתייחסים לנתיבים כמו my-first-plugin/... באופן יחסי אליה.

2. צור את ה-manifest של התוסף: קובץ ה-manifest בנתיב .claude-plugin/plugin.json מגדיר את זהות התוסף שלך: שמו, התיאור והגרסה שלו. Claude Code משתמש במטא-דאטה זה כדי להציג את התוסף שלך במנהל התוספים.

   צור את הספרייה .claude-plugin בתוך תיקיית התוסף שלך:

   העתק

   mkdir my-first-plugin/.claude-plugin

   לאחר מכן צור את my-first-plugin/.claude-plugin/plugin.json עם התוכן הבא:

   העתק

   {
     "name": "my-first-plugin",
     "description": "A greeting plugin to learn the basics",
     "version": "1.0.0",
     "author": {
       "name": "Your Name"
     }
   }

   שדה	מטרה
   name	מזהה ייחודי ו-namespace של ה-skill. שמות skills מקבלים קידומת זו (למשל, /my-first-plugin:hello).
   description	מוצג במנהל התוספים בעת עיון או התקנה של תוספים.
   version	אופציונלי. אם מוגדר, משתמשים מקבלים עדכונים רק כאשר אתה מעלה שדה זה, למעט במקור מסוג command או תוסף שנטען במקום: ראה ניהול גרסאות. אם הושמט, הגרסה מגיעה מהמקור הבא המתואר ב-ניהול גרסאות.
   author	אופציונלי. מועיל עבור ייחוס קרדיט.

   לשדות נוספים כמו homepage, repository ו-license, ראה את סכמת ה-manifest המלאה.

3. הוסף skill: רכיבי Skills נמצאים בספריית skills/. כל skill הוא תיקייה המכילה קובץ SKILL.md. שם התיקייה הופך לשם ה-skill, עם קידומת ה-namespace של התוסף (hello/ בתוסף ששמו my-first-plugin יוצר את /my-first-plugin:hello).

   צור ספריית skill בתוך תיקיית התוסף שלך:

   העתק

   mkdir -p my-first-plugin/skills/hello

   לאחר מכן צור את my-first-plugin/skills/hello/SKILL.md עם התוכן הבא:

   העתק

   ---
   description: Greet the user with a friendly message
   disable-model-invocation: true
   ---
   
   Greet the user warmly and ask how you can help them today.

4. בדוק את התוסף שלך: הפעל את Claude Code עם הדגל --plugin-dir כדי לטעון את התוסף שלך:

   העתק

   claude --plugin-dir ./my-first-plugin

   ברגע ש-Claude Code מתחיל, נסה את ה-skill החדש שלך:

   העתק

   /my-first-plugin:hello

   אתה תראה את Claude מגיב בברכה. הרץ /help ופתח את הכרטיסייה Custom commands כדי לראות את ה-skill שלך מופיע תחת ה-namespace של התוסף.

   הערה: למה נדרש namespacing? שמות skills של תוספים תמיד כוללים namespace (כמו /my-first-plugin:hello) כדי למנוע התנגשויות כאשר למספר תוספים יש skills עם אותו שם.

   כדי לשנות את קידומת ה-namespace, עדכן את השדה name ב-plugin.json.

5. הוסף ארגומנטים ל-skill: הפוך את ה-skill שלך לדינמי על ידי קבלת קלט מהמשתמש. שומר המקום $ARGUMENTS לוכד כל טקסט שהמשתמש מספק אחרי שם ה-skill.

   עדכן את קובץ ה-SKILL.md שלך:

   העתק

   ---
   description: Greet the user with a personalized message
   ---

#Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

הרץ `/reload-plugins` כדי להחיל את השינויים. לאחר מכן נסה את ה-skill עם השם שלך:

```shell
/my-first-plugin:hello Alex

Claude יברך אותך בשמך. למידע נוסף על העברת ארגומנטים ל-skills, ראה Skills.

טיפ: הדגל --plugin-dir שימושי לצורכי פיתוח ובדיקה. כאשר אתה מוכן לשתף את התוסף שלך עם אחרים, ראה יצירה והפצה של marketplace לתוספים.

#פיתוח תוסף בספריית ה-skills שלך

במקום להעביר את --plugin-dir בכל הפעלה, באפשרותך לשמור תוסף בספריית ה-skills שלך ולגרום ל-Claude Code לטעון אותו באופן אוטומטי. הפקודה claude plugin init מייצרת שלד ראשוני:

claude plugin init my-tool

פעולה זו יוצרת את ~/.claude/skills/my-tool/ עם manifest בנתיב .claude-plugin/plugin.json וקובץ SKILL.md התחלתי. בהפעלה הבאה הוא נטען כ-my-tool@skills-dir ללא צורך ב-marketplace או בשלב התקנה.

לכללי הטעינה האוטומטית, היקף אישי לעומת היקף פרויקט, דרישת ה-workspace-trust, וכיצד לעדכן או להסיר תוסף כזה, ראה תוספים בספריית skills.

#סקירת מבנה התוסף

יצרת תוסף עם skill, אך תוספים יכולים לכלול הרבה יותר: agents מותאמים אישית, hooks, שרתי MCP, שרתי LSP, ומנטרי רקע (background monitors).

אזהרה: טעות נפוצה: אל תשים את commands/, agents/, skills/ או hooks/ בתוך ספריית .claude-plugin/. רק plugin.json נכנס לתוך .claude-plugin/. כל שאר הספריות חייבות להיות ברמת שורש התוסף.

שורש התוסף הוא הספרייה האישית של התוסף עצמו, כגון my-first-plugin/ מתוך ההתחלה המהירה. זה לעולם לא ~/.claude/. לדוגמה, Claude Code אינו קורא קובץ .mcp.json הממוקם ב-~/.claude/.mcp.json.

תוסף שמספק בדיוק skill אחד יכול למקם את SKILL.md ישירות בשורש התוסף במקום ליצור ספריית skills/. Claude Code טוען אותו כ-skill בודד ומשתמש בשדה name ב-frontmatter עבור שם ההפעלה. השתמש במבנה skills/ עבור תוספים שעשויים לגדול ליותר מ-skill אחד.

#פיתוח תוספים מורכבים יותר

לאחר שתרגיש בנוח עם תוספים בסיסיים, תוכל ליצור הרחבות מתוחכמות יותר.

#הוספת Skills לתוסף שלך

תוספים יכולים לכלול Agent Skills כדי להרחיב את יכולותיו של Claude. רכיבי Skills מופעלים על ידי המודל: Claude משתמש בהם באופן אוטומטי בהתבסס על הקשר המשימה.

הוסף ספריית skills/ בשורש התוסף שלך עם תיקיות Skill המכילות קובצי SKILL.md:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

כל SKILL.md מכיל YAML frontmatter והוראות. כלול description כדי ש-Claude ידע מתי להשתמש ב-skill:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

לאחר שתתקין את התוסף, בדוק את סיכום ההתקנה: אם מדווח שם Run /reload-plugins to activate., ראה החלת שינויים בתוסף ללא הפעלה מחדש כדי לטעון את ה-Skills בהפעלה הנוכחית שלך. להנחיות מלאות לכתיבת Skills, כולל חשיפה הדרגתית והגבלות כלים, ראה Agent Skills.

#הוספת שרתי LSP לתוסף שלך

טיפ: עבור שפות נפוצות כמו TypeScript, Python ו-Rust, התקן את תוספי ה-LSP המוכנים מראש מה-marketplace הרשמי. צור תוספי LSP מותאמים אישית רק כאשר אתה זקוק לתמיכה בשפות שאינן מכוסות כבר.

תוספי LSP (Language Server Protocol) מעניקים ל-Claude יכולות code intelligence בזמן אמת. אם אתה צריך לתמוך בשפה שאין לה תוסף LSP רשמי, תוכל ליצור תוסף משלך על ידי הוספת קובץ .lsp.json לתוסף שלך:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

משתמשים שמתקינים את התוסף שלך חייבים שקובץ ההפעלה הבינארי של שרת השפה יהיה מותקן במחשב שלהם.

כדי לוודא שהשרת מתחיל, הפעל את Claude Code כאשר התוסף מופעל ובדוק את כרטיסיית ה-Errors ב-/plugin: שרת שפה שנכשל בהפעלה מופיע שם, למשל עם ההודעה Executable not found in $PATH כאשר הקובץ הבינארי אינו מותקן. רשומה עם תצורה לא חוקית מדולגת במקום זאת: הרץ claude --debug כדי לראות את הסיבה.

לאפשרויות תצורה מלאות של LSP, ראה שרתי LSP.

#הוספת מנטרי רקע לתוסף שלך

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

הוסף קובץ monitors/monitors.json בשורש התוסף עם מערך של רשומות מנטרים:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

כל שורת stdout מ-command מועברת ל-Claude כהודעה במהלך ההפעלה. עבור הסכמה המלאה, כולל טריגר ה-when והחלפת משתנים, ראה מנטרים.

#אספקת הגדרות ברירת מחדל עם התוסף שלך

תוספים יכולים לכלול קובץ settings.json בשורש התוסף כדי להחיל תצורת ברירת מחדל כאשר התוסף מופעל. נכון לעכשיו, רק המפתחות agent ו-subagentStatusLine נתמכים.

הגדרת agent מפעילה את אחד מ-ה-agents המותאמים אישית של התוסף בתור ה-main thread, ומחילה את ה-system prompt שלו, הגבלות כלים, ומודל. הדבר מאפשר לתוסף לשנות את התנהגות ברירת המחדל של Claude Code כאשר הוא מופעל.

{
  "agent": "security-reviewer"
}

דוגמה זו מפעילה את ה-agent בשם security-reviewer המוגדר בספריית agents/ של התוסף. הגדרות מתוך settings.json מקבלות עדיפות על פני settings המוצהרים ב-plugin.json. מפתחות לא מוכרים זוכים להתעלמות שקטה.

#ארגון תוספים מורכבים

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

#בדיקת התוספים שלך באופן מקומי

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

claude --plugin-dir ./my-plugin

הדגל מקבל גם ארכיון .zip של ספריית התוסף.

claude --plugin-dir ./my-plugin.zip

כאשר לתוסף שנטען עם --plugin-dir יש אותו שם כמו לתוסף מותקן מ-marketplace, העותק המקומי מקבל עדיפות באותה הפעלה. הדבר מאפשר לך לבדוק שינויים בתוסף שכבר התקנת מבלי להסיר אותו קודם. החריג לכך הוא תוספים שהגדרות מנוהלות כופות את הפעלתם או השבתתם: הדגל --plugin-dir אינו יכול לעקוף אותן.

בזמן שאתה מבצע שינויים בתוסף שלך, הרץ /reload-plugins כדי לקלוט את העדכונים מבלי להפעיל מחדש. פעולה זו טוענת מחדש תוספים, skills, agents, hooks, שרתי MCP של תוספים, ושרתי LSP של תוספים. בהפעלה ללא טרמינל אינטראקטיבי, שינויים בשרת MCP של תוסף ממתינים להפעלה הבאה שלך. בדוק את רכיבי התוסף שלך:

• נסה את ה-skills שלך עם /plugin-name:skill-name
• ודא ש-agents מופיעים ב-/context תחת Custom Agents, או תייג אחד בעזרת @ לפי שמו המוגדר בהיקף (scoped name)
• הפעל את האירוע שכל hook תואם לו, כגון בקשה מ-Claude לערוך קובץ עבור hook מסוג PostToolUse, ואשר את השפעתו. Claude Code רושם אילו hooks התאימו, את קודי היציאה שלהם, ואת הפלט שלהם ב-יומן הדיבאג

טיפ: באפשרותך לטעון מספר תוספים בו-זמנית על ידי ציון הדגל מספר פעמים:

העתק

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

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

בדיקת התוסף עם --plugin-dir מראה לך שהוא יכול לפעול. כדי לגלות באיזו תדירות Claude אכן פונה אליו ומגיע לתוצאה הנכונה, הרץ אותו כנגד קבוצה של prompt-ים לבדיקה באמצעות claude plugin eval. כל prompt רץ מספר פעמים עם התוסף טעון ובלעדיו, כך שתוכל לראות מה התוסף תורם ולתפוס רגרסיות כאשר אתה משנה אותו או כאשר מודל חדש משוחרר.

כדי לטעון מספר תוספים ממקום אחד, העבר תיקייה שמכילה אותם, כגון --plugin-dir ./plugins. טעינת תיקייה של תוספים דורשת את Claude Code גרסה v2.1.265 ומעלה. Claude Code קורא את הרמה העליונה של התיקייה כדי להחליט אילו תוספים ייטענו, ובמהלך הפעלה אינטראקטיבית הוא גם עוקב אחר התיקייה לשינויים מאוחרים יותר:

• מה נטען: אם אין בתיקייה manifest או רכיבי תוסף ברמה העליונה שלה, Claude Code מתייחס אליה כאל תיקייה של תוספים. כל תת-תיקייה ישירה שיש בה manifest בנתיב .claude-plugin/plugin.json נטענת כתוסף נפרד. Claude Code מדלג על כל שאר הדברים בתיקייה מבלי לדווח על שגיאה, כולל תוספים שאין להם manifest.
• שינויים במהלך הפעלה אינטראקטיבית: תת-תיקייה שאתה מוסיף נטענת כתוסף חדש ברגע שה-manifest שלה קיים, וכאשר אתה מסיר תת-תיקייה, התוסף שלה נפרק. Claude Code מדפיס שורה בהפעלה עבור כל שינוי. אם החלת שינוי באמצע השיחה תבטל את תוקף ה-prompt cache, Claude Code מעכב אותו, והשורה מציינת שיש להריץ /reload-plugins כדי להחיל אותו.

כדי לבדוק תוסף שכבר ארוז כארכיון .zip ומאוחסן בכתובת URL, כגון תוצר בנייה של CI, השתמש ב---plugin-url במקום זאת. Claude Code מוריד את הארכיון בעת ההפעלה וטוען אותו עבור אותה הפעלה בלבד. אם Claude Code אינו מצליח להוריד את הארכיון, או שהארכיון אינו תקין, הוא מופעל ללא התוסף ורושם שגיאת טעינת תוסף שתוכל לסקור בכרטיסיית Errors של מנהל ה-/plugin. אותם שיקולי אמון חלים כמו לגבי כל מקור תוסף: כוון דגל זה רק לארכיונים שאתה שולט בהם או סומך עליהם.

כדי לטעון מספר תוספים, חזור על הדגל עבור כל URL:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

או העבר כתובות URL מופרדות ברווח כארגומנט יחיד במירכאות:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

#ניפוי שגיאות בתוספים

אם התוסף שלך אינו פועל כמצופה:

1. בדוק את המבנה: ודא שהספריות שלך נמצאות בשורש התוסף, ולא בתוך .claude-plugin/
2. בדוק רכיבים בנפרד: בדוק כל skill, agent, ו-hook בנפרד
3. השתמש בכלי אימות וניפוי שגיאות: ראה כלי פיתוח וניפוי שגיאות עבור פקודות CLI וטכניקות לפתרון בעיות

#שיתוף התוספים שלך

כאשר התוסף שלך מוכן לשיתוף:

1. הוסף תיעוד: כלול README.md עם הוראות התקנה ושימוש
2. בחר אסטרטגיית ניהול גרסאות: החלט אם להגדיר version מפורש או להסתמך על ברירת המחדל המתוארת ב-ניהול גרסאות.
3. צור או השתמש ב-marketplace: הפץ דרך marketplaces של תוספים לצורך התקנה
4. בדוק עם אחרים: בקש מחברי צוות לבדוק את התוסף לפני הפצה רחבה יותר

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