Cách xây dựng kỹ năng lập trình Claude của riêng bạn

Mỗi nhà phát triển cuối cùng đều có một quy trình làm việc lặp đi lặp lại. Một cách họ viết tin nhắn commit. Một danh sách kiểm tra họ chạy trước khi mở pull request. Một cấu trúc họ tuân theo khi xem xét mã. Họ thực hiện thủ công, giải thích cho các agent trong mỗi phiên làm việc, và quan sát cách agent diễn giải khác nhau mỗi lần.
Kỹ năng của tác nhân giải quyết vấn đề này. Kỹ năng là một tệp Markdown được tải tự động vào ngữ cảnh của Claude Code khi bạn cần. Bạn chỉ cần viết quy trình làm việc một lần. Tác nhân sẽ tuân theo quy trình đó mỗi lần. Và vì các kỹ năng tuân theo một tiêu chuẩn mở, cùng một tệp có thể hoạt động trong Claude Code, GitHub Copilot, Cursor và Gemini CLI.
Hướng dẫn này sẽ chỉ cho bạn cách xây dựng một kỹ năng từ đầu. Bạn sẽ xây dựng một trình soạn thảo thông báo commit — một kỹ năng đọc các thay đổi đã được thêm vào vùng chờ và tạo ra một thông báo commit có cấu trúc theo chuẩn Conventional Commits. Sau khi hoàn thành, bạn sẽ có một kỹ năng hoạt động được cài đặt và sẵn sàng sử dụng, và bạn sẽ hiểu cấu trúc đủ tốt để xây dựng bất kỳ kỹ năng nào bạn cần.

Agent skill là gì?

Một skill về cơ bản là một thư mục chứa tệp SKILL.md, trong đó phần YAML frontmatter ở đầu tệp dùng để mô tả tên và cách kích hoạt, còn phần nội dung markdown bên dưới là hướng dẫn cụ thể cho AI thực hiện . Điểm quan trọng nhất là hệ thống sẽ dựa chủ yếu vào trường description để quyết định có nạp skill hay không, nên mô tả càng rõ ràng thì khả năng kích hoạt càng chính xác.
my-skill/
└── SKILL.md

Phần đầu (frontmatter) cho tác nhân biết tên của kỹ năng và thời điểm sử dụng nó. Phần thân (body) cho tác nhân biết phải làm gì khi kỹ năng được tải. Đây là cấu trúc tối thiểu:
---
name: my-skill
description: What this skill does and when to use it.
---

# My Skill
Instructions for the agent go here.

Khi bạn kích hoạt một kỹ năng — bằng cách chỉ định rõ ràng /skill-name hoặc mô tả những gì bạn muốn — tác nhân sẽ đọc nội dung SKILL.md và làm theo các hướng dẫn bên trong đó. Phần frontmatter không bao giờ đến được các hướng dẫn của tác nhân. Đó là siêu dữ liệu mà hệ thống kỹ năng sử dụng để quyết định xem có nên tải kỹ năng đó hay không.

Cách tác nhân quyết định tải kỹ năng

Điều quan trọng nhất cần hiểu trước khi viết kỹ năng đầu tiên của bạn là: hệ thống sẽ quyết định có tải kỹ năng của bạn hay không hoàn toàn dựa trên trường mô tả.

Trong ngữ cảnh của Claude Code, các kỹ năng được hiển thị dưới dạng danh sách tên và mô tả. Khi bạn đưa ra yêu cầu, hệ thống sẽ quét danh sách đó và tải bất kỳ kỹ năng nào có mô tả phù hợp với yêu cầu của bạn. Nếu mô tả không rõ ràng, kỹ năng đó sẽ không được tải khi bạn cần. Nếu mô tả quá cụ thể, kỹ năng đó sẽ không được tải cho các biến thể khác nhau của cùng một yêu cầu.

Các hướng dẫn trong phần thân chỉ có tác dụng sau khi kỹ năng được tải. Việc mô tả chính xác mới quyết định kỹ năng có được tải hay không.

Những kỹ năng nào không phải là

Kỹ năng là các tập tin hướng dẫn. Chúng không thể tự chạy mã — nhưng chúng có thể hướng dẫn tác nhân chạy mã bằng cách sử dụng các công cụ hiện có. Chúng không phải là plugin, tiện ích mở rộng hay gói phần mềm. Chúng không có môi trường thực thi. Chúng là các tập tin định dạng Markdown mà tác nhân đọc, giống như một công thức mà đầu bếp làm theo.

Cách lựa chọn những gì cần xây dựng

Những kỹ năng tốt nhất đều có ba đặc điểm chung.

1. Chúng mã hóa một quy trình làm việc có thể lặp lại. Nếu bạn làm điều gì đó khác nhau mỗi lần, kỹ năng sẽ không giúp ích gì. Nếu bạn tuân theo các bước giống nhau trong mỗi buổi học — ngay cả khi bạn giải thích chúng khác nhau mỗi lần — đó mới là một kỹ năng đáng để học.
2. Chúng có một yếu tố kích hoạt rõ ràng. Bạn phải có khả năng hoàn thành câu "Tôi cần kỹ năng này khi tôi muốn...". Nếu bạn không thể hoàn thành câu đó trong một mệnh đề duy nhất, thì quy trình làm việc chưa đủ cụ thể cho kỹ năng đó.
3. Chúng tạo ra một định dạng đầu ra nhất quán. Các kỹ năng tạo ra đầu ra theo cấu trúc cố định — một thông báo cam kết, một bài đánh giá mã, một bản đặc tả — dễ xây dựng và kiểm thử hơn so với các kỹ năng tạo ra văn bản không có cấu trúc cố định.

Những ví dụ tốt: tin nhắn commit, mô tả pull request, đánh giá mã, mục nhật ký thay đổi. Những ví dụ không tốt: "giúp tôi suy nghĩ thấu đáo hơn", "làm cho điều này tốt hơn" — quá chung chung để mã hóa thành một kỹ năng.
Trong hướng dẫn này, việc tạo thông điệp commit là phạm vi phù hợp. Điều kiện kích hoạt rất rõ ràng (bạn muốn commit), quy trình làm việc được xác định (đọc các thay đổi đã được thêm vào vùng chờ, áp dụng định dạng Commit thông thường), và đầu ra được cấu trúc (một thông điệp commit với hình dạng cụ thể).

Cách cấu trúc kỹ năng của bạn

Mỗi kỹ năng bắt đầu từ một thư mục duy nhất với một tệp tin duy nhất:
commit-message-writer/
└── SKILL.md

Khi kỹ năng được nâng cao, chúng có thể bao gồm thêm các tệp mà tác nhân tải lên khi cần thiết:
commit-message-writer/
├── SKILL.md ← always loaded when skill triggers
└── references/
└── examples.md ← loaded only when the agent needs examples

Nội dung của SKILL.md nên không quá 500 dòng. Nếu hướng dẫn của bạn vượt quá con số đó, hãy chuyển các chi tiết hỗ trợ vào một references/ thư mục con và cho tác nhân biết khi nào cần đọc các tệp đó. Điều này giúp giữ cho kỹ năng gọn nhẹ — tác nhân chỉ tải những gì nó cần.
Đối với hướng dẫn này, chỉ cần một tệp SKILL.md là đủ.

Cách viết phần mô tả

Trường mô tả là điều kiện kích hoạt. Nó quyết định khi nào kỹ năng của bạn được tải và khi nào không. Hầu hết các kỹ năng thất bại không phải vì hướng dẫn sai, mà vì mô tả không khớp với cách mọi người thực sự yêu cầu trợ giúp.
Đây là một mô tả chưa đầy đủ:

description: Generates commit messages.

Thao tác này sẽ không kích hoạt đủ. "Tạo thông báo commit" sẽ tải nó. "Viết commit cho các thay đổi của tôi" có thể sẽ không. "Tóm tắt diff đã được thêm vào" chắc chắn sẽ không — mặc dù cả ba đều yêu cầu cùng một việc.
Dưới đây là một mô tả chi tiết hơn:

description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document code changes for version control.

Cấu trúc như sau: kỹ năng đó làm gì + khi nào sử dụng + các cụm từ kích hoạt cụ thể . Các cụm từ kích hoạt bao gồm nhiều cách khác nhau mà nhà phát triển có thể yêu cầu cùng một việc.
Hai quy tắc dành cho phần mô tả:
Hãy cụ thể về đầu ra. "Tạo thông báo commit" là quá chung chung. "Tạo thông báo commit có cấu trúc theo chuẩn Conventional Commits" sẽ cho cả tác nhân và người dùng biết chính xác những gì họ sẽ nhận được.
Hãy hơi thúc ép một chút. Hệ thống có xu hướng tự nhiên là không kích hoạt kỹ năng đúng cách — tự xử lý yêu cầu thay vì tải kỹ năng. Một mô tả liệt kê rõ ràng các cụm từ kích hoạt sẽ khắc phục điều này. Bạn không hề lặp lại, mà đang huấn luyện cụm từ kích hoạt.

Cách viết hướng dẫn

Phần thân của SKILL.md là nơi bạn định nghĩa những gì tác nhân sẽ làm khi kỹ năng được tải. Các hướng dẫn tốt tuân theo hai nguyên tắc.
Tạo ra kết quả trước, làm rõ sau. Hệ thống nên tạo ra kết quả ngay lập tức thay vì đặt câu hỏi làm rõ. Nếu cần đưa ra giả định, hệ thống nên tự đưa ra và đánh dấu chúng — chứ không phải hỏi. Việc đặt câu hỏi trước khi tạo ra kết quả sẽ làm tăng ma sát và làm mất đi lợi ích của việc sở hữu một kỹ năng nào đó.
Hãy xác định rõ định dạng đầu ra. Đừng chỉ nói "hãy viết một thông báo commit tốt". Hãy nói chính xác cấu trúc là gì, những trường nào bắt buộc, giới hạn ký tự là bao nhiêu. Định dạng đầu ra càng cụ thể, kết quả càng nhất quán.
Đây là ví dụ về các chỉ thị yếu:
# Commit Message Writer
Look at the staged changes and write a commit message that describes what changed.

Điều đó sẽ tạo ra những kết quả khác nhau mỗi lần — các định dạng khác nhau, độ dài khác nhau, quy ước khác nhau. Đó không phải là một kỹ năng. Đó chỉ là một gợi ý.
Đây là những hướng dẫn hiệu quả:

# Commit Message Writer
Read the staged diff using `git diff --staged`. Generate a commit message following the Conventional Commits standard.

Output format:
type(scope): short description under 72 characters

Body (if changes are non-trivial):
- What changed and why, not how
- One bullet per logical change

Footer (if applicable):
BREAKING CHANGE: description
Closes #issue-number

Hệ thống tự động biết chính xác cần tạo ra sản phẩm gì. Kết quả đầu ra sẽ nhất quán giữa các phiên làm việc, giữa các dự án và giữa các hệ thống tự động hỗ trợ tiêu chuẩn này.

Cách xây dựng commit-message-writer kỹ năng

Bây giờ hãy bắt đầu xây dựng. Tạo thư mục kỹ năng:

mkdir -p ~/.claude/skills/commit-message-writer

Trên Windows PowerShell:
Lưu ý: PowerShell sử dụng dấu ngoặc kép ngược ( `) để xuống dòng, chứ không phải dấu gạch chéo ngược.

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

Tạo tệp SKILL.md bên trong thư mục đó. Sau đây là toàn bộ nội dung:
---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document staged changes for version control.
---

# commit-message-writer
You generate structured commit messages from staged git changes.

## How to invoke
Run `git diff --staged` to read the staged changes. If nothing is staged, tell the user and suggest they run `git add` first.

Generate first. Do not ask clarifying questions before producing the commit message.
If you need to make assumptions about scope or type, make them and note them after the output.

## Output format
~~~
type(scope): short description
[body — optional, include if changes are non-trivial]
[footer — optional]
~~~

**Type** — choose one:
- `feat` — a new feature
- `fix` — a bug fix
- `docs` — documentation changes only
- `refactor` — code change that neither fixes a bug nor adds a feature
- `test` — adding or updating tests
- `chore` — build process, tooling, or dependency updates

**Scope** — the module, file, or area affected. Use the directory name or component name. Omit if the change spans the entire codebase.

**Short description** — imperative mood, under 72 characters, no period at the end.
"Add user authentication" not "Added user authentication" or "Adds user authentication."

**Body** — what changed and why, not how. One bullet per logical change. Skip if the short description is self-explanatory.

**Footer** — include `BREAKING CHANGE:` if the commit breaks backward compatibility.
Include `Closes #N` if it resolves a GitHub issue.

## Quality rules

- Never use "updated", "changed", or "modified" in the short description — be specific
- Never write "various improvements" or "misc fixes" — name what improved
- If more than three files changed across unrelated concerns, flag it:
"These changes may be better split into separate commits: [list concerns]"
- The short description must be under 72 characters — count before outputting

## Example output
Input: staged changes adding a rate limiter to an API endpoint

~~~

feat(api): add rate limiting to /query endpoint
- Limits requests to 100 per minute per IP using Cloudflare's rate limit binding
- Returns 429 with Retry-After header when limit is exceeded
- Adds rate limit configuration to wrangler.toml
Closes #47
~~~

Hãy lưu tập tin đó lại. Kỹ năng đã được rèn luyện xong.

Hướng dẫn cài đặt và kiểm tra kỹ năng của bạn

Xác minh tệp tin có tồn tại hay không

cat ~/.claude/skills/commit-message-writer/SKILL.md

Bạn sẽ thấy toàn bộ nội dung của SKILL.md. Nếu gặp lỗi, hãy kiểm tra đường dẫn thư mục.

Kiểm tra kỹ năng

Mở Claude Code trong bất kỳ kho lưu trữ Git nào có các thay đổi đã được thêm vào vùng chờ. Gõ:

/commit-message-writer

Công cụ này sẽ đọc bản diff bạn đã thêm vào và tạo ra thông báo commit theo định dạng bạn đã xác định.
Bạn cũng có thể kích hoạt nó một cách tự nhiên:
write a commit message for my staged changes

what should my commit say

summarize my diff for git

Cả ba đều cần tải kỹ năng và tạo ra thông báo cam kết có cấu trúc. Nếu kỹ năng không được kích hoạt khi nhận yêu cầu bằng ngôn ngữ tự nhiên, phần mô tả cần thêm các cụm từ kích hoạt — xem phần cải tiến bên dưới.

Kiểm thử các trường hợp ngoại lệ

Hãy kiểm tra các trường hợp này trước khi áp dụng kỹ năng đó vào thực tế:
# Stage nothing, then ask for a commit message git add -p # stage nothing
# In Claude Code: "write a commit message"
# Expected: skill tells you nothing is staged and suggests git add
# Stage changes across unrelated files git add src/api.ts src/styles.css README.md
# In Claude Code: "write a commit message"
# Expected: skill flags that commits may be better split

Làm thế nào để nâng cao kỹ năng của bạn theo thời gian

Phiên bản đầu tiên của bất kỳ kỹ năng nào đều là bản nháp. Bạn cải thiện nó bằng cách quan sát những chỗ nó tạo ra kết quả không nhất quán hoặc sai, sau đó cập nhật các hướng dẫn.

Khi kỹ năng không được kích hoạt đầy đủ

Nếu bạn gõ "summarize my changes for git" và kỹ năng không tải được, hãy thêm cụm từ đó vào danh sách kích hoạt trong phần mô tả:
description: ... Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "summarize my changes for git", ...

Phần mô tả là công cụ chính giúp bạn khắc phục các sự cố kích hoạt.

Khi định dạng đầu ra thay đổi

Nếu tác nhân bắt đầu tạo ra các thông báo commit không khớp với định dạng của bạn — sai kiểu dữ liệu, thiếu phạm vi, nội dung không đúng định dạng — thì hướng dẫn cần phải rõ ràng hơn. Thêm một ví dụ cụ thể cho thấy lỗi và kết quả đúng:
## Common mistakes to avoid

Wrong: "Updated the authentication flow"
Right: "refactor(auth): simplify token validation logic"

Wrong: "Fixed bugs"
Right: "fix(api): handle null response from upstream service"

Các ví dụ phản chứng cụ thể hiệu quả hơn các quy tắc trừu tượng.

Khi phạm vi mở rộng

Nếu bạn thấy mình cần kỹ năng xử lý các nhiệm vụ liên quan — xem xét thông báo commit, tạo nhật ký thay đổi, viết mô tả yêu cầu kéo — hãy tránh việc gộp tất cả vào một kỹ năng duy nhất. Hãy xây dựng các kỹ năng riêng biệt. Mỗi kỹ năng nên làm tốt một việc. Tiêu chuẩn Kỹ năng Agent được thiết kế để kết hợp các kỹ năng, chứ không phải để truyền đạt các chỉ dẫn nguyên khối.

Đi đâu tiếp theo?

Công cụ ghi thông báo cam kết (commit-message-writer) bao gồm mô hình cốt lõi. Cấu trúc tương tự cũng hoạt động với bất kỳ quy trình làm việc lặp lại nào.
Mô tả yêu cầu kéo (pull request) tuân theo cùng một cấu trúc — đọc sự khác biệt, áp dụng cấu trúc, tạo ra kết quả nhất quán. Các cụm từ kích hoạt khác nhau ("viết mô tả yêu cầu kéo", "tóm tắt nhánh của tôi để xem xét") và định dạng đầu ra bổ sung thêm các phần về động lực và thử nghiệm, nhưng cấu trúc SKILL.md vẫn giống hệt nhau.
Danh sách kiểm tra đánh giá mã hoạt động hiệu quả như một kỹ năng khi nhóm của bạn có quy trình đánh giá tiêu chuẩn. Tín hiệu kích hoạt là "xem xét mã này" hoặc "kiểm tra yêu cầu kéo này", và các hướng dẫn mã hóa bất cứ điều gì nhóm của bạn thực sự kiểm tra — các vấn đề bảo mật, độ phủ kiểm thử, quy ước đặt tên.
Mô hình người soạn thảo thông báo commit là kiến ​​trúc kỹ năng đơn giản nhất — chỉ bao gồm các hướng dẫn. Khi kỹ năng của bạn trở nên chuyên biệt hơn, hai mô hình khác sẽ trở nên hữu ích.
Phương pháp đầu tiên thêm một references/ thư mục: kỹ năng chuyển đổi giọng nói thành giọng người tải tệp CORPUS.md chứa các bài viết đã xuất bản của tác giả, mà tác nhân sẽ đọc khi cần kiểm tra đầu ra so với một phong cách cụ thể. Phương pháp thứ hai thêm các quy tắc chất lượng và định dạng đầu ra có cấu trúc giúp kết quả chính xác và nhất quán hơn — đó là mẫu mà người viết đặc tả sử dụng để đưa ra các giả định ngay trong nội tuyến. Mỗi phương pháp đều có cấu trúc SKILL.md giống nhau nhưng ở mức độ phức tạp khác nhau.
Hãy bắt đầu chỉ với hướng dẫn. Thêm tài liệu tham khảo khi người dùng cần ngữ cảnh bên ngoài. Thêm quy tắc định dạng đầu ra khi tính nhất quán quan trọng hơn tính linh hoạt.
Chuẩn Agent Skills được hỗ trợ trong Claude Code, GitHub Copilot trong VS Code, Cursor và Gemini CLI. Một kỹ năng bạn xây dựng một lần sẽ được cài đặt trên tất cả các công cụ này. Đường dẫn cài đặt khác nhau tùy thuộc vào tác nhân:

Đại lý	Danh mục kỹ năng
Mã Claude	~/.claude/skills/
GitHub Copilot	~/.copilot/skills/hoặc.github/skills/
Con trỏ	~/.cursor/skills/
Công cụ dòng lệnh Gemini	~/.gemini/skills/

Định dạng SKILL.md giống nhau ở tất cả các tệp.

Công cụ soạn thảo thông báo commit mà bạn vừa xây dựng là một kỹ năng hữu ích. Công cụ tiếp theo sẽ mất ít thời gian hơn. Đến công cụ thứ ba, bạn sẽ bắt đầu nhận thấy các quy trình làm việc mà bạn lặp.

Điều rút ra thực tế
Điểm mạnh của agent skill nằm ở chỗ bạn chỉ cần viết quy trình một lần nhưng có thể tái sử dụng ở nhiều phiên làm việc và nhiều công cụ khác nhau . Khi workflow của bạn đủ lặp lại và đủ rõ ràng, skill sẽ giúp giảm rất nhiều thao tác nhắc lại và làm cho đầu ra ổn định hơn .
Nếu bạn thường xuyên phải sửa cùng một kiểu việc theo một chuẩn cố định, thì rất có thể việc đó nên được đóng gói thành một skill. Sau khi tự làm vài skill đầu tiên, bạn sẽ bắt đầu nhìn nhiều tác vụ quen thuộc và nghĩ ngay rằng “đáng lẽ nó phải là một skill”.