איך לשתף כישורי סוכן בין מאגרי קוד בלי פערי גרסאות
העתקת כישור סוכן לשמונה מאגרים יוצרת עותקים שסוטים. למדו לנהל כישורים כתלויות: מאגר משותף אחד, גרסה שכל פרויקט נועל ובודק.
כיצד לשתף מיומנויות סוכן בין מאגרים
כדי לשתף מיומנויות סוכן (agent skills) בין מאגרים, הפסיקו להעתיק את הקבצים והתחילו להסתמך עליהם כעל תלות. החזיקו מאגר מיומנויות אחד, תייגו אותו, ואפשרו לכל פרויקט להצמיד (pin) תגית ספציפית. לאחר מכן, הוסיפו בדיקת תקינות (smoke test) לכל מיומנות, ובצעו review לכל עדכון גרסה באותו אופן שבו אתם בוחנים עדכון של ספריות תלויות.
התהליך מורכב מארבעה חלקים: מקור אמת משותף, גרסה מוצמדת לכל מאגר, בדיקת תקינות לכל מיומנות, ומסלול לביקורת קוד. כל המפורט להלן מסביר מדוע כל חלק נחוץ, מה הכלים שיופצו בשנת 2026 עושים בנידון, וכיצד לבנות את המערכת כולה על שרת git מרוחק בניהול עצמי, ללא צורך במארח git חיצוני או ב־package registry. בדיקות התקינות הן החריג היחיד. הן מריצות את Claude Code, אשר שולח כל בקשה ל־model API, ולכן שלב זה עדיין מתבצע מחוץ לשרת שלכם.
מיומנות סוכן היא תיקייה המכילה קובץ SKILL.md, בתוספת כל הסקריפטים וקבצי העזר הדרושים לה. אם יחידה זו חדשה לכם, קראו תחילה את מהי מיומנות סוכן וכיצד עובד SKILL.md. דף זה עוסק בשרשרת האספקה סביב יחידה זו.
היכן מיומנויות מאוחסנות, ומדוע שיתוף הוא משימה מורכבת
Claude Code טוען מיומנויות מהמיקומים הבאים, בין היתר, ותיעוד המיומנויות מפרט כל נתיב.
.claude/skills/<skill-name>/SKILL.mdבתוך ספריית ההגדרות המנוהלות הוא המיקום הארגוני. הוא נטען עבור כל משתמש במכונות שבהן הארגון פורס אותו.~/.claude/skills/<skill-name>/SKILL.mdהוא המיקום האישי. הוא נטען בכל הפרויקטים שלך ולא של אף אחד אחר..claude/skills/<skill-name>/SKILL.mdהוא ברמת הפרויקט. הוא נטען עבור כל מי שמושך (checks out) את ה-repository הזה.<plugin>/skills/<skill-name>/SKILL.mdמגיע בתוך תוסף (plugin). הוא נטען בכל מקום שבו התוסף מופעל.
Claude Code טוען מיומנויות גם מספריות פרויקט מקוננות, מספריות שסופקו באמצעות --add-dir, וממיומנויות שהופעלו עבור חשבון ה-claude.ai שלך.
המיומנות ברמת הפרויקט היא השימושית ביותר עבור צוות, מכיוון שהיא נשמרת ב-commit וכל מי שמשכפל (clones) את ה-repo מקבל אותה. זהו גם המקום שבו מתחילות הבעיות. מיומנות ב-.claude/skills/ שייכת ל-repository אחד. אם יש לך שמונה כאלה, המיומנות מועתקת שמונה פעמים.
ה-frontmatter לא מציע פתרון. מפרט ה-Agent Skills מאפשר שימוש בשישה מפתחות, ונתיבי ההפצה שאוכפים זאת מדפיסים את הרשימה כאשר משתמשים במפתח אחר:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameשימו לב למה שחסר: אין מפתח version. ניתן לתעד גרסה תחת metadata, אך המפרט לא מגדיר הצמדת תלויות (dependency pin) או מנגנון עדכון. זה הגיוני, מכיוון שמיומנות היא מסמך ולא חבילה (package). המשמעות היא שניהול הגרסאות חייב להגיע מהשכבה שעוטפת את הקובץ, והשכבה הזו היא באחריותך.
בעיה 1: שמונה עותקים שמתפצלים בשקט
העתקה והדבקה עובדות ביום הראשון. ביום השישים הן נכשלות. מישהו מתקן הוראה שגויה במאגר payments, ואינו נוגע בשבעת האחרים. מישהו אחר מוסיף כלל בנוגע לעימוד במאגר orders. כעת אותו שם של skill מוביל לשני reviews שונים, בהתאם לתיקייה שממנה ה־agent הופעל, ואף אחד מהמפתחים אינו יודע זאת.
הכשל שקט, משום שאין מצב שגיאה. skill הוא טקסט. הוראה מיושנת מפיקה תשובה בטוחה אך שגויה, וזהו סוג השגיאה היקר ביותר. אין ב־agent מנגנון שמשווה את העותק שלכם לעותקים של אחרים, ולכן האות היחיד הוא אדם שמבחין בכך ששני מאגרים אינם תואמים.
בעיה שנייה: שום דבר אינו מקבע גרסה
גם כאשר הצוות שומר את הידע במקום אחד, שיטת השיתוף המקובלת היא שלב העתקה: סקריפט הגדרה, שורת curl במסמך הקליטה, או כינוי מעטפת שמסנכרן תיקייה. כל אלה מתקינים את מה שנמצא כרגע בראש הענף.
משמעות הדבר היא ששני מפתחים המשתמשים באותו commit של אותו יישום עלולים להפעיל הוראות שונות, משום שהם הריצו את הסנכרון בימים שונים. המשמעות היא גם שאי־אפשר לענות על השאלה החשובה לאחר הרצה כושלת של סוכן: איזו גרסה של היכולת הפיקה את התוצאה הזו? ללא revision מתועד, אי־אפשר לשחזר את ההרצה, ולכן אין אפשרות לפעול על בסיס דיווח הבאג.
בעיה שלישית: איש אינו יודע אם היכולת עדיין פועלת
ליכולת אין מהדר. אלה הוראות שמיועדות למודל, ולכן היא עלולה להפסיק לפעול גם כאשר הקובץ נשאר זהה לחלוטין, עד לרמת הבתים. שדרוג של מודל משנה את מידת הדיוק שבה הוא פועל לפי הוראה ארוכה. כלי שורת פקודה שהיכולת מפעילה משנה את שמו של דגל. כתובת URL בקובץ הפניות מתחילה להחזיר 404, והסוכן פועל על סמך דף השגיאה.
באף אחד מהמקרים האלה אין כשל גלוי. הסוכן עדיין משיב. התשובה פשוט גרועה יותר מכפי שהייתה בחודש שעבר, וקשה להבחין בכך כאשר בודקים שינוי קטן בכל pull request.
מה פותרים הכלים ששוחררו בשנת 2026
כמה פתרונות זמינים כעת, והם חלוקים בדעתם לגבי המיקום שבו הגרסה צריכה להישמר.
קובצי נעילה (Lockfiles). כלי שורת הפקודה skills מבית Vercel Labs (זמין ב-vercel-labs/skills, ברישיון MIT, גרסה v1.7.2 נכון ל-9 באוקטובר 2026) מתקין מיומנויות (skills) ממאגר git לתוך כל ספרייה שהסוכן (agent) שלכם מצפה לה, והוא מכיר את המבנה של יותר משבעים סוכנים שונים. הפקודה npx skills add <repo> מבצעת התקנה, npx skills update מבצעת שדרוג, ו-npx skills list מציגה את מה שמותקן אצלכם. הכלי מנהל שני קובצי נעילה. קובץ גלובלי ב-~/.agents/.skill-lock.json מתעד את מה שמשתמש בודד התקין. מאז גרסה v1.4.1 (20 בפברואר 2026), התקנה בהיקף הפרויקט כותבת גם את skills-lock.json בשורש הפרויקט, וקוד המקור של הכלי מציין שקובץ זה נועד להכללה בבקרת גרסאות. הפקודה npx skills experimental_install משחזרת את המיומנויות של פרויקט מתוכו. Issue 283, שביקש פקודת skills install לשחזור קובץ הנעילה הגלובלי במכונה אחרת, נסגר בסטטוס "לא מתוכנן" ב-5 בנובמבר 2026; המתחזק מציין שמדובר באותה בקשה כמו ב-Issue 549. קראו את שניהם כדוח מצב. קובץ הנעילה ברמת הפרויקט קיים. בגרסה v1.8.1 ששוחררה, פקודת השחזור עדיין מסומנת כניסיונית בעזרה, אך npx skills install ללא מקור משחזרת גם היא את קובץ הנעילה של הפרויקט.
מפרטים ובדיקות. הכלי SkillSpec נוקט בגישה אחרת. הוא מתייחס ל-SKILL.md כאל חוזה שיש לבדוק ולא כאל טקסט שניתן לסמוך עליו, מתוך מטרה מוצהרת להפוך מיומנויות ל"ניתנות למעקב, לבדיקה ולהוכחה". הפקודה skillspec doctor <path> מדווחת היכן סוכן צפוי לנתק את השרשור. skillspec boundary map <path> מציגה את תוכן המיומנות, ו-skillspec boundary assess <path> מדווחת על מה שהיא יכולה להגיע אליו, מדורג לפי רמת סיכון. זהו crate של Rust, ברישיון כפול MIT או Apache 2.0. גרסה 0.2.2 פורסמה ב-29 ביולי 2026 והיא עדיין הגרסה החדשה ביותר ב-crates.io נכון ל-10 באוקטובר 2026. התקינו את הגרסה המקובעת (pinned) ולא את החדשה ביותר:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionמאז Cargo 1.100, ששוחררה ב-12 בנובמבר 2026, cargo install משתמשת בקובץ הנעילה הארוז כברירת מחדל, ו---locked אינה מבצעת דבר. skillspec --version אמורה להדפיס 0.2.2. מספר שונה מציין שקובץ בינארי ישן יותר שנמצא מוקדם יותר ב-PATH שלכם הוא זה שרץ.
נוהלי ספקים. גוגל תיארה כיצד היא בונה את המיומנויות ב-google/skills בפוסט על כיצד היא בונה, בודקת ומדרגת מיומנויות סוכנים. אם מסירים את נושא קנה המידה, המנגנון הוא אינטגרציה רציפה (CI) רגילה. כל מיומנות עוברת linters עבור מטא-דאטה של frontmatter, ספירת שורות, מבנה ספריות ושמות לפני שהיא ממוזגת. בודק קישורים גורם לכישלון ה-build עבור כל URL שמחזיר 404, מה שחושף קישורים סבירים שהסוכן המציא. על הכותבים לספק חבילת הנחיה להערכה (evaluation prompt suite) וקריטריונים לניקוד לצד המיומנות. משימות הערכה מתוזמנות רצות לאחר מכן מדי שבוע מול כל הספרייה כדי לזהות רגרסיות, ולכל מיומנות יש בעלים מוגדר שצפוי לתקן אותה כאשר האיכות יורדת.
התבנית המשותפת לכל שלוש התשובות
אינכם חייבים לבחור באחת מהן. בבסיסן יש מבנה יחיד, ו־git רגיל מספק את כולו.
- מקור אמת יחיד. לכל skill יש מיקום יחיד, וכל repository מפנה למיקום הזה במקום להחזיק עותק.
- גרסה נעוצה לכל repository. כל פרויקט מתעד את ה־revision המדויק שבו הוא משתמש, ולכן שדרוג הוא commit באותו פרויקט, עם מחבר ותאריך.
- בדיקת smoke test לכל skill. בדיקה אחת הניתנת להרצה ומוכיחה שה־skill עדיין מפיק את התוצאה שהובטחה.
- מסלול review. שינוי ב־skill משותף עובר review, וכל צרכן רואה diff לפני שהוא מאמץ אותו.
זהו המבנה של dependency. Skills הפכו ל־artifact משותף מהר יותר מהתפתחותם של כלי הניהול סביבם, ולכן הכלים שאתם כבר סומכים עליהם הם הבחירה הבטוחה ביותר.
פריסה לצוות קטן מול remote של git באירוח עצמי
מאגר אחד מרכז את המיומנויות. שום דבר אחר אינו נשמר בו, ולכן ההיסטוריה שלו נקראת כיומן שינויים של ההנחיות.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdגרסאות מסומנות באמצעות tags. השתמשו ב־annotated tags, משום שהם כוללים הודעה ותאריך. נסחו את ההודעה כסיבה שבגללה צרכן ירצה לבצע את השדרוג:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0אם ה־remote שלכם הוא Gitea, Forgejo, GitLab או מאגר bare באמצעות SSH ב־VPS שבבעלותכם, שום דבר מההמשך אינו משתנה. כל מה שנדרש כאן הוא git וקישור סמלי.
הצמדה באמצעות תת־מודול של git
תת־מודול מתעד commit מדויק אחד של repository אחר בתוך ה־repository שלכם. הרשומה הזו היא ההצמדה. בכל פרויקט שמשתמש בו:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"ה־symlink הוא החלק שמאפשר זאת. רשומת skill ברמת הפרויקט יכולה להיות symlink לתיקייה במקום אחר בדיסק, ו־Claude Code עוקב אחריו וקורא את SKILL.md מהיעד. כך ה־skill נטען כ־skill רגיל של הפרויקט, בעוד שהקבצים עצמם נמצאים בתת־המודול ב־commit שבחרתם.
בדקו את ההצמדה:
git submodule statusשורה תקינה מתחילה ברווח, ולאחריו ה־commit, הנתיב וה־tag הקרוב ביותר:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)קידומת - מציינת שתת־המודול מעולם לא אותחל, ולכן .claude/skills/api-review מצביע על שום דבר וה־skill אינו נטען בשקט. תקנו זאת באמצעות git submodule update --init. קידומת + מציינת שה־commit שנשלף שונה מזה שתועד, ולכן אותו מפתח מריץ הוראות שאף אחד אחר אינו מריץ. ב־clone חדש צריך להפעיל git clone --recurse-submodules, ויש לכלול את השורה הזו ב־README, משום ש־clone רגיל משאיר את vendor/agent-skills ריק ואינו מציג שגיאה.
השדרוג נעשה באופן מכוון, וזו בדיוק המטרה:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"השורה diff היא נתיב הבדיקה. היא מציגה את אותו שינוי שכל repository אחר שמשתמש ברכיב יראה, ומתאימה ל־pull request.
קיבוע גרסאות באמצעות Marketplace של תוספים
אם אינכם מעוניינים לבקש מכל מפתח ללמוד לעבוד עם submodules, מערכת התוספים של Claude Code מבצעת את ההפצה עבורכם, והיא פועלת מול שרת מרוחק בניהול עצמי. הציבו קטלוג בנתיב .claude-plugin/marketplace.json במאגר ה-skills:
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}קיימים כאן שני מקורות שונים, ובלבול ביניהם הוא טעות נפוצה. מקור ה-marketplace, כלומר המקום ממנו נמשך הקטלוג עצמו, מקבל ref עבור branch או tag, ובגרסה Claude Code v2.1.324 ומעלה, גם commit SHA מלא באותיות קטנות; הוא אינו מקבל שדה sha נפרד. מקור של תוסף בתוך הקטלוג מקבל את שניהם, וכאשר שניהם מוגדרים, ה-sha הוא הקיבוע הקובע. קבעו את הקטלוג דרך ה-ref של מקור ה-marketplace שלו, ואת התוסף דרך ה-sha של רשומת הקטלוג. גם שמות הסוגים שונים. בתוך הקטלוג, url מציין מאגר git לשכפול. במקור marketplace, ה-url מציין קישור ישיר לקובץ marketplace.json, ומאגר git מוגדר כ-git.
כל מאגר צורך מצהיר לאחר מכן על ה-marketplace בקובץ ה-.claude/settings.json שלו:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code רושם את ה-marketplace עבור חבר צוות ברגע שהוא מאשר את תיבת הדו-שיח של אמון סביבת העבודה (workspace trust) עבור תיקיית הפרויקט, ללא צורך בדף wiki שינחה אותו לעשות זאת. רשומת הקטלוג מצביעה על כתובת URL של git ולא על נתיב יחסי, לכן התוסף עצמו לא מותקן רק מהגדרות המאגר. כל חבר צוות מריץ claude plugin install team-skills@acme-agents --scope project פעם אחת, ועד אז Claude Code מדווח שהתוסף מופעל בהגדרות הפרויקט אך אינו מותקן. ה-skills מגיבים לאחר מכן ל-/team-skills:api-review, כיוון ש-skills של תוספים נמצאים במרחב שמות (namespaced) לפי שם התוסף ולא יכולים להתנגש עם skill של הפרויקט בעל אותו שם. לאחר שדחפתם (push) תגית חדשה ועדכנתם את הקיבועים בקטלוג ובמאגרים הצורכים, הצרכנים מבצעים רענון עם /plugin marketplace update acme-agents, ולאחר מכן מריצים /reload-plugins אם סיכום ההתקנה דורש זאת.
כתיבת בדיקת עשן (smoke test) עבור מיומנות אחת
בדיקת עשן היא הרצה מתוסרטת של סוכן (agent) מול סביבת בדיקה (fixture) בעלת תקלה ידועה, בצירוף טענה (assertion) אחת. Claude Code פועל באופן לא אינטראקטיבי עם -p, ומיומנות שמופעלת על ידי משתמש עובדת שם: הכניסו את /skill-name למחרוזת ה-prompt והיא תורחב לפני תחילת ההרצה.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md הוא קובץ קצר עם תקלה מכוונת אחת. הטענה היא שהמיומנות תציין את שם הקובץ. jq -e מסיים את פעולתו עם קוד יציאה שאינו אפס כאשר המסנן שלו מפיק את null, לכן מיומנות שמפסיקה לזהות את התקלה המוזרקת תגרום לכישלון התסריט. claude עצמו מסיים עם קוד יציאה שאינו אפס כאשר ההרצה נכשלת, ו-set -euo pipefail הופך כל אחד מהכשלים הללו לבדיקה שנכשלה.
מודל משנה את ניסוח תשובותיו בין הרצות, לכן לעולם אל תבצעו טענה על משפט שלם. בצעו טענה על מזהה (identifier) שהמיומנות אמורה להפיק, או על שדה בסכימה שביקשתם, ושמרו על סביבת הבדיקה קטנה כדי שההרצה תישאר זולה.
ב-CI, הוסיפו את --bare. בלעדיו, claude -p טוען את אותו הקשר שהיה נטען בסשן אינטראקטיבי, כולל hooks, תוספים ו-CLAUDE.md מהמכונה שבה הוא רץ, כך שהגדרות אישיות של חבר צוות עלולות לשנות את התוצאה. מצב bare מדלג על גילוי אוטומטי (auto-discovery) למעט מיומנויות ב-.claude/skills/ תחת ספרייה שסופקה במפורש עם --add-dir; הוא מדלג על מיומנות הפרויקט שאתם בודקים כאן, לכן טענו אותה במפורש. מצב bare גם לא קורא את פרטי ההתחברות של המנוי שלכם, לכן הגדירו תחילה את ANTHROPIC_API_KEY בסביבת העבודה:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format jsonתוסף שנטען עם --plugin-dir מקבל את שמו מ-.claude-plugin/plugin.json, ובלי ה-manifest הזה הוא נקרא על שם הספרייה שלו. בצעו commit ל-plugin.json עם "name": "team-skills" לצד הקטלוג במאגר המיומנויות, אחרת הפקודה לעיל תצטרך לקרוא ל-/agent-skills:api-review במקום.
עם --output-format stream-json, האירוע system/init מדווח אילו תוספים נטענו ונושא מערך plugin_errors עבור אלו שלא נטענו. הוא פותח את הזרם (stream) אלא אם כן אירועי אתחול מגיעים קודם. הכשילו את משימת ה-CI אם plugin_errors אינו ריק. זה תופס הפניה (pin) שמכוונת לגרסה (revision) שכבר אינה קיימת, מה שעלול להיראות אחרת כסוכן שמתעלם בשקט מכללי הבית שלכם.
מיומנות משותפת היא הוראה בת-ביצוע
שני מאפיינים הופכים זאת למילולי, ושניהם חשובים כאשר הקובץ מגיע מצוות אחר.
ראשית, SKILL.md יכול להריץ פקודות shell לפני שהמודל קורא דבר מה. שורה כזו בגוף הטקסט היא עיבוד מקדים:
- Current branch: !`git rev-parse --abbrev-ref HEAD`הפקודה רצה על המכונה הטוענת את המיומנות, והפלט שלה מחליף את מציין המיקום בטקסט שהמודל מקבל. בלוק מגודר שנפתח בשלושה גרשיים הפוכים ואחריהם ! מריץ כמה פקודות באותה דרך. איש אינו מתבקש לאשר זאת בזמן הריצה. Claude Code בודק כל פקודה מול חוקי ההרשאות שלך. מחוץ למצב אוטומטי, פקודה שחוקים אלו אינם מתירים תגרום לעצירת המיומנות, אלא אם המיומנות אישרה אותה מראש באמצעות המאפיין השני להלן. חוקי מניעה ובקשת אישור עדיין גוברים על אישור מוקדם זה. קריאת מיומנות משותפת משמעותה קריאת החלפות הפקודה שבה.
שנית, ה־frontmatter יכול לאשר כלים מראש. allowed-tools מעניק את הכלים המפורטים ללא בקשת אישור עבור הסבב שהפעיל את המיומנות. אמון בסביבת העבודה אינו חוסם הענקה זו: Claude Code מחיל את ה־allowed-tools של מיומנות פרויקט גם בהרצת -p בתיקייה שאיש לא נתן בה אמון. התיעוד של Claude Code מצהיר על התוצאה בבירור: מיומנות יכולה להעניק לעצמה גישה רחבה לכלים, לכן יש לבדוק את ה־allowed-tools של מיומנויות שנשמרו במאגר לפני שמריצים שם את Claude Code. ארגון יכול למנוע את השדה ממיומנויות פרויקט ומיומנויות אישיות על ידי הגדרת allowManagedPermissionRulesOnly בהגדרות מנוהלות, מה שדורש את Claude Code בגרסה v2.1.282 ומעלה.
לכן, יש להתייחס לעדכון מיומנות בדיוק כמו לעדכון תלות. יש לקבע לפי commit מדויק בכל מקום שבו המנגנון מאפשר זאת, כיוון שניתן להזיז תגית וסניף זז מעצם הגדרתו. במכונה מאובטחת, "disableSkillShellExecution": true בהגדרות מחליף כל החלפת פקודה בטקסט המילולי [shell command execution disabled by policy] במקום להריץ אותה, ויישום דרך הגדרות מנוהלות מונע מהמשתמש לעקוף זאת. מיומנויות ארוזות ומנוהלות פטורות מהגדרה זו.
אותה זהירות חלה על מה שמיומנות קוראת. מיומנות שמריצה env או פותחת קובץ תצורה מושכת את כל מה שהיא מוצאת לתוך ההקשר של המודל, וזהו הכשל המכוסה ב-שמירה על סודות מחוץ לסוכנים שאתה מריץ. מיומנות שמושכת דף או מריצה שאילתה היא אותה חשיפה המופנית כלפי חוץ, שכן טקסט שנשלף נוחת בהקשר ונראה בדיוק כמו ההוראות שכתבת, גבול שראוי לקרוא עליו לפני ש-מפנים סוכן למופע SearXNG משלך לחיפוש באינטרנט.
מה לקרוא בעת עדכון גרסה
- את ההבדלים של כל גוף
SKILL.md, משום שזהו הטקסט שהסוכן שלך יבצע. - כל החלפת פקודה, משום שהחלפות אלה מופעלות במחשב שלך בעת טעינת היכולת.
- כל שינוי ב־
allowed-tools, משום ששורה זו מעניקה כלים ללא בקשת אישור. - את הרצת הבדיקות שמאחורי התג. אם המאגר המשותף מריץ בדיקות smoke משלו ב־CI, לתג שאליו אתם מקבעים את הגרסה צריכה להיות הרצה מוצלחת מצורפת.
מבקר שאינו יכול לקרוא את כל ההבדלים בתוך עשר דקות בוחן יכולת שגדלה מעבר למידה. פצלו אותה. אותו עיקרון חל על מסמכי המאגר שהסוכנים שלכם קוראים: שמרו כללים יציבים בקבצים המתוארים ב־ההפרדה בין AGENTS.md ל־HUMAN.md ואת ההיגיון הארכיטקטוני ב־DESIGN.md שנכתב עבור סוכנים, והשאירו את היכולות כתהליכים ממוקדים.
כאשר שינוי במודל או בכלי פוגע במיומנות
כמה דברים משתנים מתחת למיומנות בלי שאיש יערוך אותה. שדרוג מודל משנה את מידת האמינות שבה הוא ממלא אחר הוראה ארוכה, ולכן מיומנות שהסתמכה על כך שהמודל יגיע לשלב תשע עלולה להפסיק להגיע אליו. כלי שורת פקודה משנה את שמו של דגל, ולכן הסוכן מפעיל את הדגל הישן, קורא את השגיאה ומאלתר. כתובת URL שאליה יש הפניה מתחילה להחזיר 404. מעטפת סוכן משנה את אופן בחירת המיומנויות, ולכן description שבעבר זכה בהתאמה אינו זוכה בה עוד. כאשר הליך מתחיל להסתיים מוקדם באופן כזה, עדכון גרסה לא יפתור את הבעיה. ההוראות עצמן זקוקות למבנה שכופה ביצוע של השלבים האחרונים. זו הגישה שעליה מבוססת המיומנות unlazy ושיטת Depth Tree שלה.
לכן בדיקת העשן היא הרכיב המרכזי במערך הזה. הפעילו את הבדיקה של כל מיומנות לפי לוח זמנים, וגם בכל push. Google מריצה את משימות ההערכה שלה מדי שבוע מול הספרייה כולה מסיבה זו. לצוות עם עשר מיומנויות מספיק cron שבועי ב־VPS קטן. זו הדרך היחידה לקבל התראה על התקלה לפני שמפתח נתקל בה.
גם ניידות מסייעת. המפרט Agent Skills מגביל את ה־frontmatter לשישה מפתחות, ולכן מיומנות שנכתבה לפי המפרט נטענת בכלים נוספים, ולא רק בכלי שעבורו נכתבה. כל מפתח ייחודי ל־harness שאתם מוסיפים הוא הימור על ספק אחד. כתיבת מיומנויות ששורדות החלפת מודל היא תחום בפני עצמו, והוא מוסבר ב־איך לגרום למיומנות לעבוד בכל מודל.
FAQ
כיצד ניתן לשתף מיומנות סוכן (agent skill) אחת בין כמה מאגרים?
יש להציב את המיומנות במאגר git ייעודי, לתייג גרסאות (releases) בו, ולגרום לכל פרויקט צורך להפנות לתגית במקום להעתיק את הקובץ. קיימים שני מנגנונים לעשות זאת. git submodule מתעד commit מדויק, וקישור סימבולי (symlink) מתוך .claude/skills/<name> אל תוך ה-submodule גורם לו להיטען כמיומנות רגילה של הפרויקט. זירת מסחר של תוספים (plugin marketplace) מבצעת את אותה עבודה דרך /plugin, כאשר הקיבוע (pin) מוצהר בתוך .claude/settings.json של המאגר הצורך. שתי הדרכים מתעדות את הגרסה בהיסטוריית ה-git, כך שניתן לדעת אילו הוראות הפיקו הרצה מסוימת של הסוכן.
האם ניתן לקבע (pin) מיומנות סוכן לגרסה ספציפית?
לא מתוך SKILL.md, כיוון שאין ב-frontmatter זה מפתח version. הקיבוע חייב להגיע מהשכבה שעוטפת את הקובץ. git submodule מקבע commit מדויק מעצם הגדרתו. בזירת מסחר של תוספי Claude Code, מקור תוסף מקבל ref עבור ענף (branch) או תגית, ו-sha עבור commit מדויק, כאשר sha גובר אם שניהם נוכחים. מקור זירת המסחר עצמו מקבל ref עבור ענף, תגית, או בגרסה Claude Code v2.1.324 ומעלה, SHA מלא של commit באותיות קטנות. העדיפו קיבוע ל-commit, כיוון שניתן להזיז תגית לאחר שכבר סקרתם אותה.
מה על בדיקת עשן (smoke test) של מיומנות לוודא?
יש לבדוק משהו יציב. הריצו את המיומנות באופן לא אינטראקטיבי מול fixture המכיל תקלה ידועה, ולאחר מכן ודאו שמזהה ספציפי מופיע בפלט, למשל מזהה חוק (rule id) שהמיומנות אמורה לדווח עליו. בקשת פלט מובנה עם --output-format json ו---json-schema הופכת את הבדיקה למדויקת, ו-jq -e גורם לסקריפט להיכשל כאשר הערך חסר. לעולם אל תבצעו בדיקה על משפט שלם, כיוון שמודל משנה את ניסוח תשובותיו בין הרצות.
האם בטוח להתקין מיומנות משותפת ממאגר של צוות אחר?
התייחסו לכך כאל תלות קוד (code dependency), כיוון שמדובר בהוראות בנות-ביצוע. SKILL.md יכול להריץ פקודות shell בזמן הטעינה דרך צורת החלפת הפקודה !, והשדה allowed-tools ב-frontmatter יכול לאשר מראש כלים ללא בקשת אישור. קראו את ה-diff בכל עדכון גרסה, קבעו ל-commit מדויק במקום לענף, והעדיפו מקור שהצוות שלכם שולט בו. במכונות מנוהלות, "disableSkillShellExecution": true בהגדרות עוצר הרצת החלפות פקודה במיומנויות של משתמש, פרויקט, תוסף או ספריות נוספות; מיומנויות ארוזות ומנוהלות פטורות מכך.
האם מיומנות משותפת תעבוד בסוכנים שאינם Claude Code?
זה תלוי ב-frontmatter שבו אתם משתמשים. מפרט ה-Agent Skills מגדיר שישה מפתחות: name, description, license, compatibility, metadata ו-allowed-tools. מיומנות המוגבלת למפתחות אלו תיטען בכלים המממשים את המפרט, והיא תיטען גם ב-Claude Code ללא שינויים. מפתחות ספציפיים ל-harness ותכונות גוף (body features) החורגות מהמפרט יתעלמו או יידחו במקומות אחרים, לכן הימנעו משימוש בהם בכל מיומנות שאתם מתכננים לשתף באופן נרחב.