Tự viết skill đầu tiên: cấu trúc tệp SKILL.md

Bài này dựa trên tài liệu Claude Code về skill và hướng dẫn viết skill của Anthropic, đọc ngày 11/11/2026. Tên trường, giới hạn và lệnh dưới đây là điều tài liệu hiện ghi; công cụ đổi nhanh nên hãy đối chiếu lại nếu bạn thấy khác. Chưa biết skill là gì thì đọc trước Agent Skills là gì.

Chọn việc nào để viết thành skill?

Sai lầm hay gặp nhất khi viết skill đầu tiên là viết trước rồi mới nghĩ xem nó giải quyết gì. Hướng dẫn của Anthropic đề nghị làm ngược lại: cứ làm việc thật với AI mà chưa có skill, và ghi lại những chỗ bạn phải giải thích đi giải thích lại hoặc chỗ AI làm sai. Hướng dẫn gọi cách này là xây phần đánh giá trước, viết tài liệu sau, để skill giải quyết vấn đề có thật chứ không phải vấn đề tưởng tượng.

Một việc đáng làm thành skill thường có ba đặc điểm: bạn nhắc lại nó từ lần thứ ba trở đi, nó có vài bước hoặc tiêu chuẩn riêng, và kết quả đúng hay sai nhìn thấy được. Ví dụ: soạn thông điệp commit theo mẫu của nhóm, viết báo cáo tuần theo khuôn, dịch tài liệu mà giữ nguyên tên hàm. Bài này lấy ví dụ đầu tiên, skill viet-commit, vì nó nhỏ và kiểm được ngay bằng một thay đổi git bất kỳ.

Viết skill đầu tiên từng bước

Các bước dưới đây tạo skill ở phạm vi cá nhân, dùng được ở mọi dự án trên máy bạn, theo cách tài liệu Claude Code hướng dẫn.

Bước 1. Tạo thư mục. Tên thư mục chính là tên skill. Trong terminal:

mkdir -p ~/.claude/skills/viet-commit

Bước 2. Viết tệp SKILL.md trong thư mục đó, với nội dung sau:

---
name: viet-commit
description: Soạn thông điệp commit theo mẫu type(scope) rồi mô tả ngắn, dựa trên git diff. Dùng khi người dùng nhờ viết commit message hoặc xem lại thay đổi đã stage.
---

## Cách làm

1. Đọc thay đổi đã stage bằng git diff --staged.
2. Chọn type (feat, fix, docs, refactor, test, chore) và scope là thư mục hay mô-đun bị đổi nhiều nhất.
3. Viết dòng đầu theo mẫu type(scope): mô tả, dưới 72 ký tự, không có dấu chấm cuối.
4. Nếu thay đổi gồm nhiều việc không liên quan, đề nghị tách thành nhiều commit thay vì gộp.

## Ví dụ

Thay đổi: thêm kiểm tra email rỗng ở form đăng ký.
Kết quả: fix(auth): chặn email rỗng ở form đăng ký

Bước 3. Thử. Mở Claude Code trong một dự án git có thay đổi đã stage. Có hai cách gọi: hỏi tự nhiên ("viết giúp tôi commit message cho thay đổi này") để xem agent có tự dùng skill không, hoặc gõ /viet-commit để gọi thẳng. Theo tài liệu, Claude Code theo dõi các thư mục skill nên thêm, sửa hay xóa skill có hiệu lực ngay trong phiên đang mở, không cần khởi động lại. Có một ngoại lệ: nếu bạn vừa tạo thư mục ~/.claude/skills/ mà lúc khởi động nó chưa tồn tại, hãy chạy /reload-skills.

Chỉ vậy là xong skill đầu tiên. Tài liệu Claude Code còn có một mẹo hay: trong thân skill, một dòng bắt đầu bằng dấu chấm than và đặt lệnh trong dấu nháy ngược (ví dụ để lấy kết quả git diff HEAD) sẽ được chạy trước khi agent nhìn thấy skill, nên agent nhận ngay dữ liệu mới nhất thay vì phải tự chạy lệnh. Hãy dùng khi cần cho các skill làm việc với trạng thái hiện tại của dự án.

Giải phẫu SKILL.md: khối đầu và phần thân

Tệp có hai phần. Khối YAML nằm giữa hai dòng --- ở đầu tệp, và phần thân là Markdown thường. Hướng dẫn của Anthropic nêu hai trường bắt buộc và giới hạn của chúng:

Một lưu ý nhỏ: trong Claude Code, tài liệu cho biết mọi trường đều không bắt buộc và name lấy theo tên thư mục nếu bỏ. Tuy vậy, nếu muốn skill dùng được ở nhiều công cụ và nền tảng, hãy ghi đủ hai trường theo giới hạn trên.

Đặt tên

Hướng dẫn gợi ý đặt tên theo dạng động từ đuôi "-ing" trong tiếng Anh (như processing-pdfs, writing-documentation) vì nó mô tả hoạt động, và chấp nhận dạng danh từ (pdf-processing) hay dạng mệnh lệnh (process-pdfs). Điều quan trọng hơn là nhất quán trong cả bộ skill của bạn. Tránh các tên mơ hồ như helper, utils, tools hoặc quá chung như documents, data, files. Với skill tiếng Việt, tên không dấu nối bằng gạch ngang như viet-commit hay soan-bao-cao-tuan vừa hợp lệ vừa dễ gõ.

Viết mô tả: phần quan trọng nhất

Lúc khởi động agent chỉ đọc phần khai báo (tên và mô tả) của mọi skill rồi chọn, nên mô tả là chỗ quyết định, và theo hướng dẫn nó có thể phải chọn trong hơn một trăm skill. Ba nguyên tắc:

1. Viết ở ngôi thứ ba. Mô tả được đưa vào chỉ dẫn hệ thống, nên đổi ngôi kể có thể làm việc chọn skill kém đi. Viết "Soạn thông điệp commit..." thay vì "Tôi giúp bạn viết commit...".
2. Nói cả skill làm gì lẫn khi nào dùng, kèm các từ khóa hay xuất hiện trong yêu cầu thật ("commit message", "đã stage").
3. Cụ thể. Mô tả như "Giúp làm việc với tài liệu" hay "Xử lý dữ liệu" không cho agent đủ thông tin để chọn.

Tài liệu Claude Code còn một chi tiết thực tế: phần mô tả (cộng thêm trường when_to_use nếu có) bị cắt ở 1.536 ký tự khi agent liệt kê skill, nên hãy đặt trường hợp dùng quan trọng nhất ngay đầu mô tả.

Viết phần thân: gọn, có ví dụ, đủ tự do

Hướng dẫn mở đầu bằng một nguyên tắc: cửa sổ ngữ cảnh là tài nguyên chung. Phần thân của skill, khi được nạp, cạnh tranh chỗ với lịch sử trò chuyện và các skill khác. Vì vậy hãy mặc định rằng mô hình đã rất thông minh, và chỉ thêm thứ nó chưa biết. Với mỗi đoạn, tự hỏi: AI có thật sự cần lời giải thích này không, và đoạn này có xứng với chi phí ngữ cảnh của nó không. Ví dụ, đừng giải thích PDF là gì; chỉ cần nói dùng thư viện nào và viết lệnh mẫu.

Chọn mức tự do phù hợp

Hướng dẫn chia thành ba mức, theo độ mong manh của việc cần làm:

Hình ảnh ví von của hướng dẫn: con đường hẹp bên vực thì cần lan can và chỉ dẫn từng bước (di chuyển cơ sở dữ liệu); cánh đồng thoáng thì chỉ cần chỉ hướng (duyệt code). Skill viet-commit ở trên thuộc mức tự do cao đến vừa: có mẫu type(scope): mô tả nhưng để agent tự chọn type và scope.

Dùng ví dụ, quy trình và vòng kiểm tra

• Ví dụ vào-ra truyền đạt phong cách và độ chi tiết rõ hơn mô tả bằng lời. Hãy đưa hai hoặc ba cặp ví dụ cho việc mà chất lượng đầu ra phụ thuộc vào cách viết.
• Quy trình có bước: với việc nhiều bước, viết thành danh sách bước đánh số, có thể kèm danh sách kiểm (checklist) để agent chép ra và đánh dấu dần.
• Vòng phản hồi: "kiểm tra, sửa lỗi, kiểm tra lại" nâng chất lượng rõ rệt. Ví dụ: soạn nội dung, rà theo danh sách tiêu chí, nếu còn sai thì sửa và rà lại, chỉ qua bước tiếp khi đạt hết.
• Dùng một thuật ngữ nhất quán và tránh thông tin sẽ lỗi thời (như "trước tháng 8 dùng cách cũ"). Nếu cần giữ cách cũ, để ở một mục riêng.
• Đừng đưa quá nhiều lựa chọn. Thay vì "dùng thư viện A hoặc B hoặc C", hãy đặt một mặc định và nêu một ngoại lệ.

Tách tệp kèm theo cho skill lớn dần

Hướng dẫn khuyên giữ thân SKILL.md dưới 500 dòng; gần ngưỡng đó thì tách ra tệp riêng. Cấu trúc thường gặp:

viet-commit/
├── SKILL.md           # tổng quan và chỉ đường
├── references/
│   └── quy-uoc.md     # quy ước chi tiết, chỉ đọc khi cần
└── scripts/
    └── kiem_dong_dau.py   # chạy, không đọc vào ngữ cảnh

Trong SKILL.md, nêu rõ khi nào cần đọc tệp nào, ví dụ "Chọn type và scope theo quy ước". Có bốn điều cần nhớ:

1. Giữ tham chiếu cách SKILL.md đúng một cấp. Nếu SKILL.md trỏ tới a.md và a.md lại trỏ tới b.md, agent có thể chỉ xem trước một phần tệp lồng sâu và bỏ sót thông tin.
2. Tệp tham khảo dài hơn 100 dòng nên có mục lục ở đầu, để agent thấy toàn bộ phạm vi dù chỉ đọc một phần.
3. Đặt tên tệp theo nội dung (quy-uoc-commit.md chứ không phải doc2.md) và dùng dấu gạch chéo / trong đường dẫn, kể cả trên Windows.
4. Nói rõ script để chạy hay để đọc. "Chạy kiem_dong_dau.py để kiểm độ dài" khác với "xem kiem_dong_dau.py để hiểu thuật toán". Chạy script thường hiệu quả hơn: chỉ kết quả in ra tốn ngữ cảnh, và hướng dẫn cho biết script có sẵn đáng tin hơn mã agent tự sinh mỗi lần.

Muốn truyền tham số khi gọi, Claude Code cho phép dùng $ARGUMENTS trong thân skill: nó được thay bằng mọi thứ gõ sau tên skill. Chẳng hạn thân skill có dòng "Sửa lỗi theo issue $ARGUMENTS" thì /sua-issue 123 cho agent câu "Sửa lỗi theo issue 123".

Kiểm cấu trúc skill bằng code

Các giới hạn trên đều kiểm được bằng máy. Đoạn Python dưới đây đọc một thư mục skill và báo những lỗi hình thức: tên sai định dạng hoặc chứa từ dành riêng, mô tả rỗng hay quá dài, mô tả không nêu khi nào dùng, thân quá dài, tệp tham chiếu không có hoặc lồng nhau. Ví dụ tạo hai skill: viet-commit viết đúng, và một skill mẫu mắc nhiều lỗi.

"""Kiểm cấu trúc một skill theo các giới hạn trong tài liệu Agent Skills của Anthropic (đọc ngày 11/11/2026).

Những điều kiểm: name tối đa 64 ký tự, chỉ chữ thường, số, gạch ngang, không chứa từ dành riêng (anthropic, claude);
description không rỗng, tối đa 1.024 ký tự, không có thẻ XML, viết ở ngôi thứ ba và nêu khi nào dùng; thân SKILL.md
dưới 500 dòng; tệp tham chiếu có thật, nằm cách SKILL.md một cấp, tệp dài trên 100 dòng có mục lục.
Công cụ chỉ bắt lỗi hình thức. Skill có chạy tốt hay không phải thử với việc thật.
"""
import os
import re
import tempfile
import unicodedata

TU_DANH_RIENG = ("anthropic", "claude")
TEN_MO_HO = {"helper", "utils", "tools", "documents", "data", "files"}
NGOI_THU_NHAT_HAI = {"tôi", "mình", "bạn", "i", "you", "we"}
LINK_NOI_BO = re.compile(r"\]\((?!https?://|#)([^)\s]+)\)")


def bo_dau(s):
    s = unicodedata.normalize("NFD", s.lower())
    return "".join(c for c in s if unicodedata.category(c) != "Mn").replace("đ", "d")


def tach(noi_dung):
    if not noi_dung.startswith("---\n"):
        return None, noi_dung
    dau, _, than = noi_dung[4:].partition("\n---\n")
    meta = {}
    for dong in dau.splitlines():
        khoa, sep, gia_tri = dong.partition(":")
        if sep:
            meta[khoa.strip()] = gia_tri.strip()
    return meta, than


def kiem(thu_muc):
    """Trả về danh sách (muc, noi_dung), muc là 'LỖI' hoặc 'CẢNH BÁO'."""
    kq = []
    duong_dan = os.path.join(thu_muc, "SKILL.md")
    if not os.path.isfile(duong_dan):
        return [("LỖI", "thiếu SKILL.md")]
    with open(duong_dan, encoding="utf-8") as f:
        meta, than = tach(f.read())
    if meta is None:
        return [("LỖI", "SKILL.md không có khối --- ở đầu tệp")]

    ten, mo_ta = meta.get("name", ""), meta.get("description", "")
    if not ten:
        kq.append(("LỖI", "thiếu name"))
    else:
        if len(ten) > 64:
            kq.append(("LỖI", f"name dài {len(ten)} ký tự, tối đa 64"))
        if not re.fullmatch(r"[a-z0-9-]+", ten):
            kq.append(("LỖI", "name chỉ gồm chữ thường, số và gạch ngang"))
        if any(t in ten.lower() for t in TU_DANH_RIENG):
            kq.append(("LỖI", "name chứa từ dành riêng (anthropic, claude)"))
        if ten in TEN_MO_HO:
            kq.append(("CẢNH BÁO", f"name '{ten}' quá chung, khó đoán skill làm gì"))
    if not mo_ta:
        kq.append(("LỖI", "description rỗng: agent không biết khi nào dùng skill"))
    else:
        if len(mo_ta) > 1024:
            kq.append(("LỖI", f"description dài {len(mo_ta)} ký tự, tối đa 1.024"))
        if re.search(r"<[^>]+>", mo_ta):
            kq.append(("LỖI", "description có thẻ XML"))
        tu_dau = bo_dau(mo_ta.split()[0]) if mo_ta.split() else ""
        if tu_dau in {bo_dau(t) for t in NGOI_THU_NHAT_HAI}:
            kq.append(("CẢNH BÁO", "description nên viết ở ngôi thứ ba, không bắt đầu bằng tôi/bạn"))
        if not re.search(r"dung khi|use when|khi nguoi dung", bo_dau(mo_ta)):
            kq.append(("CẢNH BÁO", "description nên nêu khi nào dùng skill (vd. 'Dùng khi ...')"))

    so_dong = len(than.strip().splitlines())
    if so_dong >= 500:
        kq.append(("CẢNH BÁO", f"thân SKILL.md dài {so_dong} dòng, nên dưới 500: tách sang tệp tham khảo"))

    for dich in LINK_NOI_BO.findall(than):
        if "\\" in dich:
            kq.append(("CẢNH BÁO", f"đường dẫn '{dich}' dùng dấu \\, nên dùng /"))
        p = os.path.join(thu_muc, dich.replace("\\", "/"))
        if not os.path.isfile(p):
            kq.append(("LỖI", f"tham chiếu tới tệp không có: {dich}"))
            continue
        with open(p, encoding="utf-8") as f:
            ref = f.read()
        if LINK_NOI_BO.search(ref):
            kq.append(("CẢNH BÁO", f"{dich} lại tham chiếu tệp khác: nên để mọi tệp cách SKILL.md một cấp"))
        if len(ref.splitlines()) > 100 and not re.search(r"^#+\s*(Contents|Mục lục)", ref, re.M | re.I):
            kq.append(("CẢNH BÁO", f"{dich} dài hơn 100 dòng nhưng chưa có mục lục"))
    return kq


def tao_mau(goc):
    tot = os.path.join(goc, "viet-commit")
    os.makedirs(os.path.join(tot, "references"))
    with open(os.path.join(tot, "SKILL.md"), "w", encoding="utf-8") as f:
        f.write(
            "---\nname: viet-commit\n"
            "description: Soạn thông điệp commit theo mẫu type(scope) rồi mô tả ngắn, dựa trên git diff. "
            "Dùng khi người dùng nhờ viết commit message hoặc xem lại thay đổi đã stage.\n---\n\n"
            "## Cách làm\n\n1. Đọc git diff --staged.\n2. Chọn type và scope theo [quy ước](references/quy-uoc.md).\n"
            "3. Viết dòng đầu dưới 72 ký tự.\n"
        )
    with open(os.path.join(tot, "references", "quy-uoc.md"), "w", encoding="utf-8") as f:
        f.write("type: feat, fix, docs, refactor, test, chore\n")
    xau = os.path.join(goc, "Claude-Helper")
    os.makedirs(xau)
    with open(os.path.join(xau, "SKILL.md"), "w", encoding="utf-8") as f:
        f.write(
            "---\nname: Claude-Helper\ndescription: Tôi giúp bạn làm việc với tệp.\n---\n\n"
            "Xem [hướng dẫn](ref\\huong-dan.md) để biết thêm.\n"
        )
    return tot, xau


def chay_thu():
    with tempfile.TemporaryDirectory() as goc:
        ket_qua = {}
        for thu_muc in tao_mau(goc):
            ten = os.path.basename(thu_muc)
            kq = kiem(thu_muc)
            ket_qua[ten] = kq
            if not kq:
                print(f"== {ten}: đạt")
            else:
                n_loi = sum(1 for m, _ in kq if m == "LỖI")
                print(f"== {ten}: {n_loi} lỗi, {len(kq) - n_loi} cảnh báo")
                for muc, nd in kq:
                    print(f"  {muc}: {nd}")
        return ket_qua


if __name__ == "__main__":
    chay_thu()

Chạy đoạn code sẽ in ra:

== viet-commit: đạt
== Claude-Helper: 3 lỗi, 3 cảnh báo
  LỖI: name chỉ gồm chữ thường, số và gạch ngang
  LỖI: name chứa từ dành riêng (anthropic, claude)
  CẢNH BÁO: description nên viết ở ngôi thứ ba, không bắt đầu bằng tôi/bạn
  CẢNH BÁO: description nên nêu khi nào dùng skill (vd. 'Dùng khi ...')
  CẢNH BÁO: đường dẫn 'ref\huong-dan.md' dùng dấu \, nên dùng /
  LỖI: tham chiếu tới tệp không có: ref\huong-dan.md

Công cụ chỉ bắt lỗi hình thức. Một skill qua được mọi kiểm tra vẫn có thể viết dở, và mới là bước thử với việc thật.

Thử và sửa: cách biết skill tốt hay chưa

Skill chỉ tốt khi AI dùng nó đúng lúc và làm đúng. Hướng dẫn của Anthropic đề nghị vòng lặp sau:

1. Thử với việc thật, không phải ca mẫu bạn tự bịa. Ghi lại chỗ AI lúng túng, thành công hay chọn khác dự kiến.
2. Xem AI đọc skill ra sao. Nó có đọc tệp tham khảo theo thứ tự bạn nghĩ không, có bỏ qua đường dẫn quan trọng không, có đọc đi đọc lại cùng một tệp không (khi đó nội dung đó nên nằm ngay trong SKILL.md), hay có tệp nào không bao giờ được mở không (có thể không cần).
3. Sửa theo quan sát, không theo phỏng đoán. Nếu skill không tự được dùng, thường mô tả cần cụ thể hơn. Nếu skill được dùng nhưng bỏ sót một quy tắc, hãy làm quy tắc đó nổi bật hơn.
4. Thử với nhiều mô hình nếu bạn định dùng nhiều mô hình. Cái đủ rõ với mô hình mạnh có thể thiếu chi tiết với mô hình nhỏ hơn.
5. Nhờ đồng nghiệp thử và hỏi: skill có tự được dùng khi cần không, chỉ dẫn có rõ không, còn thiếu gì.

Hướng dẫn cũng gợi ý một mẹo: có thể nhờ chính AI viết bản nháp skill sau khi bạn hoàn thành một việc cùng nó, rồi bạn rà soát để bỏ phần giải thích thừa và sắp lại tệp. AI hiểu định dạng skill khá tốt, nhưng người quyết định cái gì đáng giữ vẫn là bạn.

Điều khiển ai được gọi skill: các trường riêng của Claude Code

Ngoài hai trường chuẩn, Claude Code có vài trường để điều khiển cách skill được gọi. Chúng chỉ có hiệu lực trong Claude Code, nên đừng dựa vào chúng nếu skill cần chạy ở công cụ khác.

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

Học tiếp

• Muốn xem các skill người khác đã viết và cách cài chúng, đọc cài skill cho Claude Code từ GitHub.
• Muốn tìm ý tưởng skill đáng viết, đọc 10 skill hữu ích.
• Muốn phân biệt skill với tệp hướng dẫn dự án, đọc viết hướng dẫn dự án cho AI.

Nếu bạn muốn học cách làm việc với AI một cách có hệ thống, tham khảo khóa học AI của Big-O Coding.

Nguồn tham khảo

• Tài liệu Claude Code: Skills
• Tài liệu Claude: Skill authoring best practices
• Agent Skills: trang tổng quan của định dạng mở
• Anthropic Engineering: Equipping agents for the real world with Agent Skills (16/10/2025)