תיעוד 68

הוספת רכיבים לתוסף

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

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

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

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

הערה

המקרים האלה מכוסים בדפים אחרים:

בניית התוסף הראשון: התחילו ב-יצירת תוסף

התקנת תוסף של מישהו אחר: ראו התקנת תוספים

המשתמשים של התוסף נמצאים ב-claude.ai או ב-Cowork: שם נטען סט רכיבים אחר. ראו מבנה תוסף ובדיקות ואת טבלת התמיכה ברכיבים

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

הסייר מציג תוסף לדוגמה, my-plugin, שיש בו אחד מכל סוג רכיב במיקום ברירת המחדל שלו:

skill בשם review ופקודת about
subagent בשם security-review
hook שמעצב קבצים אחרי ש-Claude עורך אותם, ותיקיית scripts/ שהוא קורא לה
מוניטור לוג
סגנון פלט וערכת צבעים
workflow בשם route-audit
קובץ הרצה hello-plugin
הגדרות ברירת מחדל
שרת MCP מקומי ושרת שפה ל-Go

כל קובץ הוא הדוגמה התקינה הקטנה ביותר של הפורמט שלו, ונועד להראות את הצורה ולא להיות שימושי: skill או agent אמיתי נושא הוראות מלאות ולעיתים קבצי תמיכה, ו-hook או מוניטור אמיתי עושה עבודה אמיתית. הסעיפים שאחרי הסייר משתמשים באותם קבצים כדוגמאות ומקשרים לדוגמאות מלאות יותר. בחרו קובץ או תיקייה כדי לקרוא למה הוא נועד, לראות מה נכנס אליו, ולמצוא את הסעיף שמכסה אותו.

מה נכנס לתוסף

בתוסף הדוגמה הזה, my-plugin, יש אחד מכל סוג רכיב, כל אחד במיקום ברירת המחדל שלו. בחרו קובץ או תיקייה כדי לקרוא למה הוא נועד ולראות מה נכנס אליו.

תיקיית התוסף

my-plugin/

הפריט שנבחר

ה-מניפסט הוא קובץ plugin.json בתיקיית .claude-plugin/ של תוסף. הוא מכיל את המטא-נתונים של התוסף ואת ערכי userConfig ש-Claude Code מבקש מהמשתמש. Claude Code טוען תוסף גם בלי אחד. בתוך הקובץ, רק name נדרש. בזה, description הוא הטקסט שהמשתמשים רואים עבור התוסף ב-/plugin, ו-version משאיר את המשתמשים על הגרסה הזו עד שמשנים אותה:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}

skill הוא קובץ SKILL.md. שמרו כל skill בתיקייה משלו תחת skills/. Claude קורא את ה-description של כל skill, וכאשר מה שהמשתמש מבקש תואם לו, למשל בקשה מ-Claude לסקור בקשת משיכה כאן, Claude טוען את הוראות ה-skill ופועל לפיהן. המשתמש יכול גם להריץ אותו ישירות כ-/my-plugin:review:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

פקודה היא קובץ Markdown יחיד שהמשתמש מריץ לפי שם. פקודות הן הפורמט הישן יותר: skill רץ לפי שם באותו אופן ויכול גם לשאת קבצי תמיכה בתיקייה שלו, לכן כתבו חדשים כ-skills ושמרו את commands/ לקבצים שכבר יש לכם. הקובץ הזה הופך ל-/my-plugin:about ומקבל את אותו frontmatter כמו skill:

---
description: Summarize the repository
---

Summarize what this repository does in three sentences.

subagent הוא עוזר נפרד, עם הוראות משלו וחלון הקשר משלו, ש-Claude יכול להאציל אליו משימה ולקבל ממנו תוצאה בחזרה. כל קובץ Markdown תחת agents/ מגדיר אחד: ה-frontmatter נותן לו שם ואומר מתי להשתמש בו, והגוף הוא ה-system prompt שלו. זה נקרא my-plugin:security-reviewer, והמשתמש יכול להפעיל אותו עם @agent-my-plugin:security-reviewer:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

hook מריץ משהו אוטומטית בנקודה במחזור החיים של Claude Code, למשל אחרי כל עריכת קובץ: פקודת מעטפת, בקשת HTTP, קריאה לכלי MCP, prompt למודל, או subagent. שמרו את ה-hooks של התוסף ב-hooks/hooks.json בשורש התוסף. זה מריץ את scripts/format.sh של התוסף אחרי ש-Claude כותב או עורך קובץ:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

מוניטור הוא פקודת מעטפת ש-Claude Code מפעיל ברקע כשהסשן מתחיל ומשאיר אותה רצה עד שהוא מסתיים. מה שהוא מדפיס מגיע אל Claude כהתראות. שדה when יכול במקום זאת להפעיל אותו בפעם הראשונה ש-skill בעל שם רץ. זה עוקב אחרי לוג שגיאות:

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

תוסף יכול לכלול סגנונות פלט, שמשנים את האופן שבו Claude מעצב ומנסח את התשובות שלו. שמרו כל סגנון פלט כ-output-styles/<name>.md. זה מופיע ב-/output-style כ-my-plugin:terse:

---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---

Keep every reply short. Skip preambles and summaries.

תוסף יכול לכלול ערכות צבעים לממשק של Claude Code. שמרו כל ערכה כ-themes/<slug>.json. זו מופיעה ב-/theme כ-Dracula, ומסומנת כמגיעה מ-my-plugin:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

תיקיית workflows/ מחזיקה קבצי .js של workflow: בלוק meta, ואחר כך גוף סקריפט שמתזמר כמה subagents. זה רץ כ-/my-plugin:audit-routes:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

bin/ הוא האופן שבו תוסף מספק כלי שורת פקודה. כל עוד התוסף מופעל, Claude Code שם את התיקייה הזו על ה-PATH של המעטפת שבה הוא מריץ פקודות, כך ש-Claude, או הוראות של skill, יכולים להריץ את הכלי לפי שם בלי שהמשתמש יתקין דבר. עם ה-קובץ ההרצה הזה במקום, hello-plugin היא פקודה ש-Claude יכול להריץ:

#!/bin/bash
echo "hello from my-plugin"

ה-hook ב-hooks/hooks.json מריץ סקריפט, והתיקייה הזו היא המקום שבו הדוגמה שומרת אותו. השם scripts/ הוא מוסכמה, ולא משהו ש-Claude Code מחפש: ה-hook מצביע על הקובץ לפי הנתיב שלו, ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh. סקריפט עיצוב עשוי להיראות כך:

#!/bin/bash
npx prettier --write .

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

זה מגדיר את agent, שמריץ את ה-thread הראשי של הסשן כ-agent security-reviewer של התוסף עצמו, כך שה-system prompt של אותו agent, הגבלות הכלים והמודל חלים על כל הסשן:

{
  "agent": "security-reviewer"
}

שרת MCP נותן ל-Claude כלים ממערכת חיצונית. הכריזו עליו ב-.mcp.json בשורש התוסף. זה מפעיל שרת מקומי מסקריפט בתוך התוסף, ומופיע ב-/mcp כ-plugin:my-plugin:db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

שרת LSP נותן ל-Claude אבחון וניווט בקוד עבור שפה. הכריזו על השרת ב-.lsp.json בשורש התוסף. זה מחבר את שרת השפה של Go עבור קבצי .go:

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

#הוספת כל סוג רכיב

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

#Skills

skill הוא קובץ SKILL.md ש-Claude יכול לטעון כאשר ה-description שלו תואם למשימה. המשתמש יכול גם להריץ אותו כפקודה. שמרו כל skill בתיקייה משלו תחת skills/:

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

תנו ל-SKILL.md שדה description כדי ש-Claude יידע מתי להשתמש בו:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

אחרי שטוענים את התוסף, /my-plugin:review מריץ את ה-skill. שם הפקודה ומי יכול להפעיל אותה פועלים לפי הכללים האלה:

שם הפקודה: /<plugin>:<directory>, כך ש-skills/review/SKILL.md ב-my-plugin הוא /my-plugin:review. אם מגדירים name ב-frontmatter, הוא מחליף את המקטע האחרון וקידומת התוסף נשארת. ראו איך skill מקבל את שם הפקודה שלו
מי מפעיל אותו: Claude, המשתמש, או שניהם, לפי ה-frontmatter. ראו שליטה במי מפעיל skill

אפשר גם למקם skills מחוץ לתיקיית ברירת המחדל skills/:

תיקיות נוספות: פרטו אותן במפתח המניפסט skills. הן מתווספות לסריקת ברירת המחדל של skills/ ולא מחליפות אותה, שלא כמו commands ו-agents
skill יחיד בשורש התוסף: בלי תיקיית skills/ ובלי מפתח מניפסט skills, קובץ SKILL.md בשורש התוסף נטען כ-skill אחד. הגדירו name ב-frontmatter שלו, כי אחרת התקנה מ-marketplace נותנת ל-skill שם לפי תיקיית המטמון שלו ולא לפי התוסף שלכם

כדי לכלול הוראות בתוסף, כתבו אותן כ-skill. Claude Code לא טוען CLAUDE.md בשורש התוסף, ו-claude plugin validate מזהיר: CLAUDE.md at the plugin root is not loaded as project context.

אם כלל חייב להתקיים בכל פעם, למשל חסימת עריכות לקבצים מוגנים, הוסיפו אותו לתוסף כ-hook ולא כ-skill. כדי לבחור בין השניים, ראו את הלשונית Hook vs Skill תחת השוואת תכונות דומות.

לשדות frontmatter ולקבצי תמיכה, ראו Skills.

#Commands

פקודה היא קובץ Markdown יחיד שהמשתמש מריץ לפי שם, למשל /my-plugin:about.

הערה

פקודות הן הפורמט הישן יותר, ו-skills מחליפות אותן לעבודה חדשה. skill רץ לפי שם באותו אופן, והוא יכול גם לשאת קבצי תמיכה בתיקייה שלו. שמרו את commands/ לקבצים שאתם מעבירים מ-.claude/commands/.

שמרו פקודה ב-commands/<file>.md והיא הופכת ל-/<plugin>:<file>. תיקיית משנה מוסיפה מקטע, כך ש-commands/db/migrate.md הוא /my-plugin:db:migrate.

קבצי פקודה מקבלים את אותו frontmatter כמו skills.

#הגדרת פקודות במניפסט

צריך את זה רק אם רוצים לשמור קבצי פקודה במקום שאינו commands/, או להגדיר פקודה קצרה בתוך plugin.json בלי קובץ Markdown נפרד. הגדירו את מפתח המניפסט commands, ו-Claude Code קורא אותו במקום לסרוק את commands/. המפתח מקבל נתיב, מערך של נתיבים, או אובייקט שממפה כל שם פקודה לקובץ source או ל-content מוטמע.

המניפסט הזה מגדיר את /my-plugin:about באופן מוטמע, בלי קובץ Markdown:

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

טענו את התוסף והריצו /my-plugin:about בסשן כדי לאשר שהוא נטען.

לתחביר המלא של המפתח, ראו commands.

#Agents

subagent הוא עוזר נפרד, עם הוראות משלו וחלון הקשר משלו, ש-Claude יכול להאציל אליו משימה. כל קובץ Markdown תחת agents/ מגדיר אחד:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

ה-agent הזה נקרא my-plugin:security-reviewer, והמשתמש יכול להפעיל אותו במפורש עם @agent-my-plugin:security-reviewer. צורת השם היא <plugin>:<name>, כאשר <name> מגיע משדה name ב-frontmatter, או משם הקובץ כאשר השדה חסר.

מפתח המניפסט agents מחליף את הסריקה של agents/.

#ארגון agents בתיקיות משנה

אפשר לשים קבצי agent של תוסף בתיקיות משנה של agents/. Claude Code טוען אותם רקורסיבית ומחבר בנקודתיים את שם התוסף, כל שם של תיקיית משנה ואת שם הקובץ כדי ליצור את השם המתוחם של ה-agent. לדוגמה, agents/review/security.md בתוסף בשם my-plugin נטען כ-my-plugin:review:security. שתי הגדרות משנות את השם הזה:

name ב-frontmatter: הוא מחליף רק את שם הקובץ, כך ש-name: audit ב-agents/review/security.md נטען כ-my-plugin:review:audit
שדה agents במניפסט: קובץ שמפרטים שם נטען בלי שמות של תיקיות משנה, כך ש-"agents": "./custom/review/security.md" נטען כ-my-plugin:security

#שדות frontmatter ב-agents של תוסף

ה-frontmatter של agent בתוסף פועל לפי הכללים האלה:

שדות נתמכים: name, description, model, effort, maxTurns, autoCompactWindow, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, ומפתח cacheTtl של experimental. הערך התקין היחיד של isolation הוא "worktree". ראו שדות frontmatter נתמכים כדי לדעת מה כל אחד עושה
שדות שמתעלמים מהם: permissionMode, hooks, mcpServers ו-initialPrompt. קובץ agent לא יכול להוסיף hooks או שרתי MCP בעצמו, לכן הוסיפו אותם כ-hooks וכ-שרתי MCP של התוסף
name ארוך מ-256 תווים: Claude Code מתעלם ממנו ונותן ל-agent שם לפי הקובץ שלו, כפי שהוא עושה כאשר השדה חסר
frontmatter שלא מתפרש: ה-agent עדיין נטען וכל השדות מתעלמים. השם שלו לפי הקובץ, וה-description שלו הוא Agent from my-plugin plugin. הריצו claude plugin validate במעטפת כדי למצוא את הקבצים האלה

למה שכל שדה עושה ולכללי הקדימות, ראו Subagents.

#הוקים

הוק מריץ משהו באופן אוטומטי בנקודה במחזור החיים של Claude Code, למשל אחרי כל עריכת קובץ: פקודת מעטפת, בקשת HTTP, קריאה לכלי MCP, פרומפט למודל, או סוכן משנה. שמרו את הוקי התוסף ב-hooks/hooks.json בשורש התוסף, תחת מפתח "hooks" ברמה העליונה, באותה צורה כמו אובייקט hooks ב-settings.json. כך אפשר להעתיק הוק קיים מההגדרות בלי שינוי.

ההוק הזה מריץ סקריפט ארוז אחרי כל Write או Edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

שמרו את הסקריפט ב-scripts/format.sh והפכו אותו לבר הרצה.

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

הוקים ב-hooks/hooks.json ובמפתח המניפסט hooks נטענים שניהם. לכל אירוע והמטען שלו, ראו אירועי הוק.

כשתוסף מופעל אחר נושא אותו שם, אחד משניהם רושם את הוקי hooks/hooks.json שלו והוקי השני נשארים בחוץ. ראו הוקים כששני תוספים מופעלים חולקים שם כדי לדעת איזה מהם, ולגבי ההערה ב-/plugin שאומרת לכם.

כדי לכתוב הוקים כפונקציות JavaScript שרצות בתוך Claude Code ויכולות לצייר בממשק שלו, ציינו קובץ מודול תחת מפתח modules באותו hooks/hooks.json. תוסף עם אחד כזה הוא mod. ראו יצירת mod.

#מתי הוקי תוסף מופעלים

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

אם הוק אף פעם לא מופעל, ראו הוקים שלא מופעלים.

#סביבה, ציטוט, והתאמה לכלי MCP

סביבת ההוק, הציטוט של ${CLAUDE_PLUGIN_ROOT}, וה-matchers לכלי ה-MCP של התוסף עצמו פועלים כך:

סביבה: כל תהליך הוק מקבל CLAUDE_PLUGIN_ROOT ו-CLAUDE_PLUGIN_DATA בסביבה שלו, ועוד CLAUDE_PLUGIN_OPTION_<KEY> לכל ערך של הגדרת משתמש, כך שהסקריפט יכול לקרוא אותם משם
ציטוט: כש-command בלי args, הוא רץ דרך מעטפת, לכן עטפו את הנתיב ${CLAUDE_PLUGIN_ROOT} במירכאות כפולות, כמו בדוגמת hooks/hooks.json תחת הוקים, כדי שהנתיב המורחב יישאר מילה אחת במעטפת. כשמעבירים args במקום, כל רכיב מועבר כארגומנט אחד בלי מעטפת ולא צריך ציטוט. ראו צורת exec וצורת shell
התאמה לכלי MCP של התוסף עצמו: כלי משרת MCP שהתוסף הזה מצהיר נקרא mcp__plugin_<plugin>_<server>__<tool>, לכן כתבו את השם המלא הזה ב-matcher. matcher על שם השרת לבדו אף פעם לא מופעל. ראו התאמת כלי MCP

#שרתי MCP

שרת MCP נותן ל-Claude כלים ממערכת חיצונית. הכריזו עליו ב-.mcp.json בשורש התוסף, באותה צורה כמו .mcp.json של פרויקט. קובץ .mcp.json הזה מכריז על שרת אחד בשם db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

אפשר גם להשמיט את העטיפה mcpServers ולשים את db ברמה העליונה של הקובץ.

טענו את התוסף והריצו /mcp כדי לאשר שהשרת מופיע כ-plugin:my-plugin:db.

claude plugin validate בודק את .mcp.json ומדווח על רשומת שרת ש-Claude Code היה משמיט בזמן הטעינה כשגיאה. נדרש Claude Code v2.1.281 או חדש יותר.

למקום שבו רשומה פגומה מופיעה בזמן הטעינה, ראו שרתי MCP שלא מתחילים.

מפתח המניפסט mcpServers מקבל מפת שרתים מוטמעת, נתיב לקובץ JSON, או מערך של אלה. כשלשרת במניפסט יש אותו שם כמו לאחד ב-.mcp.json, שרת המניפסט מחליף אותו.

#הגעה למשתמשים ב-claude.ai וב-Cowork

שרת stdio מקומי, כמו שרת db תחת שרתי MCP, רץ ב-Claude Code ובסשן Cowork שרץ על המכונה שלכם באפליקציית Claude Desktop, אבל לא ב-claude.ai. כדי להגיע גם למשתמשים שם, הפנו לשרת מרוחק לפי כתובת https:// שלו, ש-claude.ai ו-Cowork מציעים למשתמש כמחבר, כמו שארוז מחבר MCP עם ה-skill שלו מראה.

#שמות שרתים, שמות כלים, וטעינות מחדש

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

שם שרת: plugin:<plugin>:<server>, כך ששרת db ב-my-plugin הוא plugin:my-plugin:db ב-/mcp. השתמשו באותה צורה כדי לנקוב בשם השרת בהוק mcp_tool
שמות כלים: mcp__plugin_<plugin>_<server>__<tool>, כך שכלי query על שרת db הזה הוא mcp__plugin_my-plugin_db__query. זה השם לשימוש בכללי הרשאה ובהתאמות הוק
החלפה: ${CLAUDE_PLUGIN_ROOT} ושאר משתני הנתיב מוחלפים ב-command, ב-args וב-env. אין צורך בציטוט ב-args, כי כל רכיב מועבר כארגומנט אחד
טעינה מחדש: כשהמשתמש מריץ /reload-plugins והטעינה מחדש חלה, שרת שהתצורה שלו לא השתנתה שומר על החיבור שלו. שרת שהתצורה שלו השתנתה מתחבר מחדש, ושרת שהסרתם מתנתק

#הכללת שרת MCPB ארוז

מפתח mcpServers מקבל גם שרת ארוז כקובץ MCPB, שהסיומת שלו היא .mcpb או .dxt הישנה יותר. הפנו את המפתח אל הקובץ, כנתיב בתוך התוסף או ככתובת https://:

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

השרת מקבל את השם שלו מה-name במניפסט של החבילה.

המניפסט של חבילה יכול להכריז על הגדרות שהשרת צריך מהמשתמש בבלוק user_config. שרת ארוז עם הגדרה נדרשת שאין לה ערך שמור לא מתחיל. לשונית Errors ב-/plugin מציגה Bundled MCP server "<name>" was not started: it needs configuration.

משתמשים מספקים את הערכים באחת משתי דרכים:

ב-/plugin: בחרו את התוסף בלשונית Installed ובחרו Configure
בהתקנה, מהמעטפת: העבירו --config <server>.<key>=<value> אל claude plugin install. נדרש Claude Code v2.1.285 או חדש יותר, וזה עובד רק לחבילה שארוזה בתוך התוסף.

לתעבורות ולאימות, ראו MCP.

#שרתי LSP

שרת LSP נותן ל-Claude אבחונים וניווט בקוד לשפה. אם תוסף מודיעין קוד רשמי כבר מכסה את השפה שלכם, התקינו אותו במקום לכתוב אחד. אחרת הכריזו על השרת ב-.lsp.json בשורש התוסף:

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

הקובץ ממפה כל שם שרת ישירות לתצורה שלו, בלי אובייקט עטיפה סביב המפה. command הוא שם הקובץ הבינארי, עם הארגומנטים שלו ב-args. extensionToLanguage צריך לפחות סיומת אחת, וכל אחת מתחילה ב-..

claude plugin validate לא קורא את הקובץ הזה. כשרשומה כלשהי לא תקינה, כל הקובץ מדולג בטעינה ו-Invalid LSP server config for ".lsp.json" מופיע בלשונית Errors של /plugin.

התוסף שלכם מגדיר את החיבור אבל לא מתקין את הבינארי של השרת, וכל סיומת קובץ מקבלת שרת אחד:

בינארי חסר: Claude Code מפעיל את command לפי שם מ-PATH של המשתמש. כשהבינארי לא שם, השרת נכשל בהתחלה ו-claude --debug רושם LSP server <name> failed to start
התנגשויות סיומת: כששני שרתים מופעלים תובעים את אותה סיומת, הראשון שנרשם מטפל בקבצים האלה והשני לא בשימוש עבורם, בין שהשרתים מגיעים מתוסף אחד או משניים. לשונית Errors ב-/plugin מציגה את האזהרה LSP server "<name>" is not used for <ext> files

מפתח המניפסט lspServers מקבל את אותה מפה מוטמעת, נתיב לקובץ JSON, או מערך של אלה, והשרתים שלו מתווספים לאלה ב-.lsp.json. כשלשרת במניפסט יש אותו שם כמו לאחד ב-.lsp.json, שרת המניפסט מחליף אותו.

ל-transport, לזמני המתנה, להפעלות מחדש ולשאר השדות, ראו lspServers.

שלחו פלט יומן אל stderr, לא אל stdout. Claude Code קורא את stdout של שרת כהודעות פרוטוקול בלבד, ומקבל כותרות הודעה עד 64 KiB וגוף הודעה עד 32 MiB.

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

#קבצי הרצה

קבצים ב-bin/ בשורש התוסף נמצאים ב-PATH של מעטפת כלי Bash בזמן שהתוסף מופעל, כך ש-Claude יכול להריץ אותם כפקודות חשופות. פקודה ש-Claude מריץ עם כלי PowerShell מחוץ לארגז החול מוצאת אותם גם ב-PATH שלה, ופקודת PowerShell בארגז חול לא. הוסיפו סקריפט בר הרצה:

#!/bin/bash
echo "hello from my-plugin"

הפכו אותו לבר הרצה עם chmod +x bin/hello-plugin וטענו את התוסף. כשמבקשים מ-Claude להריץ hello-plugin, תוצאת כלי Bash מציגה את פלט הסקריפט.

תיקיות bin/ של תוסף באות אחרי רשומות PATH של המשתמש עצמו, כך שתוסף לא יכול להאפיל על git, ls, או פקודת מערכת אחרת.

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

#הגדרות ברירת מחדל

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

קבעו את agent כדי להריץ אחד מהסוכנים של התוסף עצמו כשרשור הראשי:

{
  "agent": "security-reviewer"
}

טענו את התוסף והתחילו סשן. אז Claude עונה בשיחה הראשית עם פרומפט המערכת והמודל של סוכן security-reviewer.

לכל מה שהמפתח שולט בו, ראו הגדרת agent.

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

קובץ על פני מניפסט: כששניהם קיימים ו-settings.json קובע לפחות מפתח נתמך אחד, settings.json חל ו-settings של המניפסט מתעלמים ממנו
הגדרות משתמש על פני ברירות מחדל של תוסף: בין מקורות ההגדרות, ברירות המחדל של התוסף הן השכבה הנמוכה ביותר, כך ש-agent של המשתמש עצמו ב-~/.claude/settings.json דורס את שלכם
שני תוספים קובעים את אותו מפתח: הערך מהתוסף שנטען אחרון חל, ו-claude --debug רושם overrides setting

לצורה של subagentStatusLine, ראו שורות סטטוס של סוכן משנה.

#ערכות נושא וסגנונות פלט

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

רכיב	שמירה בשם	פורמט	מופיע ב	מפתח מניפסט
ערכת נושא	`themes/<slug>.json`	פורמט קובץ ערכת נושא מותאמת שמשתמשים כותבים ב-`~/.claude/themes/`	`/theme`, תחת ה-`name` של הקובץ	`experimental.themes`
סגנון פלט	`output-styles/<name>.md`	פורמט סגנון פלט מותאם, עם frontmatter של `name` ו-`description`	`/output-style`, כ-`<plugin>:<name>`	`outputStyles`

ערכות נושא של תוסף הן לקריאה בלבד, כך שכשמשתמש עורך אחת ב-/theme, העריכה נשמרת כעותק בתיקיית הערכות שלו.

הערכה הזו צובעת מחדש את צבע המבטא של הפרומפט ואת טקסט השגיאה על ה-preset הכהה:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

#ערוצים

ערוץ מאפשר למערכת חיצונית כמו אפליקציית צ'אט לשלוח הודעות לתוך סשן. בתוסף, ערוץ הוא אחד משרתי ה-MCP ועוד רשומת channels שנקשרת אליו ויכולה לבקש תצורה משלה. המניפסט הזה קושר ערוץ לשרת telegram ומבקש אסימון בוט:

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

server חייב להתאים למפתח ב-mcpServers. ה-userConfig לכל ערוץ מקבל את אותה צורה כמו מפתח userConfig ברמה העליונה.

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

#מוניטורים

מוניטור הוא פקודת מעטפת שרצה ברקע לכל אורך הסשן. מה שהוא מדפיס מגיע ל-Claude כהתראות, כך ש-Claude יכול להגיב ליומן או לשינוי סטטוס בלי שיתבקש לצפות בו. שמרו את הרשומות ב-monitors/monitors.json:

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

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

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

סשנים אינטראקטיביים: מוניטורים של תוסף לא מתחילים במצב לא אינטראקטיבי עם הדגל -p
גרסת מינימום: ב-Amazon Bedrock, ב-Claude Platform on AWS, ב-Google Cloud's Agent Platform, או ב-Microsoft Foundry, או כש-DISABLE_TELEMETRY או CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC מוגדרים, מוניטורים דורשים Claude Code v2.1.310 או חדש יותר. הדרישה חלה כששליפת דגלי תכונה כבויה
בלי הגדרת משתמש: command מקבל את משתני הנתיב ואת ${ENV_VAR} מהסביבה, אבל אף פעם לא את ${user_config.*}. מוניטור שמפנה לאחד כזה לא מתחיל, ותהליכי מוניטור גם לא מקבלים CLAUDE_PLUGIN_OPTION_<KEY>
השבתה באמצע סשן: אם משביתים תוסף באמצע סשן, Claude Code לא עוצר מוניטורים שכבר רצים. הם נעצרים כשהסשן מסתיים

מפתח המניפסט experimental.monitors מקבל את אותו מערך מוטמע או נתיב לקובץ JSON, והוא נקרא במקום monitors/monitors.json.

למפעיל when ולשאר השדות, ראו monitors.

#בקש מהמשתמש ערכי הגדרה

הצהר על הערכים שהתוסף שלך צריך מהמשתמש במפתח המניפסט userConfig, כדי שמשתמשים לא יערכו את settings.json בעצמם. כל אפשרות מופיעה בתיבת דו שיח, עם title שלה כתווית ועם description שלה מתחתיה.

הגדר "sensitive": true עבור אסימון או סיסמה. תיבת הדו שיח אז ממסכת את הקלט, והערך נשמר באחסון מאובטח ולא בsettings.json.

המניפסט הזה מבקש נקודת קצה ואסימון:

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

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

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

מתקין את התוסף ב/plugin
מריץ את /plugin install <plugin>@<marketplace> בתוך סשן
מפעיל את התוסף מלשונית Installed ב/plugin

כדי לפתוח את אותה תיבת דו שיח בכל עת, המשתמש מריץ את /plugin configure <plugin>@<marketplace>.

תיבת הדו שיח Manage plugins של תוסף VS Code מבקשת אפשרויות שלא הוגדרו כטופס אחרי התקנה, וסמל גלגל שיניים בשורה של התוסף פותח את הטופס שוב עם כל אפשרות.

פקודת המעטפת claude plugin install אף פעם לא מבקשת ערכי userConfig. כדי להגדיר ערכים מהמעטפת, העבר כל אחד כ--config KEY=VALUE בזמן ההתקנה, או העבר אובייקט JSON בצינור אל claude plugin configure --values-stdin לאחר מכן.

כשאפשרויות נשארות לא מוגדרות, claude plugin install מדפיס שורה userConfig options not yet set. לטקסט המדויק של השורה, ראה The userConfig dialog never appears.

לשדות האפשרות, היכן כל ערך נשמר, איך רכיב מפנה לערך שנשמר, ואילו שדות דוחים ${user_config.*}, ראה User configuration.

#הפנה לנתיבי תוסף ואחסן נתונים

אתה לא יודע היכן התוסף שלך יותקן, לכן הפנה לקבצים ולנתונים שלו דרך המשתנים האלה במקום נתיבים קבועים. הם מוחלפים בתוכן של skill, command וagent, בפקודות hook וmonitor, ובהגדרות שרתי MCP וLSP. הם גם מיוצאים לתהליכי hook, MCP וLSP:

${CLAUDE_PLUGIN_ROOT}: ספריית ההתקנה של התוסף. לכל גרסה יש ספריית מטמון משלה, ולכן הנתיב משתנה כשהתוסף מתעדכן. אל תכתוב שם מצב
${CLAUDE_PLUGIN_DATA}: ספרייה ששורדת עדכונים, עבור node_modules, סביבות וירטואליות ומטמונים. היא נפתרת אל ~/.claude/plugins/data/<id>/ ונוצרת בהפניה הראשונה
${CLAUDE_PROJECT_DIR}: שורש הפרויקט, אותו ערך שhooks מקבלים

בנתיב ספריית הנתונים, <id> הוא מזהה התוסף שבו כל תו שאינו אות, ספרה, _ ו- מוחלף ב-, כך שmy-plugin@my-marketplace הופך לmy-plugin-my-marketplace.

בWindows, רוב הנתיבים המוחלפים משתמשים בלוכסנים קדמיים, כמו בC:/Users/you/.... הם שומרים על הלוכסנים ההפוכים המקוריים שלהם בhook בצורת exec ובhook שרץ דרך PowerShell, שהיא מעטפת ברירת המחדל בWindows כשGit Bash אינו מותקן.

#התקן תלויות אל ספריית הנתונים

עבור תוסף שהותקן מmarketplace, Claude Code מתקין תלויות חבילות Node.js זכאיות אוטומטית כשהוא שומר את התוסף במטמון, כך שייתכן שלא תצטרך להתקין אותן בעצמך. כשכן, הhook הזה מסוג SessionStart מתקין את node_modules אל ${CLAUDE_PLUGIN_DATA} בהרצה הראשונה, ושוב אחרי שעדכון משנה את package.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

אחרי הסשן הראשון, ~/.claude/plugins/data/<id>/node_modules קיים. שרת MCP יכול אז להגדיר את NODE_PATH אל ${CLAUDE_PLUGIN_DATA}/node_modules בenv שלו. לאילו שדות מחליפים איזה משתנה, ראה Environment variables.

#הצעדים הבאים

Plugin manifest reference: שדות plugin.json, כללי נתיב, והפריסה הסטנדרטית
Test plugins with evals: בדוק שהרכיבים שהוספת משנים את ההתנהגות של Claude באופן שהתכוונת
Publish and distribute a plugin: תן גרסה לתוסף ושים אותו בmarketplace
Troubleshoot plugins: מה לעשות כשרכיב לא נטען או כשhook לא מופעל