Skip to main content

Agent Skills ใน SDK

ขยายความสามารถของ Claude ด้วย Agent Skills ใน Claude Agent SDK

ภาพรวม​

Agent Skills ขยายความสามารถของ Claude ด้วยความสามารถเฉพาะทางที่ Claude เรียกใช้โดยอัตโนมัติเมื่อเกี่ยวข้อง Skills ถูกบรรจุในรูปแบบไฟล์ SKILL.md ที่มีคำแนะนำ, คำอธิบาย, และทรัพยากรสนับสนุนเพิ่มเติมที่เป็นทางเลือก

สำหรับข้อมูลครบถ้วนเกี่ยวกับ Skills รวมถึงประโยชน์, สถาปัตยกรรม, และแนวทางการเขียน ดู ภาพรวม Agent Skills

วิธีที่ Skills ทำงานกับ SDK​

เมื่อใช้ Claude Agent SDK, Skills จะ:

  1. ถูกกำหนดเป็น filesystem artifacts: สร้างเป็นไฟล์ SKILL.md ในไดเรกทอรีเฉพาะ (.claude/skills/)
  2. โหลดจาก filesystem: Skills โหลดจาก filesystem locations ที่ถูกควบคุมโดย settingSources (TypeScript) หรือ setting_sources (Python)
  3. ถูกค้นพบโดยอัตโนมัติ: เมื่อโหลด filesystem settings แล้ว metadata ของ Skill จะถูกค้นพบเมื่อเริ่มต้นจาก user และ project directories; เนื้อหาเต็มจะโหลดเมื่อถูก trigger
  4. เรียกใช้โดย model: Claude เลือกใช้โดยอัตโนมัติตาม context
  5. กรองผ่าน option skills: Skills ที่ค้นพบจะเปิดใช้งานโดยค่าเริ่มต้น ส่ง list ชื่อ skill, "all", หรือ [] เพื่อควบคุมว่าอันไหนจะพร้อมใช้ในเซสชัน

ต่างจาก subagents (ซึ่งสามารถกำหนดได้แบบ programmatic) Skills ต้องสร้างเป็น filesystem artifacts SDK ไม่มี programmatic API สำหรับลงทะเบียน Skills

note

Skills ถูกค้นพบผ่าน filesystem setting sources ด้วย options query() เริ่มต้น SDK จะโหลด user และ project sources ดังนั้น skills ใน ~/.claude/skills/, <cwd>/.claude/skills/, และ .claude/skills/ ในไดเรกทอรีหลักของ <cwd> จนถึง repository root จะพร้อมใช้งาน หากคุณตั้งค่า settingSources อย่างชัดเจน รวม 'user' หรือ 'project' เพื่อเก็บการค้นพบ skill ไว้

การใช้ Skills กับ SDK​

ตั้งค่า option skills บน query() เพื่อควบคุม Skills ที่พร้อมใช้งานในเซสชัน เมื่อไม่ระบุ Skills ที่ค้นพบจะถูกเปิดใช้งานและ Skill tool จะพร้อมใช้ ส่ง "all" เพื่อเปิดใช้งานทุก Skill ที่ค้นพบ, list ชื่อ 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);
}

หากต้องการเปิดใช้งานเฉพาะ Skills ที่ระบุ ให้ส่งชื่อของมัน ชื่อจะตรงกับ field name ใน SKILL.md หรือชื่อไดเรกทอรีของ Skill ใช้ plugin:skill สำหรับ Skills ที่ให้มาโดย plugin:

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

ตำแหน่งของ Skill​

Skills โหลดจาก filesystem directories ตาม configuration settingSources/setting_sources ของคุณ:

  • Project Skills (.claude/skills/): แชร์กับทีมผ่าน git - โหลดเมื่อ setting_sources รวม "project"
  • User Skills (~/.claude/skills/): Skills ส่วนตัวในทุกโปรเจกต์ - โหลดเมื่อ setting_sources รวม "user"
  • Plugin Skills: รวมอยู่กับ Claude Code plugins ที่ติดตั้ง

การสร้าง Skills​

Skills ถูกกำหนดเป็นไดเรกทอรีที่มีไฟล์ SKILL.md พร้อม YAML frontmatter และเนื้อหา Markdown Field description กำหนดว่า Claude จะเรียกใช้ Skill ของคุณเมื่อใด

ตัวอย่างโครงสร้างไดเรกทอรี:

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

สำหรับคำแนะนำที่ครบถ้วนในการสร้าง Skills รวมถึงโครงสร้าง SKILL.md, multi-file Skills, และตัวอย่าง ดู:

ข้อจำกัดของ Tool​

note

Field allowed-tools frontmatter ใน SKILL.md รองรับเฉพาะเมื่อใช้ Claude Code CLI โดยตรง ไม่ใช้งานเมื่อใช้ Skills ผ่าน SDK

เมื่อใช้ SDK ควบคุมการเข้าถึง tool ผ่าน option allowedTools ใน query configuration ของคุณ

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);
}

การค้นพบ Skills ที่พร้อมใช้งาน​

หากต้องการดูว่า Skills ใดพร้อมใช้งานใน SDK application ของคุณ เพียงถาม Claude:

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);
}

การทดสอบ Skills​

ทดสอบ Skills โดยถามคำถามที่ตรงกับคำอธิบายของมัน:

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);
}

การแก้ไขปัญหา​

ไม่พบ Skills​

ตรวจสอบ configuration settingSources: Skills ถูกค้นพบผ่าน user และ project setting sources หากคุณตั้งค่า settingSources/setting_sources อย่างชัดเจนและละเว้น sources เหล่านั้น 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 options = {
  settingSources: [],
  skills: "all"
};

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

ตรวจสอบไดเรกทอรีทำงาน: SDK โหลด Skills จาก .claude/skills/ ใน option cwd และในทุกไดเรกทอรีหลักจนถึง repository root ตรวจสอบให้แน่ใจว่า cwd ชี้ไปที่หรือต่ำกว่าไดเรกทอรีที่มี .claude/skills/:

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

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

Skill ไม่ถูกใช้งาน​

ตรวจสอบ option skills: หากคุณส่ง list skills ให้ยืนยันว่าชื่อ skill รวมอยู่ด้วย การส่ง [] จะปิดการใช้งาน skills ทั้งหมด

ตรวจสอบคำอธิบาย: ตรวจสอบให้แน่ใจว่ามีความเฉพาะเจาะจงและรวม keywords ที่เกี่ยวข้อง ดู แนวปฏิบัติที่ดีที่สุดของ Agent Skills

เอกสารที่เกี่ยวข้อง​

คู่มือ Skills​

ทรัพยากร SDK​