رفتن به محتوا
Claude Code Docs غیر رسمی

Agent Skills در SDK

Extend Claude with specialized capabilities using Agent Skills in the Claude Agent SDK

مرورِ کلی

Section titled “مرورِ کلی”

Agent Skills کلود را با قابلیت‌های تخصصی گسترش می‌دهند که کلود هرجا مرتبط باشد خودش به‌صورت خودکار آن‌ها را فراخوانی می‌کند. Skillها به‌صورت فایل‌های SKILL.md بسته‌بندی می‌شوند که شاملِ دستورالعمل‌ها، توضیحات و منابعِ پشتیبانِ اختیاری‌اند.

برای اطلاعاتِ جامع درباره‌ی Skillها، شامل مزایا، معماری و رهنمودهای نگارش، به مرورِ کلیِ Agent Skills مراجعه کن.

Skillها چطور با SDK کار می‌کنند

Section titled “Skillها چطور با SDK کار می‌کنند”

هنگام استفاده از Claude Agent SDK، Skillها این‌طور هستند:

  1. به‌عنوان آرتیفکت‌های فایل‌سیستم تعریف می‌شوند: به‌صورت فایل‌های SKILL.md در دایرکتوری‌های مشخص (.claude/skills/) ساخته می‌شوند
  2. از فایل‌سیستم بارگذاری می‌شوند: Skillها از مکان‌های فایل‌سیستمی که توسط settingSources (در TypeScript) یا setting_sources (در Python) تعیین می‌شوند بارگذاری می‌شوند
  3. به‌صورت خودکار کشف می‌شوند: به‌محضِ بارگذاریِ تنظیماتِ فایل‌سیستم، متادیتای Skill هنگامِ راه‌اندازی از دایرکتوری‌های کاربر و پروژه کشف می‌شود؛ محتوای کامل هنگامِ فراخوانی بارگذاری می‌شود
  4. توسط مدل فراخوانی می‌شوند: کلود بر اساسِ کانتکست خودش تصمیم می‌گیرد کِی از آن‌ها استفاده کند
  5. با گزینه‌ی skills فیلتر می‌شوند: Skillهای کشف‌شده به‌صورت پیش‌فرض فعال‌اند. برای کنترلِ این‌که کدام‌ها در نشست در دسترس باشند، یک فهرستی از نام‌های Skill، مقدارِ "all" یا [] را پاس بده

برخلافِ ساب‌ایجنت‌ها (که می‌توان آن‌ها را به‌صورتِ برنامه‌نویسی‌شده تعریف کرد)، Skillها باید به‌عنوانِ آرتیفکتِ فایل‌سیستم ساخته شوند. SDK برای ثبتِ Skillها یک API برنامه‌نویسی‌شده ارائه نمی‌دهد.

استفاده از Skillها با SDK

Section titled “استفاده از Skillها با SDK”

گزینه‌ی skills را روی query() تنظیم کن تا کنترل کنی کدام Skillها برای نشست در دسترس باشند. وقتی این گزینه حذف شود، Skillهای کشف‌شده فعال‌اند و ابزارِ Skill در دسترس است، که با رفتارِ CLI مطابقت دارد. برای فعال‌سازیِ همه‌ی Skillهای کشف‌شده "all" را پاس بده، برای فعال‌سازیِ فقط برخی، فهرستی از نام‌های Skill را، و برای غیرفعال‌سازیِ همه [] را. وقتی skills را تنظیم کنی، SDK خودش ابزارِ Skill را به allowedTools اضافه می‌کند. اگر فهرستِ صریحِ tools را هم پاس بدهی، "Skill" را در آن فهرست بگنجان تا کلود بتواند Skillها را فراخوانی کند.

پس از پیکربندی، کلود به‌صورت خودکار Skillها را از فایل‌سیستم کشف می‌کند و هرجا که با درخواستِ کاربر مرتبط باشد آن‌ها را فراخوانی می‌کند.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions




async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # Project with .claude/skills/
        setting_sources=["user", "project"],  # Load Skills from filesystem
        skills="all",  # Enable 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())
import { query } from "@anthropic-ai/claude-agent-sdk";


for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: "/path/to/project", // Project with .claude/skills/
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all", // Enable every discovered Skill
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

برای فعال‌سازیِ فقط Skillهای مشخص، نامِ آن‌ها را پاس بده. نام‌ها با فیلدِ name در SKILL.md یا با نامِ دایرکتوریِ Skill مطابقت دارند. برای Skillهایی که توسطِ پلاگین ارائه می‌شوند از plugin:skill استفاده کن.

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

گزینه‌ی skills یک فیلترِ کانتکست است، نه یک سندباکس. Skillهای فهرست‌نشده از مدل پنهان می‌مانند و توسطِ ابزارِ Skill رد می‌شوند، اما فایل‌هایشان روی دیسک باقی می‌مانند و از طریقِ Read و Bash قابلِ دسترس‌اند.

مکانِ Skillها

Section titled “مکانِ Skillها”

Skillها بر اساسِ پیکربندیِ settingSources/setting_sources تو از دایرکتوری‌های فایل‌سیستم بارگذاری می‌شوند:

  • Skillهای پروژه (.claude/skills/): از طریقِ git با تیمت به اشتراک گذاشته می‌شوند — وقتی setting_sources شاملِ "project" باشد بارگذاری می‌شوند
  • Skillهای کاربر (~/.claude/skills/): Skillهای شخصی در همه‌ی پروژه‌ها — وقتی setting_sources شاملِ "user" باشد بارگذاری می‌شوند
  • Skillهای پلاگین: همراهِ پلاگین‌های نصب‌شده‌ی Claude Code می‌آیند

ساختنِ Skillها

Section titled “ساختنِ Skillها”

Skillها به‌عنوانِ دایرکتوری‌هایی تعریف می‌شوند که یک فایلِ SKILL.md با frontmatterِ YAML و محتوای Markdown دارند. فیلدِ description تعیین می‌کند کلود کِی Skill تو را فراخوانی کند.

نمونه‌ی ساختارِ دایرکتوری:

Terminal window
.claude/skills/processing-pdfs/
└── SKILL.md

برای راهنماییِ کاملِ ساختنِ Skillها، شامل ساختارِ SKILL.md، Skillهای چندفایلی و مثال‌ها، به این‌ها مراجعه کن:

محدودیت‌های ابزار

Section titled “محدودیت‌های ابزار”

برای کنترلِ دسترسیِ ابزار برای Skillها در برنامه‌های SDK، از allowedTools استفاده کن تا ابزارهای مشخص از پیش تأیید شوند. بدونِ کال‌بکِ canUseTool، هر چیزی که در فهرست نباشد رد می‌شود:

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


async for message in query(prompt="Analyze the codebase structure", options=options):
    print(message)
for await (const message of query({
  prompt: "Analyze the codebase structure",
  options: {
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk" // Deny anything not in allowedTools
  }
})) {
  console.log(message);
}

کشفِ Skillهای در دسترس

Section titled “کشفِ Skillهای در دسترس”

برای دیدنِ این‌که کدام Skillها در برنامه‌ی SDK تو در دسترس‌اند، کافی است از کلود بپرسی:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
)


async for message in query(prompt="What Skills are available?", options=options):
    print(message)
for await (const message of query({
  prompt: "What Skills are available?",
  options: {
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all"
  }
})) {
  console.log(message);
}

کلود بر اساسِ دایرکتوریِ کاریِ فعلی و پلاگین‌های نصب‌شده، Skillهای در دسترس را فهرست می‌کند.

آزمایشِ Skillها

Section titled “آزمایشِ Skillها”

Skillها را با پرسیدنِ سؤال‌هایی که با توضیحاتشان مطابقت دارند آزمایش کن:

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["Read", "Bash"],
)


async for message in query(prompt="Extract text from invoice.pdf", options=options):
    print(message)
for await (const message of query({
  prompt: "Extract text from invoice.pdf",
  options: {
    cwd: "/path/to/project",
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Bash"]
  }
})) {
  console.log(message);
}

اگر توضیحات با درخواستت مطابقت داشته باشد، کلود به‌صورت خودکار Skill مرتبط را فراخوانی می‌کند.

عیب‌یابی

Section titled “عیب‌یابی”

Skillها پیدا نمی‌شوند

Section titled “Skillها پیدا نمی‌شوند”

پیکربندیِ settingSources را بررسی کن: Skillها از طریقِ منابعِ تنظیماتِ user و project کشف می‌شوند. اگر settingSources/setting_sources را به‌صورت صریح تنظیم کنی و این منابع را حذف کنی، Skillها بارگذاری نمی‌شوند:

# 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 options = {
  settingSources: [],
  skills: "all"
};


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

برای جزئیاتِ بیشتر درباره‌ی settingSources/setting_sources، به مرجعِ TypeScript SDK یا مرجعِ Python SDK مراجعه کن.

دایرکتوریِ کاری را بررسی کن: SDK، Skillها را از .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"
};

برای الگوی کامل، به بخشِ «استفاده از Skillها با SDK» در بالا مراجعه کن.

مکانِ فایل‌سیستم را تأیید کن:

Terminal window
# Check project Skills
ls .claude/skills/*/SKILL.md


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

Skill استفاده نمی‌شود

Section titled “Skill استفاده نمی‌شود”

گزینه‌ی skills را بررسی کن: اگر فهرستِ skills را پاس داده‌ای، مطمئن شو نامِ Skill در آن گنجانده شده است. پاس‌دادنِ [] همه‌ی Skillها را غیرفعال می‌کند.

توضیحات را بررسی کن: مطمئن شو دقیق است و کلیدواژه‌های مرتبط را در بر دارد. برای راهنماییِ نگارشِ توضیحاتِ مؤثر به بهترین شیوه‌های Agent Skills مراجعه کن.

عیب‌یابیِ بیشتر

Section titled “عیب‌یابیِ بیشتر”

برای عیب‌یابیِ عمومیِ Skillها (نحوِ YAML، اشکال‌زدایی و غیره)، به بخشِ عیب‌یابیِ Skillها در Claude Code مراجعه کن.

مستنداتِ مرتبط

Section titled “مستنداتِ مرتبط”

راهنماهای Skillها

Section titled “راهنماهای Skillها”

منابعِ SDK

Section titled “منابعِ SDK”