Bởi Chia sẻ agent skill giữa repo không bị lệch bản
Đừng copy skill vào 8 repo rồi để bản sao lệch nhau. Học cách dùng một repo chung, pin version, thêm smoke test và review mỗi lần bump.
Cách chia sẻ skill của agent giữa các repository
Để chia sẻ skill của agent giữa các repository, hãy ngừng sao chép file và bắt đầu quản lý dependency đến file đó. Duy trì một repository chứa skill dùng chung, tạo tag cho repository này và để mỗi project pin một tag. Sau đó thêm một smoke test cho từng skill và review mỗi lần bump giống như khi review bump của một dependency.
Quy trình này gồm 4 phần: một nguồn chuẩn dùng chung, một phiên bản được pin cho từng repository, một smoke test cho từng skill và quy trình review. Các phần dưới đây giải thích lý do tồn tại của từng phần, những gì các công cụ được phát hành trong 2026 hỗ trợ, và cách xây dựng toàn bộ quy trình trên một git remote tự host mà không cần dịch vụ bên ngoài.
Agent skill là một thư mục chứa file SKILL.md cùng các script và file tham chiếu cần thiết. Nếu khái niệm này còn mới, trước tiên hãy đọc agent skill là gì và SKILL.md hoạt động như thế nào. Trang này tập trung vào supply chain xoay quanh đơn vị đó.
Vị trí của skill và lý do khó chia sẻ
Claude Code tải skill từ ba vị trí, và tài liệu về skill liệt kê từng đường dẫn.
~/.claude/skills/<skill-name>/SKILL.mdlà cấp cá nhân. Nó được tải trong tất cả project của bạn, nhưng không được tải trong project của người khác..claude/skills/<skill-name>/SKILL.mdlà cấp project. Nó được tải cho bất kỳ ai checkout repository đó.<plugin>/skills/<skill-name>/SKILL.mdnằm bên trong plugin. Nó được tải ở bất kỳ nơi nào plugin đó được bật.
Vị trí thứ hai hữu ích cho team vì nội dung được commit và mọi người clone repo đều nhận được. Đây cũng là nơi vấn đề bắt đầu. Một skill trong .claude/skills/ thuộc về một repository. Bạn có tám repository. Vì vậy, skill đó bị sao chép tám lần.
Frontmatter không giúp được việc này. Đặc tả Agent Skills cho phép sáu key, và các cơ chế phân phối thực thi đặc tả này sẽ in danh sách khi bạn dùng một key khác:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameHãy chú ý key bị thiếu: không có key version. File không ghi lại bản sao nào mới hơn. Điều này hợp lý vì skill là một tài liệu, không phải package. Tuy nhiên, việc versioning phải do lớp bên ngoài file đảm nhiệm, và lớp đó là trách nhiệm của bạn.
Vấn đề một: tám bản sao âm thầm lệch nhau
Copy-paste hoạt động tốt trong ngày đầu tiên. Đến ngày thứ 60 thì bắt đầu hỏng. Một người sửa hướng dẫn sai trong repo payments nhưng không cập nhật 7 bản còn lại. Một người khác thêm quy tắc về phân trang vào orders. Bây giờ, cùng một tên skill có thể cho ra 2 kết quả review khác nhau, tùy agent khởi động từ thư mục nào, và không developer nào biết điều đó.
Lỗi này diễn ra âm thầm vì không có trạng thái lỗi. Skill là nội dung dạng văn bản. Hướng dẫn đã cũ tạo ra câu trả lời tự tin nhưng sai; đây là loại lỗi tốn kém nhất. Agent không so sánh bản sao của bạn với bản sao của người khác, nên tín hiệu duy nhất là có người nhận ra 2 repo không đồng nhất.
Vấn đề 2: không có gì ghim version
Ngay cả khi team lưu skills tại một nơi duy nhất, cách chia sẻ thông thường vẫn là một bước copy: một setup script, một dòng curl trong tài liệu onboarding hoặc một shell alias để đồng bộ một thư mục. Tất cả các cách này đều cài version hiện đang ở đầu branch.
Điều đó có nghĩa là hai developer dùng cùng một commit của cùng một ứng dụng vẫn có thể đang chạy các instruction khác nhau, vì họ thực hiện đồng bộ vào những ngày khác nhau. Điều đó cũng có nghĩa là bạn không thể trả lời câu hỏi quan trọng sau một lần agent chạy lỗi: skill nào đã tạo ra kết quả này? Nếu không ghi lại revision, lần chạy đó không thể tái lập, nên báo lỗi không có đủ thông tin để xử lý.
Vấn đề thứ ba: không ai biết skill vẫn còn hoạt động
Skill không có compiler. Đây là các instruction hướng dẫn model, nên skill có thể ngừng hoạt động dù file vẫn giống hệt từng byte. Việc nâng cấp model có thể làm thay đổi mức độ tuân thủ một instruction dài. Một command-line tool mà skill gọi có thể đổi tên một flag. URL trong file tham chiếu có thể bắt đầu trả về 404, khiến agent xử lý dựa trên trang lỗi.
Không trường hợp nào trong số đó gây lỗi rõ ràng. Agent vẫn trả lời. Chỉ là câu trả lời kém hơn so với tháng trước, và rất khó nhận ra điều này khi xem từng pull request riêng lẻ.
Các công cụ phát hành trong 2026 giải quyết vấn đề gì
Hiện đã có một số hướng giải quyết, nhưng chúng chưa thống nhất về nơi lưu version.
Lockfile. Công cụ dòng lệnh skills của Vercel Labs (vercel-labs/skills, cấp phép MIT, v1.5.22 tính đến ngày 5 August 2026) cài skill từ git repository vào thư mục mà agent của bạn yêu cầu, đồng thời biết layout của hơn bảy mươi agent. npx skills add <repo> dùng để cài đặt, npx skills update dùng để nâng cấp và npx skills list dùng để xem các skill hiện có. Danh sách những gì đã cài được lưu một lần cho mỗi user thay vì một lần cho mỗi repository. Một request đang mở trong project đó (issue 283) đề nghị thêm lệnh skills install để cài lại mọi skill được ghi trong lockfile, nhằm bảo đảm máy thứ hai có cùng một tập skill. Hãy xem request đó như một báo cáo trạng thái. Ý tưởng lockfile đã được xác lập. Phần dành cho từng project vẫn đang được xây dựng.
Spec và test. SkillSpec tiếp cận theo hướng khác. Nó xem SKILL.md là một contract cần kiểm tra thay vì prose để tin tưởng, với mục tiêu được nêu là làm cho skill "có thể làm theo, kiểm thử và chứng minh". skillspec doctor <path> báo cáo những chỗ agent có khả năng mất mạch. skillspec boundary map <path> báo cáo những tài nguyên skill có thể truy cập, còn skillspec boundary assess <path> xếp hạng các phát hiện đó theo mức rủi ro. Đây là một Rust crate, được cấp phép kép theo MIT hoặc Apache 2.0, ở version 0.2.2 tính đến ngày 29 July 2026. Hãy cài version cố định thay vì version mới nhất:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked build với các version dependency mà crate đã được phát hành cùng, nên quá trình build không tự thay đổi theo thời gian. skillspec --version phải in ra 0.2.2. Nếu ra số khác, một binary cũ hơn trong PATH của bạn đang được ưu tiên.
Thực hành của vendor. Google mô tả cách xây dựng các skill trong google/skills qua bài viết về cách xây dựng, kiểm thử và mở rộng quy mô agent skill. Nếu bỏ qua quy mô, cơ chế này chỉ là continuous integration (CI) thông thường. Trước khi được merge, mọi skill đều phải vượt qua các linter kiểm tra metadata frontmatter, số dòng, layout thư mục và quy tắc đặt tên. Link checker sẽ làm build fail nếu bất kỳ URL nào trả về 404, qua đó phát hiện các link có vẻ hợp lệ nhưng agent đã tự tạo. Tác giả phải cung cấp bộ evaluation prompt và scoring rubric cùng với skill. Các job evaluation theo lịch sẽ chạy hằng tuần trên toàn bộ thư viện để phát hiện regression. Mỗi skill cũng có một owner được chỉ định và người này phải khắc phục khi chất lượng giảm.
Mẫu hình nằm dưới cả ba câu trả lời
Bạn không cần chọn một trong ba cách đó. Bên dưới chúng là một cấu trúc duy nhất, và git thuần cung cấp đầy đủ cấu trúc này.
- Một nguồn sự thật duy nhất. Skill chỉ có đúng một nơi lưu trữ, và mọi repository đều tham chiếu đến nơi đó thay vì giữ một bản sao.
- Một phiên bản được ghim cho mỗi repository. Mỗi project ghi lại revision chính xác mà nó sử dụng, vì vậy việc nâng cấp là một commit trong project đó, có tác giả và ngày tháng.
- Một smoke test cho mỗi skill. Một kiểm tra có thể chạy để chứng minh skill vẫn tạo ra kết quả mà nó cam kết.
- Một quy trình review. Thay đổi đối với skill dùng chung phải được review, và mọi consumer đều thấy diff trước khi tiếp nhận thay đổi.
Đó chính là cấu trúc của một dependency. Skill trở thành artifact dùng chung nhanh hơn tốc độ phát triển của tooling xung quanh nó, vì vậy dùng những công cụ mà bạn đã tin cậy là lựa chọn an toàn nhất.
Bố cục cho một nhóm nhỏ dùng git remote tự host
Một repository chứa các skill. Không có nội dung nào khác trong đó, nên history của repository chính là changelog của các instruction.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdRelease là các tag. Hãy dùng annotated tag vì chúng chứa message và ngày tạo. Viết message theo lý do mà consumer muốn nâng phiên bản:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Nếu remote của bạn là Gitea, Forgejo, GitLab hoặc một bare repository qua SSH trên VPS của bạn, các bước tiếp theo vẫn không thay đổi. Toàn bộ quy trình chỉ dùng git và một symlink.
Ghim phiên bản bằng git submodule
Một submodule ghi lại chính xác một commit của repository khác bên trong repository của bạn. Bản ghi đó là phiên bản được ghim. Trong mỗi project sử dụng submodule:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"Symlink là thành phần giúp cách này hoạt động. Một mục skill ở cấp project có thể là symlink trỏ đến một thư mục ở vị trí khác trên disk, và Claude Code sẽ đi theo symlink đó rồi đọc SKILL.md từ thư mục đích. Vì vậy, skill được nạp như một project skill thông thường, còn các byte nằm trong submodule tại commit bạn đã chọn.
Kiểm tra phiên bản được ghim:
git submodule statusMột dòng hợp lệ bắt đầu bằng một dấu cách, tiếp theo là commit, path rồi tag gần nhất:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)- ở đầu dòng có nghĩa là submodule chưa từng được khởi tạo, nên .claude/skills/api-review không trỏ đến đâu và skill sẽ không được nạp mà không báo lỗi. Khắc phục bằng git submodule update --init. + ở đầu dòng có nghĩa là commit đã checkout khác với commit được ghi nhận, nên developer đó đang chạy các chỉ dẫn mà không ai khác có. Clone mới cần git clone --recurse-submodules, và dòng đó phải nằm trong README, vì clone thông thường để vendor/agent-skills rỗng và không in ra lỗi.
Việc nâng cấp được thực hiện có chủ đích. Đó là mục đích chính của cách này:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"Dòng diff là đường dẫn để review. Dòng này cho thấy chính thay đổi mà mọi repo sử dụng khác sẽ nhận được, đồng thời phù hợp để đưa vào một pull request.
Thay bằng pinning với plugin marketplace
Nếu không muốn yêu cầu mọi developer học cách dùng submodule, hệ thống plugin của Claude Code sẽ tự phân phối cho bạn và hoạt động với remote tự host. Đặt catalog tại .claude-plugin/marketplace.json trong repository skills:
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}Ở đây có hai source khác nhau, và nhầm lẫn giữa chúng là lỗi phổ biến. Marketplace source, tức nơi catalog được fetch, chấp nhận ref cho branch hoặc tag và không chấp nhận sha. Plugin source bên trong catalog chấp nhận cả hai. Khi đặt cả hai, sha là pin có hiệu lực. Vì vậy, exact-commit pin phải nằm trong mục catalog.
Mỗi repository sử dụng sau đó khai báo marketplace trong .claude/settings.json đã commit:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Teammate tin cậy project folder sẽ được nhắc cài marketplace. Plugin sẽ được enable cho họ mà không cần một trang wiki hướng dẫn thao tác này. Các skills sau đó được gọi bằng /team-skills:api-review, vì plugin skills được namespace theo tên plugin và không thể xung đột với project skill cùng tên. Sau khi push tag mới, các repository sử dụng refresh bằng /plugin marketplace update acme-agents, rồi chạy /reload-plugins nếu phần tóm tắt cài đặt yêu cầu.
Viết smoke test cho một skill
Smoke test là một lần chạy agent được viết bằng script trên một fixture có lỗi đã biết, kèm theo một assertion. Claude Code chạy ở chế độ không tương tác với -p, và skill được người dùng gọi hoạt động trong chế độ đó: đặt /skill-name vào chuỗi prompt để nó được mở rộng trước khi lần chạy bắt đầu.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md là một file ngắn có một lỗi được cài chủ ý. Assertion kiểm tra skill có nêu đúng lỗi đó hay không. jq -e thoát với mã khác 0 khi bộ lọc của nó tạo ra null, vì vậy script sẽ thất bại nếu skill không còn bắt được lỗi đã cài. Bản thân claude thoát với mã khác 0 khi lần chạy thất bại, còn set -euo pipefail chuyển một trong hai lỗi đó thành test thất bại.
Model có thể diễn đạt lại câu trả lời giữa các lần chạy, vì vậy không bao giờ kiểm tra cả một câu. Hãy kiểm tra một identifier mà skill phải xuất ra, hoặc một field trong schema mà bạn yêu cầu. Giữ fixture nhỏ để lần chạy không tốn nhiều tài nguyên.
Trong CI, hãy thêm --bare. Nếu không có tùy chọn này, claude -p sẽ nạp cùng context như một phiên tương tác, bao gồm hooks, plugins và CLAUDE.md từ máy đang chạy. Vì vậy, cấu hình cá nhân của một thành viên trong nhóm có thể làm thay đổi kết quả. Chế độ bare bỏ qua toàn bộ quá trình tự động phát hiện. Điều đó cũng khiến skill bạn đang kiểm thử bị bỏ qua, nên hãy nạp riêng skill đó. Chế độ bare cũng không đọc thông tin đăng nhập subscription của bạn, vì vậy trước tiên hãy đặt ANTHROPIC_API_KEY trong environment:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format jsonVới --output-format stream-json, event đầu tiên của lần chạy sẽ báo những plugin nào đã được nạp và chứa một mảng plugin_errors cho các plugin chưa được nạp. Hãy làm cho job CI thất bại khi plugin_errors không rỗng. Cách này phát hiện trường hợp pin trỏ đến một revision không còn tồn tại; nếu không, agent có thể âm thầm bỏ qua các quy tắc nội bộ của bạn.
Một skill dùng chung là instruction có thể thực thi
Hai tính năng khiến điều này đúng theo nghĩa đen, và cả hai đều quan trọng khi file đến từ team khác.
Thứ nhất, một SKILL.md có thể chạy shell command trước khi model đọc bất kỳ nội dung nào. Một dòng như sau trong phần nội dung là bước preprocessing:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Command chạy trên máy đang load skill, rồi output của nó thay thế placeholder trong phần text mà model nhận được. Một fenced block mở bằng ba backtick và theo sau là ! cũng chạy nhiều command theo cách tương tự. Không ai phải approve các thao tác này tại thời điểm chạy. Đọc một skill dùng chung cũng có nghĩa là đọc các command substitution của nó.
Thứ hai, frontmatter có thể pre-approve tool. allowed-tools cấp quyền cho các tool được liệt kê mà không hiện permission prompt trong lượt gọi skill đó. Với project skill, quyền này có hiệu lực sau khi ai đó chấp nhận workspace trust dialog cho folder. Tài liệu Claude Code nêu rõ hệ quả: hãy review project skill trước khi trust một repository, vì skill có thể tự cấp cho mình quyền truy cập tool rất rộng.
Vì vậy, hãy xử lý việc nâng version skill giống hệt việc nâng version dependency. Khi cơ chế cho phép, hãy pin bằng exact commit, vì tag có thể bị di chuyển còn branch thì mặc định luôn thay đổi. Trên máy bị hạn chế quyền, "disableSkillShellExecution": true trong settings sẽ thay mọi command substitution bằng text literal [shell command execution disabled by policy] thay vì chạy chúng; khi được áp dụng qua managed settings, user không thể override thiết lập này. Bundled skill và managed skill không bị ảnh hưởng bởi setting đó.
Cần thận trọng tương tự với dữ liệu mà skill đọc. Một skill chạy env hoặc mở một config file sẽ đưa mọi thứ nó tìm thấy vào context của model. Đây chính là lỗi được đề cập trong giữ secret ngoài các agent bạn chạy.
Cần đọc gì khi tăng version
- Diff của toàn bộ phần thân
SKILL.md, vì nội dung đó là hướng dẫn agent sẽ thực hiện. - Mọi phép thay thế lệnh, vì chúng chạy trên máy của bạn khi skill được tải.
- Mọi thay đổi đối với
allowed-tools, vì dòng đó cấp quyền dùng tool mà không cần prompt. - Lần chạy test gắn với tag. Nếu repository dùng chung tự chạy smoke test trong CI, tag bạn pin phải có một lần chạy thành công đi kèm.
Nếu reviewer không thể đọc toàn bộ diff trong mười phút, skill đó đã phát triển quá lớn. Hãy tách nó ra. Lập luận tương tự áp dụng cho các tài liệu trong repository mà agent đọc: giữ các quy tắc lâu dài trong những file được mô tả ở phần tách AGENTS.md và HUMAN.md, đưa phần giải thích kiến trúc vào một file DESIGN.md viết cho agent, và giữ skill ở dạng các quy trình hẹp.
Khi thay đổi model hoặc tool làm hỏng một skill
Có nhiều thành phần bên dưới một skill thay đổi mà không ai chỉnh sửa skill đó. Một lần nâng cấp model có thể làm thay đổi mức độ tuân thủ ổn định đối với instruction dài. Khi đó, một skill phụ thuộc vào việc model thực hiện đến bước chín có thể không bao giờ đi đến bước này nữa. Một command line tool đổi tên flag. Agent vẫn chạy flag cũ, đọc lỗi rồi tự xử lý theo cách khác. Một URL được tham chiếu bắt đầu trả về 404. Agent harness thay đổi cách chọn skill, nên một description trước đây khớp tốt nhất có thể không còn được chọn.
Đó là lý do smoke test có vai trò quan trọng trong cách tổ chức này. Hãy chạy test của từng skill theo lịch định kỳ và mỗi khi push. Google chạy các job đánh giá hằng tuần trên toàn bộ thư viện vì lý do này. Với một team có mười skill, một cron job hằng tuần trên một VPS nhỏ là đủ. Đây là cách duy nhất để bạn phát hiện lỗi trước khi developer phát hiện ra.
Tính portable cũng hữu ích. Agent Skills spec chỉ dùng sáu key trong frontmatter. Vì vậy, một skill viết theo spec này có thể được load trong nhiều tool khác ngoài tool mà bạn viết skill đó. Ngược lại, mỗi key riêng của harness mà bạn thêm vào đều là một lựa chọn phụ thuộc vào một vendor. Viết skill có thể hoạt động sau khi đổi model là một kỹ năng riêng. Nội dung này được trình bày trong cách làm cho skill hoạt động trên mọi model.
FAQ
Làm thế nào để dùng chung một agent skill cho nhiều repository?
Đặt skill trong một git repository riêng, tạo tag cho các bản phát hành, rồi để mỗi project sử dụng tham chiếu đến một tag thay vì sao chép file. Có 2 cơ chế phù hợp. Git submodule ghi lại một commit cụ thể, còn symlink từ .claude/skills/<name> vào submodule giúp skill được nạp như skill thông thường của project. Plugin marketplace thực hiện chức năng tương tự thông qua /plugin, với pin được khai báo trong .claude/settings.json của repository sử dụng. Cả 2 cơ chế đều lưu version trong lịch sử git, nên bạn có thể xác định instruction nào đã tạo ra một lần chạy agent cụ thể.
Có thể pin một agent skill vào version cụ thể không?
Không thể thực hiện từ bên trong SKILL.md, vì frontmatter đó không có key version. Pin phải được thiết lập ở lớp bao quanh file. Git submodule mặc định pin vào một commit cụ thể. Trong Claude Code plugin marketplace, plugin source chấp nhận ref cho branch hoặc tag và sha cho commit cụ thể; khi cả 2 cùng xuất hiện, sha được ưu tiên. Bản thân marketplace source chỉ chấp nhận ref. Nên ưu tiên pin bằng commit, vì tag có thể bị di chuyển sau khi bạn đã review.
Smoke test cho skill nên kiểm tra điều gì?
Hãy kiểm tra một kết quả ổn định. Chạy skill ở chế độ non-interactive với một fixture chứa lỗi đã biết, rồi kiểm tra xem một identifier cụ thể có xuất hiện trong output hay không, chẳng hạn rule id mà skill phải báo cáo. Yêu cầu structured output bằng --output-format json và --json-schema giúp phép kiểm tra chính xác, còn jq -e sẽ làm script fail khi không tìm thấy giá trị. Không bao giờ kiểm tra một câu hoàn chỉnh, vì model có thể diễn đạt lại câu trả lời giữa các lần chạy.
Cài shared skill từ repository của team khác có an toàn không?
Hãy xem nó như một code dependency, vì đây là instruction có thể thực thi. Một SKILL.md có thể chạy shell command khi được load thông qua dạng command substitution !, còn field allowed-tools trong frontmatter có thể tự động cho phép trước các tool mà không cần prompt. Hãy đọc diff sau mỗi lần bump, pin vào một commit cụ thể thay vì branch, và ưu tiên source do team của bạn kiểm soát. Trên các máy được quản lý tập trung, "disableSkillShellExecution": true trong settings sẽ ngăn hoàn toàn việc chạy command substitution.
Shared skill có hoạt động với agent không phải Claude Code không?
Điều đó phụ thuộc vào các key frontmatter bạn sử dụng. Agent Skills spec định nghĩa 6 key: name, description, license, compatibility, metadata và allowed-tools. Skill chỉ dùng các key đó sẽ được nạp trên những tool triển khai spec, đồng thời cũng hoạt động trong Claude Code mà không cần thay đổi. Các key và tính năng trong phần body dành riêng cho từng harness, nếu vượt ra ngoài spec, có thể bị bỏ qua hoặc bị từ chối ở nơi khác. Vì vậy, không nên đưa chúng vào skill mà bạn dự định chia sẻ rộng rãi.