Codex Skills Là Gì? Giải Thích SKILL.md Từ A Đến Z (2026)

- Thông tin và số liệu dưới đây đã đối chiếu tài liệu chính thức tại thời điểm viết (08/2026); thuật ngữ Codex Skills/Plugins đang đổi nhanh - kiểm tra docs live trước khi phụ thuộc.

Codex Skills là gì?

Một Codex skill là một thư mục đóng gói hướng dẫn - kèm theo (tùy chọn) script, tài liệu tham chiếu và asset - thành một năng lực tái dùng mà Codex chỉ kéo vào khi có việc cần đến nó. Thay vì phải giải thích lại "ở đây mình làm migration database kiểu này" mỗi phiên, bạn viết một lần thành file SKILL.md, rồi Codex tự nạp khi cần.

Điều cần làm rõ trước tiên: Codex Skills không phải một format OpenAI tự nghĩ ra từ đầu. SKILL.md là chuẩn mở Agent Skills - theo đúng trang của chuẩn này, "ban đầu được Anthropic phát triển, phát hành như một chuẩn mở, và đã được ngày càng nhiều sản phẩm agent áp dụng". Anthropic ra mắt nó cho Claude Code trước (10/2025); OpenAI dùng đúng format file đó cho Codex và ChatGPT chỉ vài tuần sau. Cùng một SKILL.md, hai hệ sinh thái.

Về thực chất, một skill gồm: tên cộng dòng mô tả kích hoạt description (luôn hiển thị với Codex) và phần thân Markdown (chỉ nạp khi khớp). Nó sinh ra cho việc lặp lại, có hình dạng tác vụ rõ ràng - một quy trình fix lint, một checklist migration, một định dạng changelog - chứ không phải kiến thức chung hay ngữ cảnh dự án luôn-bật. Đó là việc của AGENTS.md, nói ở phần dưới.

Cấu trúc một file SKILL.md

Một skill là một thư mục đặt tên theo slug của nó, gồm một file bắt buộc và tối đa bốn thành phần tùy chọn:

my-skill/
├── SKILL.md            (bắt buộc)
├── scripts/            (tùy chọn - code thực thi)
├── references/         (tùy chọn - tài liệu skill có thể trỏ tới)
├── assets/             (tùy chọn - template, file tĩnh)
└── agents/openai.yaml  (tùy chọn - metadata UI + MCP riêng cho Codex)

Bản thân SKILL.md là YAML frontmatter rồi tới hướng dẫn Markdown. Chỉ hai field bắt buộc:

---
name: changelog-writer
description: Turn a git diff into a changelog entry. Use when the
  user asks for a changelog, release notes, or "what changed".
---

# Changelog writer

1. Chạy `git diff --stat` và `git log -5 --oneline`.
2. Nhóm thay đổi theo loại: Added, Changed, Fixed.
3. Viết 3-6 gạch đầu dòng theo đúng format changelog của dự án.

name là định danh; description là cái ngòi kích hoạt - dòng duy nhất Codex đọc để quyết định skill này có áp dụng hay không, nên viết cho chính xác ("dùng khi...") thay vì mơ hồ ("hỗ trợ về changelog").

Phần tùy chọn agents/openai.yaml chỉ dành riêng cho Codex: không ảnh hưởng gì tới Claude Code hay client nào khác, chỉ đổi cách skill hiển thị và vận hành bên trong Codex/ChatGPT. Theo docs hiện tại, nó gồm ba nhóm field - giao diện (display_name, short_description, icon_small/icon_large, brand_color, default_prompt), chính sách (allow_implicit_invocation, mặc định true), và danh sách phụ thuộc công cụ (một MCP server skill cần, kèm transport và URL). Tên field ở file này đổi theo sản phẩm - kiểm tra docs live trước khi phụ thuộc vào nó trong production.

Codex Skills hoạt động ra sao (progressive disclosure)

Cơ chế khiến skill rẻ để giữ trong máy gọi là progressive disclosure (nạp dần theo nhu cầu), chạy qua ba giai đoạn theo đúng tài liệu chính thức:

1. Discovery (khám phá) - lúc khởi động, Codex chỉ nạp name và description của từng skill. Đủ để biết skill tồn tại, chưa đủ để dùng.
2. Activation (kích hoạt) - khi prompt của bạn khớp với description của một skill, Codex đọc toàn bộ thân SKILL.md vào context.
3. Execution (thực thi) - Codex làm theo hướng dẫn, chạy script kèm theo hoặc kéo file trong references/assets khi skill yêu cầu.

Giai đoạn discovery có một ngân sách cứng: danh sách skill ban đầu (tên + description của mọi skill đã cài, gộp lại) bị giới hạn ở 2% context window của model, hoặc 8.000 ký tự nếu không biết kích thước context window - tùy trường hợp nào áp dụng. Đây là một trần thật sự mà đối thủ ít khi nhắc tới: cài quá nhiều skill mô tả dài dòng, một số sẽ không lọt vào danh sách.

Hai hệ quả thực tế theo sau. Một, viết description gọn và chính xác - vừa để chừa chỗ cho skill khác, vừa vì một dòng mơ hồ ("hỗ trợ về code") sẽ không kích hoạt đáng tin, còn một dòng chính xác ("dùng khi user hỏi changelog...") thì sẽ. Hai, đừng nhét gì mang tính thời điểm vào riêng description; nếu nó chỉ quan trọng lúc skill đang chạy, để trong thân bài, không để ở dòng kích hoạt.

Codex tìm skill ở đâu (scope và thứ tự ưu tiên)

Codex quét nhiều vị trí để tìm skill, từ cụ thể nhất tới chung nhất. Trùng tên thì vị trí cụ thể hơn thắng:

Hai cách kích hoạt khi Codex đã "thấy" skill:

• Explicit (chủ động) - gõ $skill-name trong Codex CLI/IDE (hoặc /skills để duyệt danh sách), @skill-name trong ChatGPT.
• Implicit (ngầm định) - chỉ cần mô tả việc bằng ngôn ngữ tự nhiên; Codex tự khớp với description của mọi skill đang thấy và tự kích hoạt.

Commit skill cấp-repo vào .agents/skills/ để cả team dùng chung; giữ thói quen cá nhân ở folder cấp-user để nó theo bạn qua mọi project.

Cách cài và tạo một Codex skill

Hai đường: cài skill người khác viết, hoặc tự xây.

Cài một skill có sẵn

Trong một phiên Codex, chạy skill cài-đặt built-in:

$skill-installer linear

Trỏ nó vào một tên từ catalog hiện tại, hoặc một GitHub URL, nó sẽ clone skill vào folder skill của bạn (mặc định cấp-user; truyền path project nếu muốn cấp-repo). Một điểm cần biết về độ tươi của thông tin: catalog skill của OpenAI đã dời chỗ một lần rồi. openai/skills trên GitHub mang banner deprecated, trỏ sang openai/plugins - và tại thời điểm viết, chính repo kế nhiệm đó cũng đã bị archive (chỉ đọc, không có repo thay thế nào được nêu). Không repo GitHub nào trong hai cái còn đáng tin làm catalog sống hiện giờ. Coi trang docs chính thức là link duy nhất đáng giữ, và đừng ngạc nhiên nếu nguồn mặc định của $skill-installer tiếp tục đổi - kiểm tra xem nó thực sự trỏ vào đâu trước khi chạy trong một script tự động.

Tự xây bằng công cụ tạo tương tác

$skill-creator

Lệnh này dẫn bạn qua từng bước: đặt tên skill, viết description kích hoạt, và soạn thân bài theo kiểu tương tác, rồi lưu thư mục vào skill path của bạn. Với một skill bạn sẽ tự dùng lại, ba thói quen quan trọng hơn bản thân cái tool:

1. Viết description như một cái ngòi kích hoạt, không phải một câu tóm tắt - "dùng khi X" tốt hơn "hỗ trợ về X".
2. Giữ thân bài có hình dạng tác vụ. Nếu bạn đang ghi ngữ cảnh dự án luôn-đúng thay vì một việc cụ thể, chỗ đó thuộc về AGENTS.md, không phải skill.
3. Test cả hai đường kích hoạt - gọi trực tiếp bằng $your-skill trước để xác nhận thân bài chạy đúng, rồi thử kích hoạt ngầm định bằng ngôn ngữ tự nhiên để xác nhận description thực sự bắt được.

Bạn cũng có thể tự tạo folder và file bằng tay - mkdir -p .agents/skills/my-skill && touch .agents/skills/my-skill/SKILL.md - công cụ tạo tương tác chỉ là tiện ích, không bắt buộc.

Codex Skills vs AGENTS.md vs Plugins - dùng cái nào?

Ba nguyên thể (primitive), ba việc khác nhau. Chúng không cạnh tranh nhau - phần lớn setup Codex thật sự dùng hai, thậm chí cả ba, cùng lúc.

Cách diễn đạt chính thức, gần như nguyên văn: một skill "packages instructions and supporting resources for a specific task or workflow" (đóng gói hướng dẫn và tài nguyên hỗ trợ cho một tác vụ hoặc workflow cụ thể), còn một plugin "is an installable bundle that can include skills, connectors, or both" (là gói cài đặt có thể gồm skill, connector, hoặc cả hai). Vậy plugin không phải một format thứ tư cạnh tranh với skill - nó là một lớp đóng gói, có thể ship một hoặc nhiều skill cùng nhau, cộng cả những thứ không phải skill như connector.

AGENTS.md nằm ở một lối hoàn toàn khác: nó không nạp theo nhu cầu, nó luôn ở trong context - chính vì vậy lời khuyên cho nó ngược hẳn với skill. Giữ ngắn (lệnh, rule cứng, path quan trọng), không viết dài, vì mỗi dòng tốn token ở mọi lượt. Đọc kỹ hơn về cách viết AGENTS.md gọn ở AGENTS.md vs CLAUDE.md vs SKILL.md; còn thứ tự tìm AGENTS.md riêng của Codex thì xem hướng dẫn AGENTS.md cho Codex.

Codex Skills có giống Claude Code Skills không?

Về cốt lõi, có - và có nguồn chính thống thật sự cho điều này, không chỉ là cảm tính. agentskills.io, trang của chính chuẩn này, liệt kê cả "Claude Code" lẫn "ChatGPT & Codex" là client được hỗ trợ, đứng cạnh nhau, và nói rõ format này "ban đầu được Anthropic phát triển, phát hành như một chuẩn mở, và đã được ngày càng nhiều sản phẩm agent áp dụng".

Cần chính xác ở đây: không một trang nào của OpenAI viết đúng câu "tương thích với Claude Code". Claim tương thích chéo dựa trên chính danh sách client của chuẩn này cộng nhiều nguồn thứ ba độc lập, không phải một câu trích dẫn từ OpenAI - nên bài này diễn đạt nó là "cùng một chuẩn mở", không phải một xác nhận chính thức từ OpenAI về Claude Code.

Cái thật sự di chuyển được giữa hai tool: chính file SKILL.md - name, description, thân Markdown, và các folder scripts//references/assets. Viết một skill ở tool này, file gốc chạy được ở tool kia, kể cả phần thừa không đọc được.

Cái không di chuyển là phần mở rộng riêng của từng tool, cái kia đơn giản là bỏ qua:

• Codex thêm agents/openai.yaml cho metadata UI desktop ChatGPT và phụ thuộc MCP.
• Claude Code thêm context: fork (chạy skill trong một subagent cô lập) và disable-model-invocation (chặn tự kích hoạt cho skill có side-effect) - xem chi tiết ở Claude Code Skills là gì.

Kết luận thực dụng: viết một skill không có frontmatter riêng-tool, nó tự động portable. Thêm một field chỉ-Codex hoặc chỉ-Claude, nó chỉ bị tool kia bỏ qua - không hỏng, chỉ không làm gì ở đó.

Không muốn tự viết? Bộ kit skill và workflow dựng sẵn

Tự viết skill hợp khi bạn muốn một workflow cá nhân thật chính xác. Nếu bạn muốn bắt đầu từ một thư viện đã được tuyển chọn thay vì một file SKILL.md trống, đó chính là khoảng trống trung thực mà AgentKit lấp vào - xem cách nó cắm vào Codex cụ thể ở dùng AgentKit trong Codex, hoặc vào thẳng agentkit.best. Làm rõ nhanh vì tên hay bị trùng: đây là AgentKit affiliate (agentkit.best, CLI ak) - không phải AgentKit/Agent Builder của chính OpenAI.

Nói thẳng ranh giới: tính năng Skills gốc của Codex miễn phí, đã bao gồm trong gói ChatGPT của bạn - không có gì ở đây bắt bạn phải mua. AgentKit là một add-on riêng, trả phí: một bộ kit gồm skill, subagent và workflow dựng sẵn, cài vào Codex bằng ak kit init engineer --target codex --global, rồi chạy qua $ak:cook thay vì tự viết tay từng SKILL.md. Đây là lựa chọn "đã có người xây và test sẵn", không phải điều kiện để Skills hoạt động.

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

Codex Skills có miễn phí không?

Có. Skills là tính năng gốc của Codex, đã bao gồm trong gói ChatGPT của bạn - viết, cài và chạy file SKILL.md của riêng bạn không tốn thêm phí. Chi phí chỉ xuất hiện nếu bạn chọn mua một bộ kit dựng sẵn của bên thứ ba thay vì tự xây.

Sự khác biệt giữa Codex skill và AGENTS.md là gì?

Skill nạp theo nhu cầu: chỉ nạp khi có việc khớp description. AGENTS.md luôn nạp: nằm trong context ở mọi lượt. Dùng skill cho một việc cụ thể, lặp lại; dùng AGENTS.md cho lệnh và rule cần luôn được biết.

Codex Skills có chạy được trong Claude Code không?

File SKILL.md gốc thì có - cả hai tool đều đọc chuẩn Agent Skills mở, và agentskills.io liệt kê cả hai là client được hỗ trợ. Phần mở rộng riêng-tool thì không di chuyển: agents/openai.yaml của Codex bị Claude Code bỏ qua, còn context: fork / disable-model-invocation của Claude Code bị Codex bỏ qua.

Đặt một custom Codex skill ở đâu?

Cấp-repo: .agents/skills/ tại root của repo (commit để cả team dùng chung). Cấp cá nhân, dùng ở mọi project: $HOME/.agents/skills. Codex còn quét working directory hiện tại và thư mục cha của nó, cộng vị trí admin và system-bundled, theo đúng thứ tự đó.

Có cài được skill của người khác không?

Có - chạy $skill-installer trong Codex, trỏ vào một tên trong catalog hoặc một GitHub URL, nó sẽ clone skill vào folder skill của bạn. Nên đọc qua SKILL.md và script của skill bên thứ ba trước khi cài, giống cách bạn review một dependency mới.

openai/skills còn là catalog chính thức không?

Không. openai/skills trên GitHub đã deprecated, trỏ sang openai/plugins - và tại thời điểm viết, chính openai/plugins cũng đã bị archive (chỉ đọc). Không repo nào trong hai cái còn là catalog sống; dùng docs chính thức tại learn.chatgpt.com/docs/build-skills thay vào đó.

Kết luận

Một Codex skill là một thư mục, một file SKILL.md, và một dòng mô tả kích hoạt - không có gì huyền bí hơn thế. Nó nạp theo nhu cầu trong khi AGENTS.md luôn bật, portable sang Claude Code vì cả hai đọc cùng một chuẩn Agent Skills mở, và miễn phí vì đi kèm sẵn trong Codex. Bắt đầu nhỏ: chọn một việc bạn cứ phải giải thích lại cho Codex mỗi lần, viết một description thật gọn, để progressive disclosure giữ nó rẻ. Nếu không muốn tự xây cả thư viện từ đầu, một bộ kit tuyển chọn như AgentKit là lối tắt trả phí - không phải điều kiện bắt buộc. Muốn xem AGENTS.md nằm cạnh skills thế nào, đọc hướng dẫn AGENTS.md cho Codex, hoặc bắt đầu từ Codex là gì nếu bạn còn chưa nắm tổng quan.