📘 תיעוד 183

הרחבת סוכנים עם מיומנויות

שליטה במיומנויות שקלוד יכול להפעיל בסשנים של Claude Agent SDK, שיגור פקודות לפי שם, וכתיבת מיומנויות שהסשנים מגלים

מיומנויות סוכן (Agent Skills) מרחיבות את קלוד ביכולות מתמחות שקלוד מפעיל כשהן רלוונטיות. מיומנויות נארזות כקבצי SKILL.md שמכילים הוראות, תיאורים ומשאבי תמיכה אופציונליים. הדף הזה מכסה גם פקודות בסשנים של Agent SDK.

למידע נוסף על מיומנויות, כולל יתרונות, ארכיטקטורה והנחיות לכתיבה, ראו את סקירת Agent Skills.

#איך מיומנויות עובדות עם ה-Agent SDK

בשימוש ב-Claude Agent SDK, מיומנויות הן:

• מוגדרות כארטיפקטים במערכת הקבצים: יוצרים כל מיומנות כקובץ SKILL.md בתיקייה משלה, לדוגמה .claude/skills/<name>/SKILL.md
• נטענות ממערכת הקבצים: ה-SDK טוען מיומנויות ממיקומים במערכת הקבצים שנקבעים על ידי settingSources (TypeScript) או setting_sources (Python)
• מתגלות אוטומטית: אחרי שטעינת הגדרות מערכת הקבצים, ה-SDK מגלה מטא נתונים של מיומנויות בהפעלה מתיקיות משתמש ופרויקט, וטוען את התוכן המלא כשקלוד מפעיל את המיומנות
• מופעלות על ידי המודל: קלוד בוחר בעצמו מתי להשתמש בהן לפי ההקשר
• מופעלות על ידי המשתמש: משגרים מיומנות ישירות על ידי שליחת /<name> בפרומפט. ראו פקודות בסשנים של Agent SDK
• מוגבלות בהיקף דרך האפשרות skills: מיומנויות שהתגלו מופעלות כברירת מחדל. מעבירים רשימת שמות מיומנויות, "all", או [] כדי לשלוט באילו מיומנויות קלוד יכול להפעיל

בניגוד ל-subagents, שאפשר להגדיר באפשרות agents, יוצרים מיומנויות כקבצים על הדיסק. ה-SDK לא מספק API תכנותי לרישום שלהן.

[!NOTE]

מיומנויות מתגלות דרך מקורות ההגדרות של מערכת הקבצים. עם אפשרויות ברירת המחדל של query(), ה-SDK טוען מקורות משתמש ופרויקט, ולכן מיומנויות ב-~/.claude/skills/, ב-<cwd>/.claude/skills/, וב-.claude/skills/ בכל תיקיית אב של <cwd> עד שורש המאגר זמינות. מקור הפרויקט מכסה גם את <dir>/.claude/skills/ בכל תיקייה שמעבירים דרך additionalDirectories (TypeScript) או add_dirs (Python), כי ה-SDK מעביר את התיקיות האלה ל-Claude Code כ---add-dir. אם מגדירים את settingSources במפורש, כללו את 'project' כדי לשמור מיומנויות של הפרויקט ושל תיקיות שנוספו ואת 'user' כדי לשמור את המיומנויות האישיות, או השתמשו באפשרות plugins כדי לטעון מיומנויות מנתיב מסוים.

#שימוש במיומנויות עם ה-Agent SDK

מגדירים את האפשרות skills ב-query() כדי לשלוט באילו מיומנויות קלוד יכול להפעיל בסשן. כשמשמיטים אותה, מיומנויות שהתגלו מופעלות וכלי ה-Skill זמין, בהתאמה להתנהגות ה-CLI. מעבירים "all" כדי לאפשר לקלוד להפעיל כל מיומנות שהתגלתה, רשימת שמות מיומנויות כדי לאפשר רק אותן, או [] כדי לאפשר לקלוד להפעיל אף אחת.

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

Python:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

TypeScript:

const options = { skills: ["pdf", "docx"] };

#הגדרת מיומנויות בסשן

כשמגדירים את skills, ה-SDK מוסיף את כלי ה-Skill ל-allowedTools אוטומטית. אם מעבירים גם רשימת tools מפורשת, כללו את "Skill" ברשימה הזו כדי שקלוד יוכל להפעיל מיומנויות.

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

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

Python:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
        setting_sources=["user", "project"],  # Load skills from filesystem
        skills="all",  # Let Claude invoke every discovered skill
        allowed_tools=["Read", "Write", "Bash"],
    )

    async for message in query(
        prompt="Help me process this PDF document", options=options
    ):
        print(message)


asyncio.run(main())

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: process.cwd(), // .claude/skills/ here or in a parent directory
    settingSources: ["user", "project"], // Load skills from filesystem
    skills: "all", // Let Claude invoke every discovered skill
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

#אימות שהמיומנויות נטענו

קרוב לתחילת הזרם, ה-SDK מניב הודעת מערכת עם subtype init. בדקו את מערך ה-skills שלה כדי לאשר שהמיומנויות נטענו לפני שקלוד מתחיל לעבוד. המערך כולל את המיומנויות שהמשתמש יכול להפעיל, שהוגדרו עם שדה frontmatter בשם description או when_to_use, יחד עם מיומנויות מצורפות שכלולות ב-Claude Code.

המערך מפרט רק מיומנויות שהמשתמש יכול להפעיל. מיומנות עם user-invocable: false ב-frontmatter שלה נטענת ונשארת זמינה לקלוד, אבל לא מופיעה במערך. המערך מפרט את אותן המיומנויות בין אם הן ברשימת skills ובין אם לא.

#התרת מיומנויות ספציפיות בלבד

כדי לאפשר לקלוד להפעיל רק מיומנויות ספציפיות, מעבירים את השמות שלהן ברשימת skills:

• המיומנויות שלכם: שם התיקייה של המיומנות
• מיומנויות של תוסף: plugin:skill
• התנגשויות שמות ב-additionalDirectories או add_dirs: מיומנות באחת מהתיקיות האלה מקבלת שם עם קידומת כשהשם שלה מתנגש עם מיומנות ארגונית, אישית או של הפרויקט, או עם מיומנות בתיקייה שנוספה קודם. מפרטים אותה לפי השם הזה. עם מיומנות verify ב-../api וב-../web, שנוספו בסדר הזה, ובלי מיומנות verify אחרת, מפרטים אותן כ-verify ו-web:verify. נדרש Claude Code מגרסה v2.1.309 ואילך

הרשימה מקבלת שמות מיומנות מדויקים בלבד. אם רשומה לא יכולה לעבוד כשם מדויק, query() דוחה את הרשימה לפני שהסשן מתחיל. ראו שגיאת שם מיומנות לא תקין לכללי השמות ולשגיאה שכל SDK מעלה.

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

כדי לאפשר לקלוד להפעיל כל מיומנות שהתגלתה, מעבירים skills: "all" במקום תו כללי.

#פקודות בסשנים של Agent SDK

הסעיף הזה הוא תיעוד הפקודות של ה-SDK. פקודה היא כל דבר שמריצים על ידי שליחת /<name> בפרומפט. רשומות במשטח הפקודות נבדלות במה שעומד מאחוריהן:

• פקודות מובנות: מריצות לוגיקה שמקודדת בתהליך Claude Code שה-SDK מריץ, לדוגמה /compact
• מיומנויות מצורפות: ארטיפקטים של פרומפט שכלולים ב-Claude Code, לדוגמה /code-review
• המיומנויות שלכם: ארטיפקטים של פרומפט שאתם כותבים, כל אחד תיקייה שמחזיקה קובץ SKILL.md. השם של מיומנות שהמשתמש יכול להפעיל מצטרף למשטח אוטומטית, כך ששיגור /security-check משלכם והרצת פקודה מובנית עובדים באותו אופן
• קבצי פקודה מותאמים: צורת ארטיפקט ישנה יותר עם אותה התנהגות, קבצי Markdown שטוחים ב-.claude/commands/ ששמות הקבצים שלהם הופכים לשמות פקודות. מיומנויות הן היורש המומלץ שלהם

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

#גילוי פקודות זמינות

אפשר לשגר דרך ה-SDK פקודות שעובדות בלי מסוף אינטראקטיבי. הודעת system/init מפרטת את אלה שזמינות בסשן בשדה slash_commands שלה. פקודות שצריכות מסוף אינטראקטיבי, כמו /theme ו-/terminal-setup, לא מופיעות ברשימה. ניגשים לשדה כשהסשן מתחיל:

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello Claude",
  options: { maxTurns: 1 }
})) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available commands:", message.slash_commands);
  }
}

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage


async def main():
    async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            print("Available commands:", message.data["slash_commands"])


asyncio.run(main())

הרשימה המודפסת מערבבת פקודות מובנות, מיומנויות מצורפות, המיומנויות שלכם שהמשתמש יכול להפעיל, וקבצי .claude/commands/:

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

מיומנות עם user-invocable: false ב-frontmatter שלה לא מופיעה ברשימה הזו ולא במערך skills מ-אימות שהמיומנויות נטענו. סשנים שמגדירים שרתי MCP יכולים גם לחשוף פרומפטים של MCP כפקודות.

#שיגור פקודות לפי שם

שולחים פקודה על ידי הכללתה במחרוזת הפרומפט, באותו אופן ששולחים טקסט רגיל. השיגור לא תלוי באפשרות skills. שליחת /<name> מריצה מיומנות שהמשתמש יכול להפעיל גם כשרשימת skills משמיטה אותה. פקודות שפועלות על היסטוריית השיחה, כמו /compact, צריכות הודעות קודמות כדי לעבוד איתן.

/<name> שלא תואם לא פקודה בסשן ולא פקודה מובנית של Claude Code לא מכשיל את ה-query. Claude Code שולח את הפרומפט לקלוד כהודעה רגילה, עם הערה שהפקודה לא רצה, כך שה-query צורך תור מודל ומחזיר את תשובת קלוד. לפני v2.1.274, /<name> שלא התאים לכלום החזיר Unknown command: /<name> כתוצאה בלי תור מודל.

/<name> שתואם לפקודה מובנית של Claude Code שלא זמינה בסשן, כמו /theme, מחזיר /theme isn't available in this environment. כתוצאה בלי תור מודל.

[!NOTE]

פקודה יכולה להגיע למגבלת maxTurns / max_turns כמו כל פרומפט אחר, ולסיים את ה-query בתוצאת שגיאה במקום success. לחוזה של תוצאת השגיאה, ראו טיפול בתוצאה. אם הפקודה עלולה להגיע למגבלה, עטפו את הלולאה ב-try/catch ב-TypeScript או ב-try/except ב-Python, כפי שמוצג ב-קלט הודעה יחידה, או הגדירו את maxTurns גבוה מספיק כדי שהעבודה תושלם.

#דחיסת היסטוריה עם /compact

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

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Compaction needs existing history, so have a conversation first
try {
  for await (const message of query({
    prompt: "Explain what this project does",
    options: { maxTurns: 2 }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result,
  // so the follow-up query below still runs.
  console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
  prompt: "/compact",
  options: { continue: true, maxTurns: 1 }
})) {
  if (message.type === "system" && message.subtype === "compact_boundary") {
    console.log("Compaction completed");
    console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
    console.log("Trigger:", message.compact_metadata.trigger);
    // Example output:
    // Compaction completed
    // Pre-compaction tokens: 1842
    // Trigger: manual
  }
}

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage


async def main():
    # Compaction needs existing history, so have a conversation first
    try:
        async for message in query(
            prompt="Explain what this project does",
            options=ClaudeAgentOptions(max_turns=2),
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # so the follow-up query below still runs.
        print(f"Session ended with an error: {error}")

    # Compact the same conversation
    async for message in query(
        prompt="/compact",
        options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
            print("Compaction completed")
            print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
            print("Trigger:", message.data["compact_metadata"]["trigger"])
            # Example output:
            # Compaction completed
            # Pre-compaction tokens: 1842
            # Trigger: manual


asyncio.run(main())

[!NOTE]

הודעת compact_boundary מגיעה רק כשהדחיסה רצה. כשבסשן שהמשיך יש הודעות אבל אין מה ש-/compact יכול לסכם, הריצה עדיין מסתיימת בתוצאת success ולא בשגיאה, ולא מגיעה הודעת compact_boundary. טקסט התוצאה נושא אז את הסיבה, לדוגמה Not enough messages to compact. כשהסשן מחזיק פרומפט אבל עדיין אין תשובה מקלוד. קריאת query() חד פעמית טרייה מתחילה עם הקשר ריק, אז משתמשים בתבנית הזו בסשן עם תורים קודמים, לדוגמה ב-מצב קלט בזרימה או כשמחדשים סשן.

#איפוס הקשר עם /clear

פקודת /clear מאפסת את השיחה להקשר ריק, כך שפרומפטים הבאים מתחילים בלי היסטוריית שיחה קודמת. השיחה הקודמת נשארת על הדיסק. אפשר לחזור לשיחה הזו על ידי העברת מזהה הסשן שלה לאפשרות resume.

/clear שימושי ב-מצב קלט בזרימה, שבו שולחים כמה פרומפטים על חיבור יחיד. בקריאות query() חד פעמיות, כל קריאה כבר מתחילה עם הקשר ריק, כך שלשליחת /clear אין השפעה מעשית. התחילו קריאת query() חדשה במקום זה.

#יצירת skills

צרו כל skill כספרייה שמכילה קובץ SKILL.md עם YAML frontmatter ותוכן Markdown. השדה description קובע מתי Claude מפעיל את ה-skill שלכם.

דוגמה למבנה ספריות:

.claude/skills/security-check/
└── SKILL.md

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

שמרו skills באחת משתי רמות הגילוי הנפוצות ביותר:

• Project skills: .claude/skills/, זמינים רק בפרויקט הנוכחי
• Personal skills: ~/.claude/skills/, זמינים בכל הפרויקטים שלכם

אם יש לכם קבצי פקודה מותאמים אישית קיימים ב-.claude/commands/, הם ממשיכים לעבוד. קובץ פקודה ב-.claude/commands/deploy.md יוצר את /deploy ועובד באותו אופן כמו skill ב-.claude/skills/deploy/SKILL.md. אם קובץ פקודה ו-skill חולקים שם, ראו פתרון skills שחולקים שם כדי לדעת איזה מהם רץ. ה-SDK טוען קבצים מ-.claude/commands/ ומ-~/.claude/commands/ מאותם שני scopes כמו skills. ראו הרחבת Claude עם skills למדריך המלא לשתי צורות הארטיפקט.

#יצירה והפעלה של ה-skill הראשון שלכם

כדי לראות את הזרימה המלאה, צרו את .claude/skills/security-check/SKILL.md:

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

אחרי שהקובץ קיים, ה-skill זמין דרך ה-SDK. Claude מפעיל אותו כשבקשה תואמת את ה-description שלו, ואפשר להפעיל אותו ישירות:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "/security-check",
  options: { maxTurns: 10 }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    async for message in query(
        prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

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

**Security scan of `app.js` , 4 findings (most severe first):**

1. **SQL Injection** (line 8) , `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

שם ה-skill מופיע גם במערך slash_commands של הודעת ה-init.

[!NOTE]

Claude Code כולל skills מובנים code-review ו-verify. אם נותנים לקובץ ב-.claude/commands/ שם של אחד מהם, לדוגמה .claude/commands/code-review.md, הפקודה של הקובץ מסתירה את ה-skill המובנה ו-slash_commands מציג את השם פעם אחת.

#אישור מראש של כלים ל-skills

[!NOTE]

בסשנים של SDK אפשר לאשר מראש כלים ל-skill של פרויקט או אישי באמצעות ה-frontmatter allowed-tools של ה-skill, או באמצעות האפשרות allowedTools (allowed_tools ב-Python) בהגדרת ה-query. אם הארגון שלכם מגדיר allowManagedPermissionRulesOnly ב-managed settings, Claude Code מתעלם משניהם. Skills שמסונכרנים מ-claude.ai פועלים לפי כללי ה-frontmatter שלהם.

Skills רצים עם הכלים של הסשן. הדוגמה למטה מאשרת מראש את Read, Grep ו-Glob באמצעות allowedTools (allowed_tools ב-Python), כדי ש-Claude יוכל לבדוק קבצים בזמן הרצת ה-skill security-check בלי לעצור לאישור:

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load skills from filesystem
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
)


async def main():
    async for message in query(prompt="Check this project for security issues", options=options):
        print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Check this project for security issues",
  options: {
    settingSources: ["user", "project"], // Load skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  console.log(message);
}

בזרם, הפעלת ה-skill מופיעה כשימוש בכלי Skill, ואחריה קריאות Read לקבצי הפרויקט. ההרצה מסתיימת בתוצאת success שהטקסט שלה נושא את הממצאים.

הרשימה מאשרת מראש את הכלים שצוינו, במקום להגביל את האחרים. לזרימת ההרשאות המלאה, כולל מצבי הרשאה וה-callback canUseTool, ראו הרשאות.

#פתרון בעיות

#Skills לא נמצאו

בדקו את הגדרת settingSources: ה-SDK מגלה skills דרך מקורות ההגדרות user ו-project. אם מגדירים את settingSources/setting_sources במפורש ומשמיטים את המקורות האלה, ה-SDK לא טוען skills:

# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)

// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
  settingSources: [],
  skills: "all"
};

// Skills loaded: user and project sources included
const optionsWithSkills = {
  settingSources: ["user", "project"],
  skills: "all"
};

לאילו ספריות skill כל מקור טוען, ראו את טבלת מקורות מערכת הקבצים. לפרטים נוספים על settingSources/setting_sources, ראו את הפניה ל-SDK של TypeScript או הפניה ל-SDK של Python.

בדקו את ספריית העבודה: ה-SDK טוען skills מ-.claude/skills/ באפשרות cwd ובכל ספריית אב עד שורש המאגר. ודאו ש-cwd מצביע על הספרייה שמכילה את .claude/skills/ או מתחתיה, בתוך אותו מאגר:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
    setting_sources=["user", "project"],  # Loads skills from these sources
    skills="all",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
  cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
  settingSources: ["user", "project"], // Loads skills from these sources
  skills: "all"
};

ראו שימוש ב-skills עם ה-Agent SDK לדפוס המלא.

אמתו את מיקום מערכת הקבצים:

# Check project skills
ls .claude/skills/*/SKILL.md

# Check personal skills
ls ~/.claude/skills/*/SKILL.md

#Skill לא בשימוש

בדקו את האפשרות skills: אם העברתם רשימת skills, ודאו ששם ה-skill כלול. כש-Claude מנסה להפעיל skill שלא ברשימה, כלי ה-Skill מחזיר Skill <name> is not in this session's skills allowlist. הוסיפו את השם לרשימה, או הפעילו את ה-skill ישירות על ידי שליחת /<name> ב-prompt, וזה עובד בלי רישום ברשימה.

בדקו את ה-description: ודאו שהוא ספציפי וכולל מילות מפתח רלוונטיות. ראו שיטות עבודה מומלצות ל-Agent Skills להנחיה לכתיבת descriptions יעילים.

#שגיאת שם skill לא תקין

כששם ברשימת skills שלכם לא יכול לשמש כשם skill מדויק, query() דוחה את הרשימה לפני הפעלת תהליך Claude Code. שמות שמפעילים את הדחייה כוללים:

• שם ריק
• שם שמכיל סוגריים, פסיקים או תווי בקרה
• שם שמרופד ברווח לבן
• צורת wildcard כגון * בודד או סיומת :*

כל SDK מציג את הדחייה אחרת:

TypeScript

ה-SDK של TypeScript זורק Error שמציין את הכלל שהרשומה הפרה. לדוגמה, skills: ["docs:*"] זורק:

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

שם ריק מדווח Skill names must be non-empty strings.

לפני TypeScript Agent SDK 0.3.221, ה-SDK לא הריץ את הבדיקה הזו.

Python

ה-SDK של Python מעלה ValueError שמציין את הכלל שהרשומה הפרה. לדוגמה, skills=["docs:*"] מעלה:

ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

שם ריק מדווח Skill names must be non-empty strings.

לפני Python Agent SDK 0.2.129, ה-SDK לא הריץ את הבדיקה הזו.

#פתרון בעיות נוסף

לפתרון בעיות כללי ב-skills, כגון שגיאות תחביר YAML וניפוי שגיאות, ראו את מקטע פתרון הבעיות של skills ב-Claude Code.

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

מדריך ה-skills של Claude Code מכסה כתיבה לעומק. ההנחיה שלו חלה על סשנים של SDK. התחילו במקטעים האלה:

• הפניה ל-frontmatter: כל שדה נתמך
• העברת ארגומנטים ל-skills: $ARGUMENTS, $0 ו-$1. טבלת ההחלפות המלאה מוסיפה ארגומנטים בעלי שם ואת המשתנים ${CLAUDE_*}
• הזרקת הקשר דינמי: שורות !`command` שרצות לפני ש-Claude רואה את תוכן ה-skill
• בחירה מאיפה skills נטענים: כל מיקום של skill, namespacing של plugins, ואיזה skill רץ כששניים חולקים שם

#משאבים קשורים

• פקודות ב-Claude Code: משטח הפקודות המלא, כולל כל פקודה מובנית
• סקירה של Agent Skills: סקירה מושגית, יתרונות וארכיטקטורה
• שיטות עבודה מומלצות ל-Agent Skills: הנחיות כתיבה ל-skills יעילים
• ספר מתכונים של Agent Skills: skills ותבניות לדוגמה
• Subagents ב-SDK: סוכנים דומים שמבוססים על מערכת קבצים, עם אפשרויות תכנותיות
• סקירת SDK: מושגי SDK כלליים
• הפניה ל-SDK של TypeScript: תיעוד API מלא
• הפניה ל-SDK של Python: תיעוד API מלא