Codex Skill là gì? Cách đóng gói kỹ năng chuẩn cho Codex CLI
Codex Skill là giải pháp đóng gói tài nguyên theo mô-đun cho Codex CLI, giúp nạp ngữ cảnh 3 tầng tinh gọn, tiết kiệm chi phí token và chuẩn hóa quy trình AI.
Điểm nổi bật
7 mục
Điểm nổi bật
7 mục
Chương trình dành cho doanh nghiệpKhông cần biết lập trìnhXây dựng đội ngũ AI Agent cho doanh nghiệpTừ lựa chọn use case đến thiết kế quy trình, quản trị rủi ro và đo hiệu quả vận hành.Khám phá chương trìnhHọc thực chiến cùng DATMarketingCodex Skill là gói hướng dẫn nghiệp vụ và tài nguyên thực thi đóng gói theo mô-đun giúp tác tử lập trình OpenAI Codex CLI xử lý chính xác các quy trình kỹ thuật phức tạp. Thay vì giải thích lặp đi lặp lại trong từng câu lệnh, mỗi kỹ năng gói gọn toàn bộ quy tắc, tập lệnh tiện ích và tài liệu tra cứu vào một thư mục độc lập xoay quanh tệp SKILL.md.
Áp dụng chuẩn Codex Skill cho phép mô hình giữ cửa sổ ngữ cảnh tinh gọn nhờ cơ chế nạp thông tin 3 tầng, chỉ mở tài liệu chuyên sâu khi tác vụ thực sự khớp yêu cầu. Đội ngũ phát triển vừa tiết kiệm đáng kể chi phí token (đơn vị dữ liệu ngôn ngữ), vừa đảm bảo tính nhất quán khi chia sẻ quy trình nội bộ qua kho mã nguồn.
Hướng dẫn dưới đây trình bày chi tiết cấu trúc thư mục chuẩn, quy trình 4 bước khởi tạo bằng script hệ thống, cách cấu hình agents/openai.yaml và đối chiếu trực tiếp với hệ thống kỹ năng trên Google Antigravity.
Codex Skill là gì và cơ chế nạp ngữ cảnh 3 tầng

Cơ chế nạp ngữ cảnh 3 tầng tiết kiệm token của Codex Skill
Codex Skill vận hành như một mô-đun năng lực mở rộng dành riêng cho tác nhân lập trình trên dòng lệnh, giúp bổ sung tri thức miền chuyên biệt mà không làm chậm phiên làm việc chung. Theo kho mã nguồn mở OpenAI Codex CLI, thiết kế kỹ năng tuân thủ hai nguyên tắc cốt lõi là giữ bước khám phá siêu nhẹ và tiết lộ chi tiết theo từng tầng.
Nhờ tách bạch phần hướng dẫn chuyên môn khỏi tệp quy tắc nền, lập trình viên có thể vận hành quy trình theo hướng dẫn sử dụng OpenAI Codex CLI một cách linh hoạt trên mọi dự án mà không lo xung đột ngữ cảnh.
3 giai đoạn nạp thông tin giúp tiết kiệm Token
Để tránh tiêu tốn hạn mức vào những tài liệu chưa dùng tới, hệ thống chia quá trình đọc ngữ cảnh của mỗi Codex Skill thành 3 giai đoạn tuần tự:
- Giai đoạn 1 - Tên và mô tả ngắn (Name and description): Ở trạng thái chờ, chỉ hai trường siêu dữ liệu này được đưa vào danh sách nhận diện để trợ lý chọn đúng kỹ năng khi cần.
- Giai đoạn 2 - Nội dung tệp chính (SKILL.md body): Ngay khi xác định yêu cầu của người dùng khớp với phạm vi mô tả, tác tử mới đọc phần thân Markdown trong
SKILL.md. - Giai đoạn 3 - Tài nguyên phụ trợ (Supporting resources): Các tệp trong thư mục
references/hoặc tập lệnh trongscripts/chỉ được mở đọc hoặc thực thi khi bước làm việc cụ thể yêu cầu.
Cơ chế đọc phân tầng này loại bỏ hoàn toàn tài liệu dư thừa khỏi bộ nhớ đệm và hỗ trợ trực tiếp cách tối ưu token khi dùng Codex CLI trong các dự án có hàng chục quy trình khác nhau.
So sánh chế độ tự kích hoạt và gọi lệnh $skill-name
OpenAI Codex CLI hỗ trợ hai cơ chế kích hoạt kỹ năng tùy theo mức độ nhạy cảm của tác vụ, cho phép đội ngũ kiểm soát chặt chẽ thời điểm thực thi qua tệp cấu hình agents/openai.yaml.
| Tiêu chí đối chiếu | Kích hoạt tự động (Implicit Invocation) | Gọi trực tiếp bằng $skill-name |
|---|---|---|
| Trạng thái mặc định | Bật sẵn cho mọi kỹ năng mới khởi tạo | Bật khi thiết lập allow_implicit_invocation: false |
| Cách thức kích hoạt | Tác tử tự đối chiếu prompt với trường description | Người dùng gõ đích danh $ten-ky-nang trong câu lệnh |
| Trường hợp nên áp dụng | Tác vụ thường xuyên như kiểm tra lỗi, viết unit test | Quy trình phát hành nhạy cảm chỉ chạy khi có lệnh rõ ràng |
Theo nguyên tắc thiết kế từ bộ công cụ tạo kỹ năng hệ thống, bạn nên giữ chế độ tự động mặc định cho đa số kỹ năng và chỉ khóa kích hoạt ngầm định khi người dùng yêu cầu gọi đích danh, thay vì khóa cứng mọi thao tác cần xác nhận.
Giải phẫu cấu trúc 5 thành phần của một Codex Skill

Cấu trúc 5 thành phần của Codex Skill gồm SKILL.md và 4 thư mục mở rộng
Một thư mục Codex Skill chuẩn thường được lưu tại $CODEX_HOME/skills (mặc định là ~/.codex/skills) cho cá nhân hoặc trong thư mục kỹ năng của kho dự án. Cấu trúc thư mục tối đa gồm 5 thành phần độc lập, trong đó chỉ tệp SKILL.md là bắt buộc phải tồn tại:
skill-name/
├── SKILL.md # Bắt buộc: YAML frontmatter và hướng dẫn thực thi
├── agents/ # Tùy chọn: Siêu dữ liệu giao diện và chính sách gọi
│ └── openai.yaml
├── scripts/ # Tùy chọn: Mã tiện ích thực thi lặp lại
├── references/ # Tùy chọn: Tài liệu tra cứu chuyên sâu theo ngữ cảnh
└── assets/ # Tùy chọn: Mẫu giao diện, biểu mẫu, hình ảnh đầu ra
Vai trò của tệp SKILL.md và cấu hình openai.yaml
Tệp SKILL.md giữ vai trò trung tâm điều phối toàn bộ hành vi của kỹ năng. Phần đầu tệp khai báo khối YAML Frontmatter gồm name (chữ thường, chữ số và dấu gạch ngang, tối đa dưới 64 ký tự) cùng description mô tả ngắn gọn phạm vi áp dụng, đi kèm trường metadata tùy chọn như short-description.
Trong khi đó, tệp agents/openai.yaml lưu trữ siêu dữ liệu phục vụ giao diện người dùng gồm display_name, short_description, default_prompt và khối policy kiểm soát quyền tự kích hoạt. Cách tách riêng siêu dữ liệu hiển thị ra tệp YAML giúp phần thân Markdown trong SKILL.md tập trung hoàn toàn vào quy trình kỹ thuật.
Cách phân bổ thư mục scripts, references và assets
Phân tách đúng vai trò cho 3 thư mục phụ trợ giúp mô hình không bị quá tải bởi tệp không liên quan. Bảng dưới đây tóm tắt mục đích sử dụng chuẩn cho từng thư mục trong một Codex Skill:
| Thư mục con | Mục đích sử dụng chính | Ví dụ thực tế nên lưu | Lưu ý ngữ cảnh |
|---|---|---|---|
scripts/ | Chạy logic phức tạp hoặc lặp lại nhiều lần | rotate_pdf.py, validate_api.sh | Có thể thực thi trực tiếp mà không cần đọc hết mã nguồn |
references/ | Lưu tài liệu tham khảo theo từng chế độ | schema.md, aws.md, policies.md | Chỉ mở đọc đúng tệp phù hợp với tình huống đang xử lý |
assets/ | Cung cấp tài nguyên đưa vào sản phẩm đầu ra | frontend-template/, mẫu tài liệu, phông chữ | Không nạp vào ngữ cảnh hướng dẫn trừ khi cần kiểm tra |
Một lưu ý quan trọng là tuyệt đối tránh đưa vào thư mục kỹ năng các tệp tài liệu phụ thừa thãi như README.md, hướng dẫn cài đặt riêng hay lịch sử thay đổi CHANGELOG.md, vì chúng không hỗ trợ trực tiếp bước thực thi của tác tử.
Quy trình 4 bước khởi tạo và kiểm định Codex Skill

Quy trình 4 bước khởi tạo và kiểm định Codex Skill tự động
Để tạo mới một Codex Skill đồng nhất với bộ công cụ hệ thống skill-creator có sẵn trong ~/.codex/skills/.system/, lập trình viên nên thực hiện tuần tự 4 bước từ khởi tạo khung mẫu, viết hướng dẫn, cấu hình giao diện đến chạy kiểm định tự động.
Bước 1 và 2: Khởi tạo bằng init_skill.py và viết chỉ dẫn
Thay vì tạo thư mục thủ công dễ thiếu tệp, hai bước đầu tận dụng script khởi tạo chuẩn có sẵn của Codex CLI:
- Bước 1 - Chạy tập lệnh khởi tạo
init_skill.py: Thực thi lệnh với tùy chọn--resourceschỉ rõ đúng các thư mục thực sự cần dùng để tránh tạo thư mục rỗng dư thừa. - Bước 2 - Biên soạn
SKILL.mdtheo rủi ro tác vụ: Chỉ viết những ràng buộc thực sự làm thay đổi quyết định của mô hình, nêu rõ kết quả mong muốn và dẫn liên kết tới các tệp trongreferences/.
scripts/init_skill.py api-audit \
--path "${CODEX_HOME:-$HOME/.codex}/skills" \
--resources scripts,references
Bước 3 và 4: Cấu hình openai.yaml và chạy kiểm định
Sau khi hoàn tất nội dung hướng dẫn và tập lệnh hỗ trợ, bước tiếp theo là chuẩn hóa tệp giao diện và xác minh cấu trúc trước khi đưa vào sử dụng hằng ngày:
- Bước 3 - Sinh hoặc cập nhật
agents/openai.yaml: Dùngscripts/generate_openai_yaml.py <duong-dan-skill> --interface key=valuecho kỹ năng mới; nếu tệp cũ đã có trườngpolicyhoặcdependencies, hãy sửa trực tiếp đúng trường cần đổi để tránh ghi đè mất cấu hình. - Bước 4 - Chạy kiểm định cấu trúc bằng
quick_validate.py: Lệnh này tự động rà soát định dạng YAML Frontmatter, quy ước đặt tên chữ thường dưới 64 ký tự và phát hiện các đoạn mẫu placeholder còn sót lại.
scripts/quick_validate.py "${CODEX_HOME:-$HOME/.codex}/skills/api-audit"
So sánh Codex Skill và Google Antigravity Skill

So sánh Codex Skill và Google Antigravity Skill cùng điểm chung SKILL.md và MCP
Dù phục vụ hai môi trường tác tử khác nhau, Codex Skill và Google Antigravity Skill cùng chia sẻ cấu trúc nền tảng xoay quanh tệp SKILL.md và triết lý nạp ngữ cảnh lũy tiến. Theo tài liệu giới thiệu Codex của OpenAI, việc chuẩn hóa ngữ cảnh dự án giúp các nhóm kỹ thuật dễ dàng kết hợp nhiều công cụ trên cùng một kho mã nguồn.
| Tiêu chí so sánh | Codex Skill (OpenAI Codex CLI) | Google Antigravity Skill |
|---|---|---|
| Đường dẫn lưu trữ mặc định | ~/.codex/skills/ hoặc .agents/skills/ | .agents/skills/ hoặc ~/.gemini/config/skills/ |
| Tệp cấu hình mở rộng | agents/openai.yaml (UI và policy gọi) | .agents/skills.json (kế thừa và lọc đường dẫn) |
| Thư mục phụ trợ hỗ trợ | scripts/, references/, assets/ | scripts/, references/, examples/, resources/ |
| Cơ chế gọi trực tiếp | Cú pháp $skill-name trên phiên làm việc | Tự kích hoạt theo mô tả hoặc lệnh giao diện |
| Kết nối công cụ ngoài | Hỗ trợ tích hợp qua giao thức Model Context Protocol | Kết hợp qua mcp_config.json và gói Plugin |
Điểm tương đồng về chuẩn SKILL.md và nạp lũy tiến
Cả hai nền tảng đều dùng chung cấu trúc tệp SKILL.md có YAML Frontmatter chứa hai trường bắt buộc name và description, kết hợp thân bài Markdown mô tả quy trình thực thi. Nhờ thiết kế nạp phân tầng tương đồng, một nhóm kỹ thuật sử dụng song song cả OpenAI Codex CLI và Google Antigravity hoàn toàn có thể đặt kho kỹ năng dùng chung tại thư mục .agents/skills/ ngay ở gốc dự án.
Khi kỹ năng cần tương tác với hệ thống quản trị bên ngoài hoặc cơ sở dữ liệu nội bộ, cấu trúc chung này cũng dễ dàng kết hợp với hướng dẫn tích hợp MCP vào OpenAI Codex CLI để tạo thành quy trình tự động hóa khép kín.
Khác biệt về tệp cấu hình openai.yaml và skills.json
Sự khác biệt rõ rệt nằm ở lớp điều phối ngoài tệp SKILL.md. Codex tập trung vào khả năng kiểm soát kích hoạt ngầm định từng kỹ năng và hiển thị giao diện thông qua agents/openai.yaml, phù hợp khi lập trình viên muốn gắn rõ nút lệnh hoặc khóa gọi nhầm thao tác rủi ro cao.
Ngược lại, Google Antigravity nhấn mạnh vào cơ chế kế thừa đa kho và ghi đè theo 5 cấp độ thông qua skills.json với các bộ lọc include_only và exclude. Nếu muốn một thư mục kỹ năng trong .agents/skills/ chạy mượt trên cả hai nền tảng, bạn chỉ cần giữ phần lõi SKILL.md, scripts/, references/ thuần túy theo chuẩn chung và chỉ bổ sung tệp cấu hình riêng khi thực sự cần tính năng đặc thù.
3 nguyên tắc vàng khi thiết kế Codex Skill thực tế

3 nguyên tắc vàng khi thiết kế Codex Skill trong thực tế vận hành
Chất lượng của một Codex Skill không nằm ở độ dài hàng trăm dòng chỉ dẫn, mà ở độ chính xác khi tác tử ra quyết định trong những tình huống phức tạp. Áp dụng 3 nguyên tắc vàng gồm tối giản hướng dẫn, viết mô tả sắc nét và kiểm thử bằng tác tử độc lập giúp bộ kỹ năng hoạt động ổn định trong môi trường doanh nghiệp.
Giữ mô tả phân loại sắc bén và tránh lặp quy tắc
Hãy mặc định rằng mô hình đã thành thạo kỹ năng lập trình phổ thông; chỉ đưa vào SKILL.md những quy ước đặc thù, rào chắn bảo mật hoặc điều kiện biên dễ gây sai sót. Với các tác vụ có nhiều hướng giải quyết hợp lý, hãy mô tả tiêu chí lựa chọn và kết quả cần đạt thay vì ép cứng số bước máy móc.
Đồng thời, trường description trong YAML cần nêu rõ năng lực thực tế và giới hạn loại trừ những yêu cầu gần giống nhưng không thuộc phạm vi kỹ năng. Điều này giúp mô hình tránh kích hoạt nhầm quy trình kiểm toán chuyên sâu vào các yêu cầu chỉnh sửa nhỏ thông thường.
Kiểm thử thực tế bằng tác tử độc lập trước khi dùng
Tập lệnh quick_validate.py chỉ kiểm tra lỗi cú pháp Frontmatter và tên thư mục, không thể chứng minh kỹ năng giúp mô hình ra quyết định đúng. Với các kỹ năng phức tạp hoặc tác động nhiều tệp tin, đội ngũ nên thực hiện kiểm thử tiến tới độc lập (Independent Forward-Testing) bằng một tác tử con trong thư mục tạm cô lập.
Cách kiểm thử chuẩn là giao cho tác tử kiểm thử đúng một yêu cầu thực tế của người dùng cùng đường dẫn kỹ năng (dạng $skill-name) mà không mớm trước đáp án hay lỗi dự kiến. Sau khi tác tử hoàn thành, kỹ sư đối chiếu kết quả đầu ra và chỉ tinh chỉnh đúng những điểm bất cập quan sát được thay vì thêm hàng loạt luật cứng nhắc.
Câu hỏi thường gặp (FAQ)
1. Nên lưu Codex Skill trong thư mục ~/.codex/skills hay .agents/skills của dự án?
Nếu kỹ năng phục vụ quy trình chung của toàn bộ nhóm phát triển như chuẩn hóa API hoặc kiểm tra bảo mật trước khi gộp mã, hãy lưu trong .agents/skills tại gốc dự án để đồng bộ qua Git. Ngược lại, các kỹ năng mang tính thói quen cá nhân áp dụng cho nhiều kho mã khác nhau nên đặt tại ~/.codex/skills.
2. Khi nào cần đặt cấu hình allow_implicit_invocation bằng false trong openai.yaml?
Bạn chỉ nên tắt kích hoạt tự động khi muốn kỹ năng hoạt động ở chế độ gọi đích danh bằng cú pháp $ten-ky-nang cho các quy trình đặc thù hoặc có yêu cầu tách biệt rõ ràng. Với các kỹ năng hỗ trợ hằng ngày, hãy giữ nguyên cơ chế tự động mặc định để tác tử chủ động nhận diện đúng lúc.
3. Một thư mục Codex Skill có bắt buộc phải có đủ cả scripts, references và assets không?
Không bắt buộc phải có đủ cả 3 thư mục phụ trợ này. Duy nhất tệp SKILL.md là thành phần bắt buộc, còn scripts/, references/ hay assets/ chỉ nên tạo khi quy trình thực tế có mã chạy lặp lại, tài liệu tra cứu lớn hoặc tệp mẫu đầu ra cần tái sử dụng.
Tổng kết & Lời khuyên hành động
Triển khai bài bản hệ thống Codex Skill mang lại 3 giá trị bền vững cho quy trình phát triển phần mềm bằng AI:
- Giữ ngữ cảnh luôn gọn nhẹ nhờ cơ chế nạp 3 tầng tách biệt giữa siêu dữ liệu nhận diện, hướng dẫn chính và tài nguyên tham khảo.
- Chuẩn hóa chất lượng thực thi thông qua tập lệnh đóng gói sẵn trong
scripts/và kiểm tra tính hợp lệ tự động bằngquick_validate.py. - Dễ dàng mở rộng và dùng chung với cả đội ngũ sử dụng Google Antigravity thông qua cấu trúc tệp
SKILL.mdthống nhất.
Hãy bắt đầu bằng việc chạy tập lệnh init_skill.py cho một quy trình lặp đi lặp lại trong dự án hiện tại, viết phần mô tả YAML Frontmatter thật súc tích và kiểm chứng ngay trên một tác tử độc lập trước khi chia sẻ toàn nhóm.
Bài viết liên quan
Xem tất cảGoogle Antigravity Skill là gì? Cách xây dựng SKILL.md chuẩn
Google Antigravity Skill giúp chuẩn hóa quy trình cho AI Agent qua tệp SKILL.md, tiết kiệm token ngữ cảnh và đồng bộ năng lực thực thi cho toàn doanh nghiệp.
Xử lý khiếu nại khách hàng cho doanh nghiệp nhỏ
Khám phá khung hành động 5 bước xử lý khiếu nại khách hàng cho SME, kết hợp kỹ năng giao tiếp thấu cảm để dập tắt sự cố và gia tăng lòng trung thành.
Hệ thống phản hồi khách hàng cho doanh nghiệp nhỏ
Xây dựng hệ thống phản hồi khách hàng giúp doanh nghiệp nhỏ chuẩn hóa kênh thu thập ý kiến, xử lý điểm nghẽn dịch vụ và tối ưu chi phí giữ chân khách cũ.
