Claude Skills API Chính thức ra mắt: Có gì mới và Cách sử dụng

API Claude Skills đã được phát hành rộng rãi (GA) kể từ ngày 20 tháng 8 năm 2026. Giờ đây, bạn có thể tạo, quản lý phiên bản và điều hành các kỹ năng tùy chỉnh thông qua https://api.anthropic.com/v1/skills với các tiêu đề chuẩn, không yêu cầu cờ beta, và chạy chúng bên trong môi trường sandbox code của Claude mà không cần tự mình lưu trữ bất cứ thứ gì. Anthropic đã ra mắt phiên bản GA này cùng lúc với tính năng sử dụng máy tính, công cụ trình duyệt mới và Files API, được giới thiệu trong thông báo như là nền tảng sản xuất để xây dựng tác nhân trên Nền tảng Claude.

Nếu khái niệm kỹ năng còn mới mẻ đối với bạn, hướng dẫn về Claude Skills của chúng tôi sẽ trình bày ý tưởng từ đầu. Bài viết này tập trung vào tầng API: các endpoint, mô hình quản lý phiên bản, cấu trúc yêu cầu để tải kỹ năng vào một lời gọi Messages, và những điểm phức tạp (phạm vi workspace, phiên bản snapshot) mà GA chưa làm cho dễ dàng hơn. Vì tất cả đều là HTTP thuần túy, mỗi lời gọi ở đây có thể được xây dựng và kiểm tra hồi quy trong Apidog khi bạn thực hành theo.

button

Làm mới kiến thức trong 30 giây: kỹ năng là gì

Một kỹ năng là một thư mục. Ở cấp cao nhất của nó là một tệp SKILL.md với frontmatter YAML chứa name và description; xung quanh nó là bất kỳ script, template và tệp tham chiếu nào mà tác vụ cần. Khi một yêu cầu bao gồm kỹ năng, Claude sẽ tải các hướng dẫn chỉ khi tác vụ yêu cầu chúng, và thực thi bất kỳ script nào được đóng gói trong môi trường sandbox code của nó.

Frontmatter có các quy tắc xác thực thực tế:

name: tối đa 64 ký tự, chỉ chứa chữ cái thường, số và dấu gạch nối. Không có thẻ XML, và các từ khóa "anthropic" và "claude" bị từ chối.
description: không được trống, tối đa 1024 ký tự.
Một display_name tùy chọn (tối đa 255 ký tự) có thể thân thiện với người dùng.
Toàn bộ tải lên phải dưới 30 MB khi chưa nén.

Các kỹ năng đến từ hai nguồn. Các kỹ năng do Anthropic quản lý (type: "anthropic") được cài đặt sẵn với các ID ngắn như pptx, xlsx, docx và pdf, và sử dụng các phiên bản dựa trên ngày như 20251013. Các kỹ năng tùy chỉnh (type: "custom") là của bạn: được tải lên thông qua API, riêng tư trong workspace của bạn, với các ID được tạo tự động như skill_01AbCdEfGhIjKlMnOpQrStUv.

GA thực sự đã thay đổi những gì

Ba điều mới hoặc được củng cố kể từ ngày 20 tháng 8 năm 2026:

Không có tiêu đề beta. API Skills hoạt động trên Claude API chỉ với x-api-key và anthropic-version: 2023-06-01.
Quy trình tải lên và quản lý phiên bản đơn giản hơn. Anthropic mô tả GA mang lại “một API đơn giản hơn để tải lên và quản lý phiên bản” các kỹ năng tùy chỉnh. Các phiên bản là tài nguyên hạng nhất với các endpoint riêng.
Nhiều nền tảng hơn. API Skills có sẵn thông qua Microsoft Foundry cũng như Claude API. Các kỹ năng thực thi trong sandbox được quản lý của Claude, vì vậy không có cơ sở hạ tầng nào ở phía bạn.

Phần còn lại của làn sóng GA cũng quan trọng đối với người dùng kỹ năng: các kỹ năng thường tạo ra các tệp (bản trình bày, bảng tính đã điền), và các đầu ra đó được trả về thông qua Files API vừa được GA.

Bề mặt Endpoint

Tất cả đều nằm dưới /v1/skills:

Thao tác	Endpoint
Tạo kỹ năng	`POST /v1/skills`
Liệt kê kỹ năng	`GET /v1/skills`
Truy xuất kỹ năng	`GET /v1/skills/{skill_id}`
Xóa kỹ năng	`DELETE /v1/skills/{skill_id}`
Tạo phiên bản mới	`POST /v1/skills/{skill_id}/versions`
Liệt kê phiên bản	`GET /v1/skills/{skill_id}/versions`

Việc tạo một kỹ năng sẽ tải lên toàn bộ tập tin của nó; việc tạo một phiên bản cũng làm tương tự đối với một ID kỹ năng hiện có. Trong một dự án Apidog, điều này ánh xạ rõ ràng thành một thư mục gồm sáu yêu cầu đã lưu với {{skill_id}} và {{skill_version}} là biến môi trường, vì vậy việc đẩy một phiên bản mới qua môi trường dev và prod là thay đổi biến, chứ không phải chỉnh sửa yêu cầu.

Tải lên một kỹ năng tùy chỉnh

Một kỹ năng tùy chỉnh tối thiểu gồm hai thứ: thư mục và lời gọi tải lên. Giả sử bạn lưu một kỹ năng báo cáo thương hiệu trong repo của mình:

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

Với SKILL.md bắt đầu như sau:

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

Tải lên bằng cách gửi các tệp dưới dạng dữ liệu form multipart:

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

Phản hồi trả về skill_id được tạo và ID skver_* của phiên bản đầu tiên. Lưu cả hai; ID kỹ năng được sử dụng trong các yêu cầu Messages của bạn, và ID phiên bản là điểm neo để bạn khôi phục. Kiểm tra tên trường multipart chính xác so với tài liệu tham khảo Skills API cho phiên bản SDK của bạn, vì các trình trợ giúp SDK có kiểu dữ liệu thường bao bọc lời gọi này trong hầu hết các ngôn ngữ.

Lưu ý phần mô tả: nó giống như một quy tắc định tuyến. Claude quyết định có tải một kỹ năng hay không bằng cách đọc trường đó, vì vậy một mô tả liệt kê các cụm từ kích hoạt mà người dùng của bạn nói sẽ hiệu quả hơn một nhãn một dòng mọi lúc.

Sử dụng kỹ năng trong yêu cầu Messages

Các kỹ năng không tự động gắn vào một yêu cầu. Chúng hoạt động thông qua công cụ thực thi mã, được khai báo qua tham số container:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Các quy tắc chi phối khối này:

Công cụ thực thi mã phải được bật trong tools, vì các kỹ năng thực thi bên trong sandbox đó. Hỗ trợ mô hình tuân theo danh sách tương thích của công cụ thực thi mã.
Tối đa 20 kỹ năng mỗi yêu cầu. Claude đọc mô tả của mỗi kỹ năng và chỉ tải các hướng dẫn cho những kỹ năng mà tác vụ cần.
Việc ghim phiên bản là do bạn kiểm soát. "latest" trỏ đến phiên bản mới nhất; một ID skver_* được ghim (hoặc phiên bản ngày cho các kỹ năng của Anthropic) sẽ cố định hành vi. Ghim trong môi trường sản xuất, sử dụng "latest" trong môi trường phát triển.

Khi một kỹ năng tạo ra một tài liệu, phản hồi sẽ mang theo một file_id mà bạn tải xuống thông qua Files API bằng GET /v1/files/{file_id}/content. Sự bắt tay hai API đó (Skills để tạo, Files để truy xuất) là vòng lặp sản xuất cốt lõi.

Quản lý phiên bản: ảnh chụp, không phải khác biệt

Mô hình quản lý phiên bản là phần mà hầu hết các nhóm thường mắc lỗi ở lần thử đầu tiên. Một phiên bản mới là một ảnh chụp hoàn chỉnh, không phải là một sự khác biệt (delta). Khi bạn POST /v1/skills/{skill_id}/versions, bạn tải lên toàn bộ tập tin của kỹ năng một lần nữa; các tệp bạn bỏ qua sẽ không được chuyển từ phiên bản trước. `name` trong SKILL.md của phiên bản mới cũng phải khớp với tên hiện có của kỹ năng.

Coi các thư mục kỹ năng như các tạo phẩm xây dựng: giữ nguồn đáng tin cậy trong kho lưu trữ của bạn, đóng gói toàn bộ thư mục trong CI, và đẩy nó như một phiên bản mới. Việc khôi phục sau đó trở nên đơn giản, vì các phiên bản cũ vẫn có thể truy cập được bằng ID skver_* của chúng và một sự cố sản xuất có thể được khắc phục bằng cách ghim lại một chuỗi.

Phạm vi workspace: bẫy đa người thuê

Các kỹ năng tùy chỉnh có thể truy cập được bởi toàn bộ workspace của bạn. Chúng không được giới hạn theo người dùng cuối, cuộc trò chuyện, hoặc phiên, và mọi khóa API trong workspace đều chia sẻ chúng. Nếu bạn điều hành một sản phẩm đa người thuê mà trong đó các người thuê tải lên kỹ năng của riêng họ, một workspace duy nhất có thể dẫn đến rò rỉ dữ liệu.

Cách khắc phục tương tự như đối với Files API: tạo một workspace riêng cho mỗi người thuê. Workspace là ranh giới cách ly, và mỗi tổ chức được tối đa 100 workspace trước khi cần liên hệ với đội ngũ tài khoản. Khóa, tệp và kỹ năng đều thừa hưởng ranh giới đó, vì vậy một quyết định sẽ cách ly cả ba.

Kỹ năng chạy dài: pause_turn và tái sử dụng container

Việc thực thi kỹ năng có thể kéo dài hơn một lượt mô hình duy nhất. Hai cơ chế xử lý điều này:

pause_turn: khi một phản hồi dừng với stop_reason: "pause_turn", hãy thêm nội dung của trợ lý vào lịch sử tin nhắn của bạn và gọi lại, chuyển cùng một container.id. Sandbox sẽ tiếp tục từ nơi nó đã dừng.
Tái sử dụng Container: đối tượng container chấp nhận một id từ một phản hồi trước đó, giữ cho các tệp đã cài đặt và trạng thái tồn tại trong suốt một cuộc trò chuyện nhiều lượt. Điều đó có nghĩa là một kỹ năng có thể xây dựng một bảng tính ở lượt đầu tiên và sửa đổi nó ở lượt thứ ba mà không cần tạo lại từ đầu.

Cả hai mẫu đều là các chuỗi HTTP có trạng thái, điều này khiến chúng khó kiểm tra thủ công nhưng dễ chịu khi kiểm tra như một kịch bản Apidog: yêu cầu một xác nhận stop_reason, một script nâng container.id thành một biến, yêu cầu hai tái sử dụng nó, và bước cuối cùng xác nhận file_id được tạo tải xuống sạch sẽ. Apidog CLI chạy cùng một kịch bản trong CI, vì vậy việc tăng phiên bản kỹ năng không thể âm thầm phá vỡ pipeline của bạn. Nếu bạn muốn xem cách các kỹ năng hoạt động trong hệ sinh thái của nhà cung cấp khác để so sánh, chúng tôi đã phân tích kỹ năng Claude của Postman trong một bài đánh giá trước đó.

Nơi nó chạy

Tại GA, API Skills có sẵn trên Claude API và thông qua Microsoft Foundry. Các kỹ năng thực thi trong sandbox của Anthropic bất kể, vì vậy "triển khai" là một quá trình tải lên, và không có hình ảnh container, không có vá lỗi runtime, và không có nút điều chỉnh quy mô nào ở phía bạn. Lưu ý sự phụ thuộc vào mô hình hơn là nền tảng: yêu cầu phải sử dụng một mô hình mà công cụ thực thi mã hỗ trợ, chẳng hạn như claude-opus-5 trong các ví dụ trên. Hướng dẫn API Claude Opus 5 của chúng tôi bao gồm các kiến thức cơ bản về yêu cầu của mô hình đó nếu bạn mới bắt đầu.

Câu hỏi thường gặp

Tôi có còn cần tiêu đề beta cho skills không? Không. Kể từ ngày 20 tháng 8 năm 2026, /v1/skills và tham số container.skills hoạt động với các tiêu đề chuẩn trên Claude API. Gỡ bỏ bất kỳ cờ beta nào đã ghim khi bạn nâng cấp SDK của mình.

Một kỹ năng có thể gọi các API bên ngoài khi nó đang chạy không? Các kỹ năng thực thi bên trong sandbox code của Claude với các ràng buộc mạng của công cụ thực thi mã. Đóng gói những gì kỹ năng cần trong thư mục của nó thay vì giả định rằng có thể truy cập mạng bên ngoài tự do, và giữ logic gọi API trong tầng ứng dụng của bạn nơi bạn có thể kiểm tra nó một cách đúng đắn.

Một yêu cầu có thể tải bao nhiêu kỹ năng? Tối đa 20. Claude đọc description frontmatter của mỗi kỹ năng để quyết định kỹ năng nào mà tác vụ cần, vì vậy các mô tả rất quan trọng: hãy viết chúng như các quy tắc định tuyến, không phải là lời quảng cáo.

Sự khác biệt giữa điều này và kỹ năng Claude Code là gì? Cùng một khái niệm, thời gian chạy khác nhau. Claude Code khám phá các thư mục kỹ năng trên hệ thống tệp của bạn; API Skills lưu trữ chúng trên máy chủ, có phiên bản, cho các lời gọi API Messages. Định dạng thư mục với SKILL.md frontmatter được chia sẻ, vì vậy một kỹ năng bạn viết cho Claude Code thường có thể chuyển đổi với ít thay đổi.

Tổng kết

GA biến kỹ năng từ một thử nghiệm thành một bề mặt vận hành: sáu endpoint, quản lý phiên bản ảnh chụp, cách ly workspace và chuyển giao sạch sẽ sang Files API cho các đầu ra. Các nhóm đạt được giá trị nhanh nhất coi kỹ năng như bất kỳ tạo phẩm có thể triển khai nào khác, điều này có nghĩa là đóng gói CI, các phiên bản được ghim trong môi trường sản xuất và các kiểm thử tự động xung quanh vòng đời của container. Mô hình hóa sáu endpoint trong Apidog, kết nối việc tăng phiên bản vào một kịch bản kiểm thử, và bạn sẽ biết một phiên bản kỹ năng bị lỗi đã phá vỡ trình tạo bản trình bày của bạn trước khi người dùng của bạn nhận ra. Tải Apidog miễn phí và xây dựng bộ công cụ trong một buổi chiều.