Agent Skills trong SDK

Tổng quan

Agent Skills mở rộng Claude với năng lực chuyên biệt mà Claude tự gọi khi phù hợp. Skills được đóng gói dưới dạng file SKILL.md chứa chỉ dẫn, mô tả, và tài nguyên hỗ trợ tùy chọn.

Để biết thông tin toàn diện về Skills, gồm lợi ích, kiến trúc, và hướng dẫn viết, xem Agent Skills overview.

Skills hoạt động thế nào với SDK

Khi dùng Claude Agent SDK, Skills:

1. Được định nghĩa như artifact filesystem: bạn tạo mỗi Skill dưới dạng một file SKILL.md trong thư mục riêng, như .claude/skills/<name>/SKILL.md
2. Được load từ filesystem: SDK load Skills từ các vị trí filesystem do settingSources (TypeScript) hay setting_sources (Python) quản lý
3. Tự động được phát hiện: một khi filesystem setting load xong, SDK phát hiện metadata của Skill khi khởi động từ thư mục người dùng và dự án, và load nội dung đầy đủ khi Claude gọi Skill
4. Do model gọi: Claude tự quyết định khi nào dùng chúng dựa trên ngữ cảnh
5. Được lọc qua tùy chọn skills: các skill đã phát hiện được bật theo mặc định. Truyền một danh sách tên skill, "all", hoặc [] để kiểm soát skill nào khả dụng trong session

Không như subagent (có thể định nghĩa theo cách lập trình), Skills phải được tạo dưới dạng artifact filesystem. SDK không cung cấp API lập trình để đăng ký Skills.

Ghi chú

Skills được phát hiện qua các filesystem setting source. Với tùy chọn query() mặc định, SDK load user và project source, nên skill trong ~/.claude/skills/, <cwd>/.claude/skills/, và .claude/skills/ ở bất kỳ thư mục cha nào của <cwd> lên tới gốc repository đều khả dụng. Nếu bạn đặt settingSources một cách tường minh, hãy đưa 'user' hay 'project' vào để giữ việc phát hiện skill, hoặc dùng tùy chọn plugins để load skill từ một đường dẫn cụ thể.

Dùng Skills với SDK

Đặt tùy chọn skills trên query() để kiểm soát Skill nào khả dụng cho session. Khi bỏ trống, các Skill đã phát hiện được bật và tool Skill khả dụng, khớp hành vi CLI. Truyền "all" để bật mọi Skill đã phát hiện, một danh sách tên Skill để chỉ bật những cái đó, hoặc [] để tắt tất cả. Khi bạn đặt skills, SDK tự động thêm tool Skill vào allowedTools. Nếu bạn cũng truyền một danh sách tools tường minh, hãy đưa "Skill" vào danh sách đó để Claude có thể gọi skill.

Một khi đã cấu hình, Claude tự động phát hiện Skills từ filesystem và gọi chúng khi phù hợp với yêu cầu của người dùng.

Ví dụ dưới đây đặt cwd thành thư mục làm việc hiện tại của process, nên hãy chạy nó từ bên trong một dự án có thư mục .claude/skills/ ở thư mục hiện tại hay bất kỳ thư mục cha nào lên tới gốc repository:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        cwd=os.getcwd(),  # .claude/skills/ ở đây hoặc thư mục cha
        setting_sources=["user", "project"],  # Load Skills từ filesystem
        skills="all",  # Bật mọi Skill đã phát hiện
        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: process.cwd(), // .claude/skills/ ở đây hoặc thư mục cha
    settingSources: ["user", "project"], // Load Skills từ filesystem
    skills: "all", // Bật mọi Skill đã phát hiện
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

Gần đầu stream, SDK trả về một system message với subtype init. Kiểm tra mảng skills của nó để xác nhận Skills của bạn đã load trước khi Claude bắt đầu làm việc. Mảng này chỉ liệt kê Skill có thể gọi bởi người dùng. Một Skill có user-invocable: false trong frontmatter vẫn load và khả dụng cho Claude nhưng không xuất hiện trong mảng.

Để chỉ bật một số Skill cụ thể, truyền tên của chúng. Tên khớp trường name trong SKILL.md hay tên thư mục của Skill. Dùng plugin:skill cho Skill do plugin cung cấp.

Ghi chú

Các câu lệnh import trong ví dụ đầu tiên được giả định có sẵn trong các đoạn code sau.

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

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

Tùy chọn skills là một bộ lọc ngữ cảnh, không phải sandbox. Skill không được liệt kê bị ẩn khỏi model và bị tool Skill từ chối, nhưng file của chúng vẫn nằm trên đĩa và có thể truy cập qua Read và Bash.

Vị trí Skill

Skills được load từ các thư mục filesystem dựa trên cấu hình settingSources/setting_sources của bạn:

• Skill dự án (.claude/skills/): chia sẻ với team qua git - được load khi setting_sources gồm "project"
• Skill người dùng (~/.claude/skills/): Skill cá nhân qua mọi dự án - được load khi setting_sources gồm "user"
• Skill plugin: đi kèm với plugin Claude Code đã cài

Tạo Skills

Tạo mỗi Skill dưới dạng một thư mục chứa một file SKILL.md với frontmatter YAML và nội dung Markdown. Trường description quyết định khi nào Claude gọi Skill của bạn.

Cấu trúc thư mục ví dụ:

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

Để biết hướng dẫn đầy đủ về tạo Skills, gồm cấu trúc SKILL.md, Skill nhiều file, và ví dụ, xem:

• Agent Skills trong Claude Code: hướng dẫn đầy đủ kèm ví dụ
• Agent Skills Best Practices: hướng dẫn viết và quy ước đặt tên

Giới hạn tool

Ghi chú

Trường frontmatter allowed-tools trong SKILL.md chỉ được hỗ trợ khi dùng Claude Code CLI trực tiếp. Nó không áp dụng khi dùng Skills qua SDK.

Khi dùng SDK, kiểm soát quyền truy cập tool qua tùy chọn allowedTools chính trong cấu hình query của bạn.

Để kiểm soát quyền truy cập tool cho Skills trong ứng dụng SDK, dùng allowedTools để duyệt trước các tool cụ thể. Không có callback canUseTool, bất cứ gì không nằm trong danh sách đều bị từ chối:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills từ filesystem
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="dontAsk",  # Từ chối bất cứ gì chưa được duyệt trước thay vì hỏi
)


async def main():
    async for message in query(prompt="Analyze the codebase structure", options=options):
        print(message)


asyncio.run(main())

for await (const message of query({
  prompt: "Analyze the codebase structure",
  options: {
    settingSources: ["user", "project"], // Load Skills từ filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk" // Từ chối bất cứ gì chưa được duyệt trước thay vì hỏi
  }
})) {
  console.log(message);
}

Khám phá Skill khả dụng

Để xem Skill nào khả dụng trong ứng dụng SDK của bạn, hãy hỏi Claude. Ví dụ dưới đây chỉ đặt tùy chọn skills và bỏ qua settingSources/setting_sources. Khi bạn không đặt settingSources/setting_sources, SDK vẫn load Skills từ user và project source, nên tùy chọn skills đặt "all" một mình cũng đủ làm chúng khả dụng để liệt kê.

options = ClaudeAgentOptions(skills="all")


async def main():
    async for message in query(prompt="What Skills are available?", options=options):
        print(message)


asyncio.run(main())

for await (const message of query({
  prompt: "What Skills are available?",
  options: {
    skills: "all"
  }
})) {
  console.log(message);
}

Claude sẽ liệt kê các Skill khả dụng dựa trên thư mục làm việc hiện tại và plugin đã cài của bạn.

Kiểm thử Skills

Kiểm thử Skills bằng cách hỏi những câu hỏi khớp với mô tả của chúng:

options = ClaudeAgentOptions(
    cwd=os.getcwd(),
    setting_sources=["user", "project"],  # Load Skills từ filesystem
    skills="all",
    allowed_tools=["Read", "Bash"],
)


async def main():
    async for message in query(prompt="Extract text from invoice.pdf", options=options):
        print(message)


asyncio.run(main())

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

Claude tự động gọi Skill phù hợp nếu mô tả khớp yêu cầu của bạn.

Xử lý sự cố

Không tìm thấy Skills

Kiểm tra cấu hình settingSources: Skills được phát hiện qua setting source user và project. Nếu bạn đặt settingSources/setting_sources tường minh và bỏ qua các source đó, skill sẽ không được load:

# Skills không được load: setting_sources loại trừ user và project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills được load: gồm cả user và project source
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)

// Skills không được load: settingSources loại trừ user và project
const optionsWithoutSkills = {
  settingSources: [],
  skills: "all"
};

// Skills được load: gồm cả user và project source
const optionsWithSkills = {
  settingSources: ["user", "project"],
  skills: "all"
};

Để biết thêm chi tiết về settingSources/setting_sources, xem TypeScript SDK reference hoặc Python SDK reference.

Kiểm tra thư mục làm việc: SDK load Skills từ .claude/skills/ trong tùy chọn cwd và mọi thư mục cha lên tới gốc repository. Đảm bảo cwd trỏ tới hoặc bên dưới thư mục chứa .claude/skills/, trong cùng repository:

# Đảm bảo cwd của bạn trỏ tới thư mục chứa .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ ở đây hoặc thư mục cha
    setting_sources=["user", "project"],  # Load skill từ các source này
    skills="all",
)

// Đảm bảo cwd của bạn trỏ tới thư mục chứa .claude/skills/
const options = {
  cwd: "/path/to/project", // .claude/skills/ ở đây hoặc thư mục cha
  settingSources: ["user", "project"], // Load skill từ các source này
  skills: "all"
};

Xem phần “Dùng Skills với SDK” ở trên để biết pattern đầy đủ.

Xác minh vị trí filesystem:

# Kiểm tra Skill dự án
ls .claude/skills/*/SKILL.md

# Kiểm tra Skill cá nhân
ls ~/.claude/skills/*/SKILL.md

Skill không được dùng

Kiểm tra tùy chọn skills: nếu bạn truyền một danh sách skills, xác nhận tên skill có nằm trong đó. Truyền [] tắt mọi skill.

Kiểm tra mô tả: đảm bảo nó cụ thể và chứa từ khoá liên quan. Xem Agent Skills Best Practices để biết hướng dẫn viết mô tả hiệu quả.

Xử lý sự cố khác

Để xử lý sự cố Skills chung (cú pháp YAML, debug, v.v.), xem phần xử lý sự cố Skills của Claude Code.

Tài liệu liên quan

Hướng dẫn Skills

• Agent Skills trong Claude Code: hướng dẫn Skills đầy đủ với cách tạo, ví dụ, và xử lý sự cố
• Agent Skills Overview: tổng quan khái niệm, lợi ích, và kiến trúc
• Agent Skills Best Practices: hướng dẫn viết Skills hiệu quả
• Agent Skills Cookbook: ví dụ Skills và template

Tài nguyên SDK

• Subagent trong SDK: agent dựa trên filesystem tương tự với tùy chọn lập trình
• Slash Command trong SDK: command do người dùng gọi
• SDK Overview: khái niệm chung về SDK
• TypeScript SDK Reference: tài liệu API đầy đủ
• Python SDK Reference: tài liệu API đầy đủ

Nguồn

Dịch và biên soạn từ Agent Skills in the SDK.