# Skill Codex đầu tiên: biến một workflow thành SKILL.md

[Chuck McCullough](https://homus.dev/speakers/chuck-mccullough) · [Coding With Chuck](https://homus.dev/orgs/coding-with-chuck)

> Cách biến một workflow đã làm ra thành skill Codex: thư mục .agents/skills, SKILL.md với name và description, progressive disclosure, và kiểm skill có chạy thật.

Topics: Skills, Coding Agents, Workflow

Canonical: https://homus.dev/talks/create-your-first-codex-skill-turn-a-workflow-into-skill-md

## 1. Vì sao lại phải giải quyết chuyện này lần nữa?

Chuck McCullough mở đầu video (đăng ngày 30/10/2026) bằng một câu hỏi: bạn đã bao giờ mất nửa cuộc hội thoại chỉ để khiến một agent làm một việc theo đúng cách bạn muốn chưa? Bạn thử vài tool, sửa output, và cuối cùng có được một quy trình chạy được. Rồi một cuộc hội thoại mới bắt đầu, và bạn lại ngồi giải thích lại đúng những quyết định ấy.

Anh kể mình đã gặp đúng chuyện này khi làm các bài thuyết trình cho khoá học. Phần có ích của cuộc hội thoại kia, theo anh, chính là tất cả những gì anh học được về quy trình, và anh muốn giữ lại phần đó.

![Slide mở đầu Why are we solving this again? cạnh Chuck McCullough](https://homus.dev/photos/0KC2BQBxNq8-0023.jpg)

Slide mở đầu "Why are we solving this again?" (bài Creating skills, Chuck McCullough): hôm qua người dùng nói "That worked. Use that process.", còn trong một cuộc hội thoại mới agent lại trả lời "Let me try a few approaches..." (slide trong video đăng ngày 30/10/2026).

Khi làm việc với một agent, anh nói (video đăng ngày 30/10/2026), ta thường đang đi qua vài bước của một workflow lớn hơn. Ví dụ, anh có thể đang làm một bài thuyết trình cho một khoá đào tạo anh đang xây dựng. Việc đó gồm nhiều bước, từ lập dàn ý tới thiết kế slide và chuẩn bị speaker notes.

Khi bắt đầu nhờ agent giúp, anh thấy có những lần tương tác suôn sẻ hơn nhiều so với những lần khác. Rất nhiều thứ phụ thuộc vào cách agent tiếp cận việc giúp anh (theo trải nghiệm Chuck kể trong video đăng ngày 30/10/2026). Qua nhiều lần tương tác, anh dần học được cách tiếp cận nào hiệu quả nhất với mình.

## 2. Skill giữ lại một workflow dùng lại được

Bây giờ anh muốn ghi lại những hướng dẫn, những lựa chọn tool và những hành động đó, để agent dùng lại được quy trình ấy. Theo Chuck (video đăng ngày 30/10/2026), đó là việc một skill cho phép anh làm: đóng gói một workflow dùng lại được thành các chỉ dẫn (instructions), kèm file hỗ trợ khi cần.

![Slide A skill captures a reusable workflow](https://homus.dev/photos/0KC2BQBxNq8-0123.jpg)

Slide "A skill captures a reusable workflow": skill là những chỉ dẫn giữ lại cách bạn làm một việc, kèm file hỗ trợ khi cần, để lần sau dùng lại quy trình bạn đã tìm ra (slide trong video đăng ngày 30/10/2026).

## 3. Ví dụ: từ video tới slideshow, và bài học về FFmpeg, Whisper

Anh đưa một ví dụ. Trong công việc, anh thường có một video hoặc một bản ghi âm anh giảng giải một chủ đề. Từ đó, anh muốn tạo ra một slideshow.

Slideshow là đích cuối, nhưng để tới đó có nhiều bước: thứ nhất là chuyển âm thanh thành chữ (transcribe), rồi tóm tắt các ý chính, thiết kế slide và thêm speaker notes.

![Slide A presentation has several jobs với sáu bước từ .mp4 tới Notes](https://homus.dev/photos/0KC2BQBxNq8-0143.jpg)

Slide "A presentation has several jobs": .mp4 (bản ghi) → Audio (tách nếu cần) → Text (transcribe) → Ideas (chọn và nhóm) → Slides (giải thích bằng hình) → Notes (phát triển phần học). Dòng cuối: một workflow tốt ghi lại cách bạn đi giữa các bước này (slide trong video đăng ngày 30/10/2026).

Một điều anh học được trong workflow của mình (theo lời anh trong video đăng ngày 30/10/2026) là tách âm thanh ra khỏi video trước khi transcribe cho anh kết quả tốt hơn, và anh tìm được một tool tên là FFmpeg làm được việc đó. Anh cũng học được rằng có nhiều cách để transcribe âm thanh. Trong một số cuộc hội thoại, agent thử vài cách khác nhau, thất bại, rồi cứ thử tiếp cho tới khi tìm được cách chạy được.

Chuck thấy dùng Whisper để transcribe là cách đáng tin cậy nhất với nhu cầu của anh (theo trải nghiệm anh kể trong video đăng ngày 30/10/2026). Giờ anh có thể viết một script tách âm thanh từ video rồi transcribe bằng Whisper, và như vậy anh có một pipeline lặp lại được. Anh vẫn sẽ cần xem lại bản chữ để sửa lỗi, hoặc nhờ agent làm việc đó.

## 4. Phần cho tool, phần cho model, và giá trị của kinh nghiệm

Theo Chuck (video đăng ngày 30/10/2026), tóm tắt ý chính và thiết kế slide thì đòi hỏi nhiều phán đoán hơn. Đó là phần anh cần model làm. Khi tới bước tạo bài thuyết trình, anh thấy mình cần đưa khá nhiều hướng dẫn về nội dung slide, cũng như nên dùng ứng dụng trình chiếu nào.

![Slide Tool calls and decisions need different help, hai cột](https://homus.dev/photos/0KC2BQBxNq8-0243.jpg)

Slide "Tool calls and decisions need different help". Cột trái, chạy các tool dòng lệnh: FFmpeg → audio, Whisper → bản chữ, kiểm các file output, và ghi tên tool cùng các tuỳ chọn vào chỉ dẫn của skill. Cột phải, để model quyết: ý nào thuộc về nhau, cái gì giải thích bằng hình được, chỗ nào cần giải thích thêm trong attendee notes (slide trong video đăng ngày 30/10/2026).

Qua các vòng lặp đó (theo lời anh trong video đăng ngày 30/10/2026), anh học được về các tool để tạo ra những loại nội dung khác nhau, và cách chỉ đạo agent tạo nội dung rồi kiểm tra lại nội dung đó.

Theo Chuck, ghi lại những gì bạn biết là phần quan trọng nhất. Ngay cả khi model rốt cuộc cũng tự nghĩ ra được một lời giải chấp nhận được, kiến thức của bạn có thể giúp tiết kiệm thời gian và tiền bạc (theo Chuck, video đăng ngày 30/10/2026).

## 5. Một yêu cầu ngắn, một quy trình đứng sau

Vì vậy khi anh nói với agent: tôi có một video nói về một chủ đề nào đó trong file này, tên file là thế này, hãy tạo slideshow cho tôi, anh kỳ vọng nó đi theo skill anh đã xây. Theo Chuck (video đăng ngày 30/10/2026), khi skill đó được chọn, quy trình đã nằm sẵn ở đó: tách âm thanh nếu cần, transcribe bằng Whisper, tóm tắt các ý chính, thiết kế slide, thêm speaker notes bằng tool trình chiếu anh ưa dùng.

![Slide A short request can have a process behind it với yêu cầu của người dùng và câu trả lời của agent](https://homus.dev/photos/0KC2BQBxNq8-0343.jpg)

Slide "A short request can have a process behind it": người dùng gõ "I have a video in xxx.mp4. Please create a slide show for me."; khi skill phù hợp được chọn, agent trả lời rằng nó sẽ chuẩn bị âm thanh nếu cần, transcribe, sắp xếp ý, rồi dựng slide và attendee notes (ví dụ minh hoạ trên slide của video đăng ngày 30/10/2026).

Agent khi đó có sẵn những lựa chọn tool và tuỳ chọn đã chạy được của anh, thay vì phải tự khám phá lại từ đầu. Theo Chuck (video đăng ngày 30/10/2026), điều đó có thể cải thiện hiệu quả và độ nhất quán, và giảm chi phí agent. Anh nói tất nhiên vẫn cần kiểm tra kết quả, nhưng mục tiêu là giảm thời gian và giảm chi phí.

## 6. Skill đi vào context của agent như thế nào

Chuck giải thích (video đăng ngày 30/10/2026): AI client ráp context cho model từ prompt của bạn, phần lịch sử hội thoại liên quan, các chỉ dẫn áp dụng như `AGENTS.md`, và thông tin về các tool cùng các skill đang có. Với skill, ban đầu model thấy tên và mô tả. Trong Codex, nó còn thấy cả đường dẫn file của chúng.

![Slide A skill joins the agent's working context, ô Skill metadata được khoanh](https://homus.dev/photos/0KC2BQBxNq8-0423.jpg)

Slide "A skill joins the agent's working context": User request, Relevant history, Instructions và Skill metadata (ô được khoanh) đi vào bước "Model chooses the next action" (đọc một skill, gọi một tool, hoặc trả lời), rồi Tool call → Tool result → Model continues. Hai dòng cuối: chỉ dẫn trong SKILL.md được chọn sẽ vào context, resource nạp khi cần; host quyết định cái gì được đưa vào và lúc nào (theo slide, video đăng ngày 30/10/2026).

Khi model quyết định dùng một skill, nó đọc file `SKILL.md` của skill đó. Sau đó nó có thể đọc thêm các tài liệu tham khảo hỗ trợ hoặc chạy script khi cần. Chuck nói đó là cái ta gọi là progressive disclosure: chỉ dẫn chi tiết và resource chỉ vào context khi chúng hữu ích. Một task có thể dùng nhiều hơn một skill, và model tiếp tục làm việc với các chỉ dẫn này bên cạnh phần còn lại của context (theo Chuck, video đăng ngày 30/10/2026).

Anh nói thêm (video đăng ngày 30/10/2026): việc chọn một skill không bảo đảm mọi bước sẽ chạy đúng.

Trang tài liệu skill của Codex (đọc ngày 31/10/2026) cũng mô tả cùng cơ chế: Codex bắt đầu với tên và mô tả của từng skill, kèm đường dẫn file, rồi mới nạp toàn bộ chỉ dẫn trong `SKILL.md` khi quyết định dùng skill đó.

## 7. Tạo thư mục skill trong Codex

Theo hướng dẫn của Chuck (video đăng ngày 30/10/2026), trong Codex bạn bắt đầu với một thư mục `.agents` ở cấp user hoặc cấp project, tuỳ bạn muốn skill dùng được ở đâu. Các ứng dụng agent khác có thể dùng vị trí khác.

Tiếp theo, theo Chuck (video đăng ngày 30/10/2026), tạo một thư mục con tên là skills. Trong thư mục skills, tạo một thư mục riêng cho mỗi skill và đặt tên thư mục trùng với tên skill: dùng chữ thường, chữ số và dấu gạch nối, không có khoảng trắng. Chọn một cái tên giúp nhận ra đó là task gì. Còn phần mô tả (description) là nơi ta nói rõ khi nào agent nên cân nhắc dùng skill.

![Slide A skill is a folder with a SKILL.md file, cây thư mục .agents/skills/agent-chat-mood/SKILL.md](https://homus.dev/photos/0KC2BQBxNq8-0523.jpg)

Slide "A skill is a folder with a SKILL.md file": cây thư mục `.agents/skills/agent-chat-mood/SKILL.md`. Bên phải: cấp Project dùng chung với repo này, cấp User dùng được ở mọi project của bạn; hãy dùng những vị trí mà ứng dụng agent của bạn hỗ trợ. Dòng dưới: chọn tên task dễ nhận ra, tên thư mục khớp với name trong front matter (theo slide, video đăng ngày 30/10/2026).

Cấu trúc trên slide:

```
.agents/
└ skills/
└ agent-chat-mood/
└ SKILL.md
```

Tài liệu Codex (đọc ngày 31/10/2026) ghi vị trí cấp repo là `$REPO_ROOT/.agents/skills` (và các thư mục `.agents/skills` từ thư mục đang làm việc lên tới gốc repo), còn cấp user là `$HOME/.agents/skills`. Đặc tả Agent Skills (đọc ngày 31/10/2026) ghi trường name chỉ gồm chữ thường, số và dấu gạch nối, và phải khớp tên thư mục cha.

## 8. SKILL.md và YAML front matter

Bên trong thư mục skill, tạo một file tên `SKILL.md`. Theo Chuck (video đăng ngày 30/10/2026), file này chứa tài liệu và chỉ dẫn cho skill, gồm các bước, các tool và các nguyên tắc agent cần theo khi áp dụng skill.

Phần đầu file là YAML front matter. Nằm giữa hai dòng ba dấu gạch ngang, nó chứa tên skill (khớp với tên thư mục) và một mô tả. Mô tả đó cho agent biết skill làm gì và khi nào nên cân nhắc dùng nó (theo Chuck, video đăng ngày 30/10/2026).

![Slide The description tells the agent when to consider it với front matter của create-slide-show-from-video](https://homus.dev/photos/0KC2BQBxNq8-0543.jpg)

Slide "The description tells the agent when to consider it": front matter của skill `create-slide-show-from-video`. Name là một workflow dễ nhận ra; description là task sẽ khiến agent cân nhắc dùng skill (slide trong video đăng ngày 30/10/2026).

Front matter trên slide:

```
---
name: create-slide-show-from-video
description: >
Create a slide show from a local video recording.
---
```

Với việc chọn tự động, tên và mô tả của skill giúp model quyết định skill đó có liên quan hay không (theo Chuck, video đăng ngày 30/10/2026).

## 9. Chọn skill tự động hay gọi đích danh

Theo Chuck (video đăng ngày 30/10/2026), việc chọn dựa trên ý nghĩa, nên một yêu cầu về làm slide từ video có thể khớp với skill của anh. Nhưng không phải cứ prompt chứa vài từ khoá nhất định là chắc chắn khớp. Khi skill đã được chọn, model đọc toàn bộ chỉ dẫn của nó, rồi dùng bất kỳ resource hỗ trợ nào nó cần.

Bạn cũng có thể gọi đích danh skill ngay trong prompt. Trong Codex CLI hoặc IDE extension, bạn có thể dùng bộ chọn skill (skills selector) hoặc nhắc tên skill bằng dấu đô la (theo Chuck, video đăng ngày 30/10/2026). Các client khác dùng cách chọn khác, nên hãy xem danh sách trên máy của bạn. Tài liệu Codex (đọc ngày 31/10/2026) ghi: trong Codex CLI hoặc IDE extension, chạy `/skills` hoặc gõ `$` để nhắc tới một skill.

Hai đường để một skill được dùng theo Chuck (video đăng ngày 30/10/2026): model tự chọn dựa trên ý nghĩa của name và description (không bảo đảm khớp chỉ vì có từ khoá), hoặc người dùng gọi đích danh bằng skills selector hay dấu đô la trong Codex CLI và IDE extension.

## 10. Skill chào hỏi theo ngày trong tuần

Chuck cho xem một skill đơn giản anh tạo ra để đổi giọng hội thoại của agent theo ngày trong tuần. Theo anh (demo trong video đăng ngày 30/10/2026), workflow này dùng tool call để tìm ra hôm nay là thứ mấy và thêm một chút ngẫu nhiên vào tâm trạng (mood). Phần mô tả cần khớp với những lời chào anh nhắm tới mà không khớp với các yêu cầu không liên quan.

![Slide A small greeting skill makes the process visible với front matter của agent-chat-mood](https://homus.dev/photos/0KC2BQBxNq8-0703.jpg)

Slide "A small greeting skill makes the process visible": front matter của skill `agent-chat-mood`, mô tả "Use a weekday-influenced mood for personal greetings.", kèm metadata version "1.1.0". Dòng dưới: trong SKILL.md, metadata nằm trên dấu phân cách, chỉ dẫn cho tool nằm bên dưới (slide trong video đăng ngày 30/10/2026).

Theo Chuck (demo trong video đăng ngày 30/10/2026), phần thân file đưa ra những chỉ dẫn cụ thể anh muốn agent dùng, ví dụ hai lệnh PowerShell: Get-Date và Get-Random. Nội dung `SKILL.md` trên slide, phần front matter và phần thân ("Then the body gives the process"):

```
---
name: agent-chat-mood
description: >
Use a weekday-influenced mood
for personal greetings.
metadata:
version: "1.1.0"
---

1. Run Get-Date for the weekday.
Monday = 1 … Sunday = 7.
2. Run Get-Random
-Minimum -1 -Maximum 2.
3. Add day + adjustment.
4. Choose a matching persona.
5. Reply; keep the index internal.
```

## 11. Phép tính mood index và lần sửa đầu tiên

Theo Chuck (demo trong video đăng ngày 30/10/2026), skill đánh số thứ Hai là 1 và Chủ nhật là 7, rồi cộng thêm một điều chỉnh ngẫu nhiên là trừ 1, 0 hoặc cộng 1. Kết quả là một mood index từ 0 tới 8: 0 là cáu kỉnh (grumpy), 8 là vui vẻ và lạc quan. Các số ở giữa là những tâm trạng trung gian.

![Slide The response follows a small calculation: Weekday, Adjustment, Mood index, Reply và thang 0 Grumpy tới 8 Cheerful](https://homus.dev/photos/0KC2BQBxNq8-0743.jpg)

Slide "The response follows a small calculation": Weekday (Monday 1 ... Sunday 7) → Adjustment (−1, 0 hoặc +1) → Mood index (ngày + điều chỉnh) → Reply (dùng giọng tương ứng), cùng thang từ 0 Grumpy tới 8 Cheerful. Dòng cuối: dùng mood, giữ index ở bên trong (slide trong video đăng ngày 30/10/2026).

Lần đầu Chuck thử skill này (demo trong video đăng ngày 30/10/2026), agent trả lời và để lộ cả index đã tính, nói những câu kiểu: vì hôm nay là thứ Hai nên tôi phải cáu kỉnh.

Nên anh thêm một chỉ dẫn: giữ index ngoài lời chào, thay vào đó dùng một persona hợp với tâm trạng. Khi bạn gửi cho agent một lời chào mang tính cá nhân, nó có thể chọn skill này để xác định tâm trạng phù hợp và trả lời theo đó, bằng một persona khớp với tâm trạng ấy (theo Chuck, video đăng ngày 30/10/2026).

## 12. Thử vào thứ Hai và thứ Sáu

Một hôm thứ Hai, Chuck cố tình gửi một lời chào vui vẻ, phấn chấn. Câu trả lời của agent có ghi nhận tin vui, nhưng giọng thì rõ ràng khô khan và cáu kỉnh (demo trong video đăng ngày 30/10/2026).

Rồi anh thử vào một ngày thứ Sáu. Anh làm ngược lại với tâm trạng của chính mình và đưa một prompt u ám. Agent trả lời theo kiểu nhìn thấy nửa ly đầy (demo trong video đăng ngày 30/10/2026).

![Slide Friday: a more playful reply với prompt về trận bóng bầu dục đại học và câu trả lời của agent](https://homus.dev/photos/0KC2BQBxNq8-0843.jpg)

Slide "Friday: a more playful reply": người dùng viết rằng cuối tuần sẽ đi xem trận bóng bầu dục đại học, đội nhà có lẽ sẽ thua, "I'm a glutton for punishment"; agent đáp "Ah, a brave soul entering the arena anyway, magnificent." và nói thắng hay thua thì vẫn có ban nhạc, tiếng ồn và sự hỗn loạn huy hoàng, "That's not punishment; that's tradition with snacks." (demo trong video đăng ngày 30/10/2026).

Câu trả lời trông nhất quán với skill, nhưng theo Chuck, chỉ riêng giọng điệu thì chưa chứng minh được skill đã chạy. Anh phải xem các tool log có sẵn và chi tiết cuộc chat để kiểm xem agent có đọc skill và có chạy các lệnh bắt buộc hay không (demo trong video đăng ngày 30/10/2026).

## 13. Execution record mới là thứ để kiểm

Chuck nói mục tiêu thật của anh không phải là chính lời chào theo tâm trạng. Anh chỉ muốn cho thấy (demo trong video đăng ngày 30/10/2026) phần mô tả có dẫn tới việc chọn skill hay không, và agent có thực thi các bước anh đã định nghĩa hay không. Câu trả lời là một cách nhanh để quan sát kết quả mong muốn; còn execution record (bản ghi thực thi) mới là thứ cho phép kiểm tra quy trình thật sự.

![Slide What would you inspect next? với ba câu hỏi về execution record](https://homus.dev/photos/0KC2BQBxNq8-0903.jpg)

Slide "What would you inspect next?", phần execution record: skill nào đã được đọc, Get-Date và Get-Random có chạy không, và đầu vào, index cùng câu trả lời có khớp nhau không. Dòng cuối: "Try it: create SKILL.md, vary the prompts, and inspect the steps." (slide trong video đăng ngày 30/10/2026).

Còn bây giờ, theo Chuck (video đăng ngày 30/10/2026), các ví dụ này cho ta một lần kiểm tra đầu tiên, chứ chưa chứng minh được skill chạy ổn định.

## 14. Đến lượt bạn thử

Chuck giao bài (video đăng ngày 30/10/2026): tạo cấu trúc thư mục và một file `SKILL.md`. Đặt vào vài chỉ dẫn đơn giản, rồi thử các prompt khác nhau để xem cái gì kích hoạt skill và cái gì không. Kiểm xem agent thực sự đã làm theo những chỉ dẫn nào.

Anh nhắc: chuyện này không tất định (non-deterministic). Theo Chuck (video đăng ngày 30/10/2026), agent vẫn đang dùng large language model. Tất cả những gì bạn làm với skill là bổ sung vào context gửi tới large language model, và bạn vẫn đang đi theo một kết quả mang tính xác suất (probabilistic outcome). Rồi anh nói thêm: thử nói câu đó nhanh ba lần xem.

Bài tập Chuck giao trong video đăng ngày 30/10/2026: tạo cấu trúc thư mục và SKILL.md với vài chỉ dẫn đơn giản, đổi prompt để xem cái gì kích hoạt skill và cái gì không, rồi kiểm xem agent thực sự làm theo chỉ dẫn nào.

## 15. Từ file prompt copy-paste tới một skill

Chuck nói có thể bạn đang có một file đầy prompt để copy rồi paste vào cuộc hội thoại. Có khi bạn còn có những "công thức" (recipes), thả lần lượt vài prompt vào cuộc hội thoại. Theo anh (video đăng ngày 30/10/2026), đó chính là một workflow.

Anh kể vài hôm trước khi quay video (video đăng ngày 30/10/2026), anh vừa nói chuyện với một người bạn về đúng chuyện này, và đó là cách cô ấy làm: cứ thả các prompt vào. Anh bảo cô: hãy làm một skill. Lấy kiến thức và kinh nghiệm của mình biến thành một skill.

Lần tới khi có task đó, bạn chỉ cần bảo agent dùng quy trình bạn đã tìm ra. Theo Chuck (video đăng ngày 30/10/2026), việc đó giúp bạn khỏi phải đưa từng bước cho agent lần nữa, trong khi bạn vẫn xem lại kết quả và xử lý những quyết định cần tới ý kiến của bạn.

Cuối video, anh giới thiệu mình là Chuck McCullough.

## Nguồn và liên kết

- Tên gốc: Create Your First Codex Skill: Turn a Workflow into SKILL.md
- Sự kiện: [YouTube](https://homus.dev/events/youtube)
- Video gốc: [https://www.youtube.com/watch?v=0KC2BQBxNq8](https://www.youtube.com/watch?v=0KC2BQBxNq8)

- Kênh YouTube Coding With Chuck (Chuck McCullough): [youtube.com/channel/UCx5fdKheO1UBTKUfRRSpZ3Q](https://www.youtube.com/channel/UCx5fdKheO1UBTKUfRRSpZ3Q)

- Tài liệu Agent Skills của Codex (vị trí `.agents/skills` theo cấp repo và user, progressive disclosure, gọi skill bằng `/skills` hoặc `$`; đọc ngày 31/10/2026): [developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

- Đặc tả Agent Skills (quy tắc cho trường name và description trong SKILL.md; đọc ngày 31/10/2026): [agentskills.io/specification](https://agentskills.io/specification)

Nguồn: https://homus.dev/talks/create-your-first-codex-skill-turn-a-workflow-into-skill-md · cập nhật 2026-10-31