Bởi Matt Connor
Cách chia sẻ kỹ năng agent giữa các repository hiệu quả
Đừng sao chép file kỹ năng agent gây ra lỗi drift. Hãy quản lý chúng như dependency bằng cách dùng một repo chung, pin phiên bản cụ thể và chạy smoke test để kiểm soát.
Cách chia sẻ kỹ năng agent giữa các repository
Để chia sẻ kỹ năng agent giữa các repository, hãy ngừng việc sao chép file và bắt đầu thiết lập sự phụ thuộc vào nó. Hãy duy trì một repository chứa các kỹ năng, gắn tag cho nó và để mỗi dự án pin một tag cụ thể. Sau đó, thêm một bài kiểm tra smoke test cho mỗi kỹ năng và review mọi bản cập nhật giống như cách bạn review một dependency.
Quy trình này gồm bốn phần: một nguồn tin cậy duy nhất (shared source of truth), một phiên bản được pin cho mỗi repository, một bài kiểm tra smoke test cho mỗi kỹ năng và một quy trình review. Nội dung dưới đây giải thích lý do tồn tại của từng phần, cách các công cụ được phát hành trong năm 2026 xử lý vấn đề này và cách xây dựng toàn bộ hệ thống trên một git remote tự host mà không cần bất kỳ git host hoặc package registry bên ngoài nào. Các bài kiểm tra smoke test là ngoại lệ duy nhất. Chúng chạy Claude Code, gửi mọi request đến một model API, vì vậy bước đó vẫn yêu cầu kết nối ra ngoài server của bạn.
Một kỹ năng agent là một thư mục chứa file SKILL.md, cùng với bất kỳ script và file tham chiếu nào cần thiết. Nếu đơn vị đó là mới, hãy đọc kỹ năng agent là gì và cách SKILL.md hoạt động trước. Trang này tập trung vào chuỗi cung ứng xoay quanh đơn vị đó.
Vị trí của skill và lý do khó chia sẻ
Claude Code tải skill từ các vị trí sau, cùng với một số vị trí khác; tài liệu về skill liệt kê từng đường dẫn.
.claude/skills/<skill-name>/SKILL.mdbên trong thư mục settings được quản lý là vị trí dành cho doanh nghiệp. Skill được tải cho mọi người dùng trên các máy mà tổ chức triển khai nó.~/.claude/skills/<skill-name>/SKILL.mdlà vị trí cá nhân. Skill được tải trong tất cả project của bạn và không được tải trong project của người khác..claude/skills/<skill-name>/SKILL.mdlà vị trí cấp project. Skill được tải cho bất kỳ ai checkout repository đó.<plugin>/skills/<skill-name>/SKILL.mdnằm bên trong một plugin. Skill được tải ở mọi nơi plugin đó được bật.
Claude Code cũng tải skill từ các thư mục project lồng nhau, các thư mục được cung cấp bằng --add-dir và các skill được bật cho tài khoản claude.ai của bạn.
Vị trí cấp project là lựa chọn hữu ích cho team vì nội dung được commit, nên mọi người clone repo đều nhận được. Đây cũng là nơi vấn đề bắt đầu. Skill trong .claude/skills/ thuộc về một repository. Bạn có tám repository. Vì vậy, skill được sao chép tám lần.
Frontmatter không giúp được gì. Đặc tả Agent Skills cho phép sáu key, và các đường dẫn phân phối thực thi đặc tả này sẽ in danh sách đó khi bạn sử 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ú ý phần còn thiếu: không có key version. Không có nội dung nào bên trong file 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 một package. Tuy nhiên, việc versioning phải do lớp bên ngoài file đảm nhiệm, và lớp đó là phần việc 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ì hỏng. Một người sửa hướng dẫn sai trong repo payments nhưng không cập nhật bảy 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 lại cho ra hai kết quả review khác nhau, tùy agent được khởi chạy từ thư mục nào. Không developer nào biết điều đó.
Lỗi này không biểu hiện rõ 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 một câu trả lời tự tin nhưng sai, và đây là loại lỗi tốn kém nhất. Agent không so sánh bản copy của bạn với bản copy của người khác. Vì vậy, tín hiệu duy nhất là một người phát hiện hai repo không khớp nhau.
Vấn đề thứ hai: không cố định version
Ngay cả khi team lưu trữ các skill tại một nơi, cách chia sẻ phổ biến vẫn là một bước copy: script setup, một dòng curl trong tài liệu onboarding hoặc một shell alias để đồng bộ thư mục. Tất cả các cách này đều cài phiên bản 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 application 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 cáo bug không đủ thông tin để xử lý.
Vấn đề ba: không ai biết skill còn hoạt động hay không
Skill không có compiler. Đây là tập chỉ dẫn dành cho model, nên skill có thể ngừng hoạt động trong khi file vẫn giữ nguyên từng byte. Việc nâng cấp model có thể thay đổi mức độ model tuân thủ một chỉ dẫn dài. Một công cụ dòng lệnh mà skill gọi có thể đổi tên một flag. Một URL trong file tham chiếu có thể bắt đầu trả về 404, khiến agent làm việc dựa trên trang lỗi.
Không trường hợp nào trong số này 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ếu chỉ xem từng pull request một.
Các công cụ phát hành trong năm 2026 giải quyết vấn đề gì
Hiện đã có một số câu trả lời được đưa ra, nhưng chúng không 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 cấp phép MIT, phiên bản v1.7.2 tính đến ngày 9 October 2026) cài skill từ mộ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> thực hiện cài đặt, npx skills update nâng cấp và npx skills list hiển thị những gì bạn đã cài. Công cụ này duy trì hai lock file. Lock file global tại ~/.agents/.skill-lock.json ghi lại những gì một user đã cài. Từ v1.4.1 (20 February 2026), việc cài đặt trong phạm vi project cũng ghi skills-lock.json tại thư mục gốc của project, và source code của công cụ cho biết file này được thiết kế để commit vào version control. npx skills experimental_install khôi phục skill của project từ file đó. Issue 283, yêu cầu có lệnh skills install để khôi phục global lock file trên một máy khác, đã được đóng với trạng thái không triển khai vào ngày 5 November 2026; maintainer xác định đây là cùng một yêu cầu với issue 549. Hãy đọc cả hai như một báo cáo trạng thái. Lockfile theo từng project đã tồn tại. Lệnh khôi phục từ lockfile đó vẫn được gắn nhãn experimental trong bản v1.7.6 đã phát hành; main branch của project hiện cũng hỗ trợ npx skills install khi không truyền source, và lệnh này sẽ khôi phục project lockfile.
Spec và test. SkillSpec tiếp cận theo hướng khác. Công cụ này 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 được". skillspec doctor <path> báo cáo những điểm agent có khả năng mất mạch xử lý. skillspec boundary map <path> hiển thị nội dung của skill, còn skillspec boundary assess <path> báo cáo những gì skill có thể truy cập, được xếp hạng theo 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 được phát hành vào ngày 29 July 2026 và vẫn là bản mới nhất trên crates.io tính đến ngày 10 October 2026. Hãy cài đúng version được ghim thay vì cài bản mới nhất:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked build với các version dependency mà crate đã sử dụng khi được phát hành, nên quá trình build không tự thay đổi version dependency. skillspec --version phải in ra 0.2.2. Nếu hiện số khác, nghĩa là một binary cũ hơn trong PATH đang được ưu tiên.
Thực hành của vendor. Google mô tả cách họ build các skill trong google/skills trong bài viết về cách họ build, test 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. Mỗi skill 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 trước khi được merge. Link checker sẽ làm build fail nếu bất kỳ URL nào trả về 404, nhờ đó phát hiện những link có vẻ hợp lệ nhưng do agent tự tạo. Tác giả phải cung cấp evaluation prompt suite và scoring rubric cùng với skill. Sau đó, các job evaluation theo lịch chạy hằng tuần trên toàn bộ library để phát hiện regression, và mỗi skill đều có một owner cụ thể, người được kỳ vọng sẽ sửa skill khi chất lượng giảm.
Mẫu hình chung phía sau cả ba câu trả lời
Bạn không phải chọn một trong các 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 đó.
- Một nguồn sự thật duy nhất. Mỗi 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 pin cho từng 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ó author và ngày tháng.
- Một smoke test cho từng skill. Một bài kiểm tra có thể chạy để xác nhận skill vẫn tạo ra kết quả như đã cam kết.
- Một quy trình review. Thay đổi đối với skill dùng chung phải qua review, và mọi consumer đều thấy diff trước khi áp dụng.
Đó 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 sử 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ỏ trên 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 hoạt động như 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. Dùng annotated tag vì chúng chứa message và ngày tạo. Viết message theo lý do consumer muốn nâng version:
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 bare repository qua SSH trên VPS của bạn, các bước tiếp theo vẫn không thay đổi. Tất cả chỉ gồm git và một symlink.
Pin 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 đó chính là pin. 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à phần giúp cách này hoạt động. Một skill entry ở cấp project có thể là symlink trỏ đến một thư mục ở nơi khác trên disk, và Claude Code sẽ đi theo symlink đó rồi đọc SKILL.md từ target. Vì vậy, skill được nạp như một project skill bình thường, còn các byte nằm trong submodule tại commit bạn đã chọn.
Kiểm tra pin:
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)Ký tự - ở đầu dòng 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. Ký tự + ở đầu dòng nghĩa là commit đã checkout khác với commit được ghi nhận, nên developer đó đang chạy các instruction mà không ai khác có. Clone mới cần git clone --recurse-submodules, và phải ghi lệnh đó trong README, vì clone thông thường để vendor/agent-skills trống và không in ra lỗi.
Việc nâng cấp được thực hiện có chủ đích. Đó chính là mục đích 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. Nó hiển thị cùng một thay đổi mà mọi repo sử dụng khác sẽ thấy, và phù hợp để đưa vào một pull request.
Ghim phiên bản bằng marketplace plugin thay thế
Nếu bạn không muốn yêu cầu mọi lập trình viên phải học cách dùng submodule, hệ thống plugin của Claude Code sẽ tự động phân phối cho bạn và nó hoạt động với một remote tự host. Hãy đặt một catalog tại .claude-plugin/marketplace.json trong kho lưu trữ kỹ năng (skills repository):
{
"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"
}
}
]
}Có hai nguồn khác nhau đang hoạt động tại đây và nhầm lẫn giữa chúng là lỗi phổ biến. Nguồn marketplace, tức là nơi catalog được tải về, chấp nhận ref cho một branch hoặc tag và không chấp nhận sha. Một nguồn plugin bên trong catalog chấp nhận cả hai, và khi cả hai cùng được thiết lập thì sha sẽ là giá trị ghim có hiệu lực. Vì vậy, việc ghim theo commit chính xác thuộc về mục nhập trong catalog. Tên các loại cũng khác nhau. Bên trong catalog, url nghĩa là một git repository để clone. Trong nguồn marketplace, url nghĩa là một liên kết trực tiếp đến một file marketplace.json, còn git repository là git.
Mỗi repository sử dụng sau đó sẽ khai báo marketplace trong file .claude/settings.json đã được commit:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code đăng ký marketplace cho thành viên trong nhóm ngay khi họ chấp nhận hộp thoại tin cậy workspace cho thư mục dự án, mà không cần một trang wiki hướng dẫn họ thực hiện. Mục nhập catalog trỏ đến một git URL thay vì đường dẫn tương đối, vì vậy bản thân plugin không tự cài đặt chỉ từ cài đặt của repository. Mỗi thành viên trong nhóm chạy claude plugin install team-skills@acme-agents --scope project một lần, và cho đến lúc đó Claude Code sẽ báo rằng plugin đã được bật trong cài đặt dự án nhưng chưa được cài đặt. Các kỹ năng sau đó sẽ phản hồi lại /team-skills:api-review, vì các kỹ năng plugin được phân tách theo tên plugin và không thể trùng lặp với kỹ năng dự án có cùng tên. Sau khi bạn push một tag mới, người dùng sẽ làm mới bằng /plugin marketplace update acme-agents, sau đó chạy /reload-plugins nếu 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 theo script trên một fixture có lỗi đã biết, kèm một assertion. Claude Code chạy ở chế độ không tương tác với -p, và skill do người dùng gọi cũng hoạt động trong chế độ đó: đặt /skill-name vào chuỗi prompt, nó sẽ đượ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ố ý. Assertion kiểm tra xem 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 skill không còn bắt được lỗi đã cài sẵn sẽ làm script thất bạ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 biế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ờ assertion trên cả một câu. Hãy assertion trên một identifier mà skill phải xuất ra, hoặc trên một field của 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, 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 cơ chế tự động tìm kiếm, ngoại trừ các skill trong .claude/skills/ dưới một thư mục được cung cấp rõ ràng bằng --add-dir; nó bỏ qua skill của project đang được test ở đây, nên hãy nạp skill đó một cách tường minh. 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 jsonPlugin được nạp bằng --plugin-dir sẽ lấy tên từ .claude-plugin/plugin.json. Nếu không có manifest đó, plugin sẽ được đặt tên theo thư mục của nó. Hãy commit một plugin.json có "name": "team-skills" cạnh catalog trong skills repository, nếu không lệnh trên phải gọi /agent-skills:api-review thay thế.
Với --output-format stream-json, event system/init báo cáo những plugin đã được nạp và chứa một array plugin_errors cho những plugin chưa được nạp. Event này mở stream, trừ khi các startup event xuất hiện trước. Hãy làm CI job thất bại khi plugin_errors không rỗng. Cách này bắt được 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à một chỉ dẫn 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ừ một team khác.
Thứ nhất, một SKILL.md có thể chạy các lệnh shell 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 tiền xử lý:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Lệnh chạy trên máy đang load skill, và output của lệnh thay thế placeholder trong phần text mà model nhận được. Một fenced block mở bằng ba dấu backtick theo sau là ! cũng chạy nhiều lệnh theo cách tương tự. Không có bước hỏi xác nhận nào cho các thao tác này trong lúc chạy. Claude Code kiểm tra từng lệnh theo các permission rule của bạn. Khi không ở auto mode, một lệnh không được các rule đó cho phép sẽ làm skill dừng, trừ khi skill pre-approve lệnh đó bằng tính năng thứ hai bên dưới. Các rule deny và ask vẫn ghi đè pre-approval đó. Đọ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 các tool. allowed-tools cấp quyền cho các tool được liệt kê mà không hiện permission prompt trong turn đã invoke skill. Workspace trust không kiểm soát quyền cấp này: Claude Code áp dụng allowed-tools của project skill ngay cả trong một lần chạy -p ở thư mục chưa được ai trust. Tài liệu Claude Code nêu rõ hệ quả: một skill có thể tự cấp cho mình quyền truy cập tool rất rộng, vì vậy hãy review allowed-tools của các skill được commit vào repository trước khi chạy Claude Code trong đó. Tổ chức có thể không cho phép project skill và personal skill dùng field này bằng cách đặt allowManagedPermissionRulesOnly trong managed settings; tính năng này cần Claude Code v2.1.282 trở lên.
Vì vậy, hãy xử lý việc cập nhật skill giống hệt việc cập nhật dependency. Khi cơ chế cho phép, hãy pin bằng commit chính xác, vì tag có thể bị di chuyển còn branch thì vốn luôn thay đổi. Trên máy bị khóa chặt, "disableSkillShellExecution": true trong settings 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ể ghi đè. Bundled skill và managed skill được miễn áp dụng setting này.
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ở config file sẽ đưa mọi thứ tìm thấy vào context của model; đây là lỗi được đề cập trong giữ secret bên ngoài các agent bạn chạy. Một skill fetch page hoặc chạy query cũng tạo ra cùng kiểu phơi nhiễm theo hướng ra ngoài, vì text được truy xuất sẽ đi vào context và trông giống hệt các instruction bạn viết, một ranh giới bạn nên đọc về trước khi trỏ agent vào instance SearXNG của riêng bạn để tìm kiếm web.
Đọc gì khi tăng phiên bản
- Diff của mọi phần thân
SKILL.md, vì nội dung đó là chỉ dẫn mà agent của bạn sẽ làm theo. - Mọi phép thay thế lệnh, vì chúng được chạy trên máy của bạn khi skill được nạp.
- Mọi thay đổi đối với
allowed-tools, vì dòng đó cấp quyền dùng công cụ 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 mà 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ự cũng á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à để skill chỉ chứa 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ứ 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 của model đố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ữa. Một command line tool có thể đổ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 có thể bắt đầu trả về 404. Agent harness có thể thay đổi cách chọn skill. Vì vậy, một description trước đây từng khớp tốt nhất có thể không còn được chọn. Khi một procedure bắt đầu kết thúc sớm như vậy, không thể sửa bằng cách tăng version. Bản thân instruction cần có cấu trúc buộc phải thực hiện các bước cuối. Đây là cách tiếp cận đứng sau skill unlazy và phương pháp Depth Tree của nó.
Đó là lý do smoke test giữ vai trò quan trọng trong mô hình này. Hãy chạy test của từng skill theo lịch, đồng thời chạy khi push. Google chạy các evaluation job hằng tuần trên toàn bộ library vì lý do này. Với một team có mười skill, một cron job chạy hằng tuần trên một VPS nhỏ là đủ. Đây là cách duy nhất để phát hiện lỗi trước khi developer phát hiện ra.
Tính portability cũng hữu ích. Đặc tả Agent Skills chỉ giữ frontmatter ở 6 key. Vì vậy, một skill được viết theo đặc tả này có thể load trong nhiều tool khác ngoài tool mà bạn viết nó, trong khi mỗi key riêng của harness là một lần đặt cược vào một vendor. Viết skill có thể hoạt động ổn định sau khi đổi model là một discipline riêng. Nội dung này được trình bày trong cách làm cho một 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ó hai 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 load như skill thông thường của project. Plugin marketplace cũng làm việc tương tự thông qua /plugin, với thông tin pin được khai báo trong .claude/settings.json của repository sử dụng. Cả hai 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 agent skill vào một version cụ thể không?
Không thể thực hiện bên trong SKILL.md, vì frontmatter đó không có key version. Pin phải được đặt ở lớp bao quanh file. Git submodule mặc định pin vào một commit cụ thể. Trong plugin marketplace của Claude Code, plugin source chấp nhận ref cho branch hoặc tag và sha cho commit cụ thể; nếu có cả hai thì sha được ưu tiê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 của 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 kiểm tra chính xác, còn jq -e làm script fail khi giá trị bị thiếu. Không nên kiểm tra cả 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 load thông qua dạng command substitution !, còn field allowed-tools trong frontmatter có thể pre-approve tool mà không cần prompt. Hãy đọc diff ở mỗi lần bump, pin vào 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ý, "disableSkillShellExecution": true trong settings sẽ ngăn command substitution chạy trong skill ở user, project, plugin và additional-directory; bundled skill và managed skill được miễn áp dụng.
Shared skill có hoạt động trong agent khác Claude Code không?
Điều đó phụ thuộc vào frontmatter bạn sử dụng. Agent Skills spec định nghĩa 6 key: name, description, license, compatibility, metadata và allowed-tools. Skill chỉ sử dụng các key này sẽ được load trên những tool triển khai spec, đồng thời cũng load trong Claude Code mà không cần thay đổi. Các key và tính năng trong body dành riêng cho từng harness, nếu vượt ngoài spec, sẽ bị bỏ qua hoặc bị từ chối ở nơi khác. Vì vậy, hãy loại bỏ chúng khỏi mọi skill mà bạn dự định chia sẻ rộng rãi.