Mục tiêu học tập

Sau bài này, bạn sẽ có thể:
  • ✅ Tạo một personal skill từ scratch với cấu trúc frontmatter đúng chuẩn
  • ✅ Test và verify skill đã load thành công trong Claude Code
  • ✅ Giải thích cơ chế 4 bước Claude dùng để match request với skill
  • ✅ Hiểu priority hierarchy (Enterprise → Personal → Project → Plugins) và cách tránh conflict
  • ✅ Update / remove skill khi thay đổi

Mở đầu: Từ “lý thuyết” tới “hành”

Skill là folder, có SKILL.md, có frontmatter — OK. Nhưng lý thuyết không đọng lại cho đến khi bạn tự tay tạo một cái và thấy nó hoạt động. Trong bài này, chúng ta build skill simple-page-builder — một skill giúp Claude tạo landing page, login page, hoặc register page theo format dễ hiểu cho người non-code. Đây là case phù hợp để bắt đầu vì:
  • Chỉ cần 1 file SKILL.md
  • Không cần script
  • Không cần tool restriction
  • Không cần hiểu sâu về Git hoặc quy trình kỹ thuật của developer
  • Vẫn đủ để bạn thấy full flow: tạo → test → match → execute
Sau bài này, bạn sẽ có:
  • Skill đầu tiên thật sự chạy được trên máy bạn
  • Mental model về priority hierarchy — tránh conflict sau này
  • Sự tự tin để viết skill thứ 2, thứ 3 nhanh hơn
Lưu ý: Mở terminal lên trước khi đọc tiếp. Bài này expect bạn gõ theo.

Chuẩn bị: Kiểm tra môi trường

Windows vs macOS/Linux

Path của personal skill khác nhau giữa OS:

Xác minh Claude Code đã cài

Kết quả mong đợi: in ra version number. Nếu không có, cài Claude Code trước khi tiếp tục.

Cấu trúc chúng ta sẽ build

Đơn giản nhất có thể. Chúng ta chưa dùng references/, scripts/, hay assets/ — những thứ đó để Bài 15.3.

Bước 1: Tạo folder skill

Mở terminal, chạy:
Giải thích:
  • mkdir -p tạo folder và folder cha nếu chưa có, không báo lỗi nếu đã tồn tại
  • ~/.claude/skills/simple-page-builder là path đầy đủ tới folder skill
  • Tên folder = tên skill
  • Quy tắc tên: lowercase, dấu gạch ngang, không gạch dưới _, không space
⚠️ Cảnh báo: Tên simple_page_builder (underscore) hoặc Simple-Page-Builder (uppercase) là sai chuẩn. Claude có thể không nhận. Luôn luôn dùng lowercase + dash. Kiểm tra folder đã tạo:
Bạn sẽ thấy simple-page-builder/ trong danh sách.

Bước 2: Viết file SKILL.md

Tạo file SKILL.md (chú ý: cap chữ SKILL, .md lowercase — sai là skill không load):

Giải thích cấu trúc

Frontmatter (giữa hai dấu ---)

  • name: simple-page-builder phải khớp tên folder
  • description là thứ Claude dùng để quyết định khi nào nên load skill
  • Description nên có nhiều trigger phrase mà người dùng thật có thể nói
Trong ví dụ này, description cover nhiều cách nói:
  • “building a landing page”
  • “login page”
  • “register page”
  • “signup page”
  • “auth screen”
Tại sao liệt kê nhiều cách nói? Vì semantic matching hoạt động tốt hơn khi bạn cover nhiều cách diễn đạt user có thể dùng.

Instructions (dưới frontmatter)

Phần body của skill là phần Claude đọc khi skill được kích hoạt. Bài này dùng cấu trúc thực tế, dễ maintain:
  • Khi thực hiện
  • Input cần có
  • Quy tắc / conventions
  • Quy trình thực hiện
  • Output format
  • Lưu ý / tránh làm
Cấu trúc này tốt hơn kiểu viết mơ hồ như “hãy tạo trang đẹp”. Nó cho Claude biết phải hỏi gì, làm theo thứ tự nào, và trả kết quả ra sao.

Bước 3: Restart Claude Code

Đây là bước hay quên nhất. Claude Code scan skill ở startup. Skill vừa tạo không tự động được nhận nếu phiên hiện tại đang chạy. Phải restart:
Trong VS Code/JetBrains extension: đóng panel Claude, mở lại.

Bước 4: Verify skill đã load

Trong Claude Code session mới, gõ:
Bạn sẽ thấy danh sách các skill Claude biết. simple-page-builder phải nằm trong đó. Nếu không thấy:
  • Check lại tên file: SKILL.md — không phải skill.md, Skill.md, SKILL.MD
  • Check lại path: ~/.claude/skills/simple-page-builder/SKILL.md
  • Check lại frontmatter: name: simple-page-builder
  • Chạy claude --debug để xem loading error
  • Chi tiết debug ở Bài 15.6

Bước 5: Test skill

Trong Claude Code, gõ một prompt non-code:
Bạn sẽ thấy Claude nhận ra skill:
Kết quả mong đợi sẽ có format gần như sau:
Test tiếp với login page:
Test tiếp với register page:
Đã xong. Skill đầu tiên của bạn đã hoạt động. Quan trọng là:
  • Claude tự biết dùng skill simple-page-builder (bạn không gõ /simple-page-builder)
  • Claude hỏi thông tin thiếu nếu prompt chưa đủ rõ
  • Output bám đúng format bạn định nghĩa
  • Lần tới gõ “làm trang signup”, “tạo màn hình đăng nhập”, “viết landing page”, Claude vẫn có thể trigger đúng skill này

Cơ chế Claude match skill — deep dive

Bây giờ skill đã chạy, hãy hiểu what happens under the hood. Đây là phần nhiều người bỏ qua, nhưng hiểu nó sẽ giúp bạn debug (Bài 15.6) và viết skill tốt hơn.

4 locations Claude scan ở startup

Khi bạn chạy claude, nó quét 4 nguồn theo thứ tự: Claude chỉ load name + description của mỗi skill ở startup, không load full content.

Chi phí token của metadata

Otto (Anthropic engineer) cho con số cụ thể: 30-50 token mỗi skill ở startup. Nghĩa là:
  • 10 skill personal → 300-500 token overhead startup
  • 50 skill + 20 project skill → ~2100-3500 token overhead
Đây là lý do có giới hạn 1024 chars cho description. Nếu description dài thêm, multiply số skill → overhead phình to, ăn vào context window của bạn. Rule of thumb: giữ description 150-300 chars, chỉ liệt kê trigger phrase cốt lõi. Đừng viết description như documentation.

Semantic matching workflow

Khi bạn gõ request: “Semantic” nghĩa là Claude không cần exact keyword. Những câu như sau vẫn có thể trigger:
  • “Làm landing page cho khóa học của tôi”
  • “Thiết kế trang đăng nhập dễ hiểu”
  • “Tạo màn hình signup cho khách đặt lịch”
  • “Viết nội dung register page”
Miễn là description của bạn cover đủ variation, Claude có cơ sở để chọn đúng skill.

Confirmation prompt — tại sao có?

Một số user hỏi: “Sao không tự chạy luôn, phải hỏi làm gì?” Lý do:
  • Transparency: Bạn biết chính xác Claude đưa cái gì vào context
  • Security: Skill có thể có tool access đặc biệt (Bài 15.3 allowed-tools) — bạn phải xác nhận
  • Accuracy: Match có thể sai nếu description mơ hồ — bạn có cơ hội deny
Bạn có thể config để auto-accept skill confirmation nếu muốn. Nhưng mặc định là luôn hỏi.

Priority hierarchy — Khi có skill trùng tên

Đây là tình huống sớm muộn sẽ gặp: bạn có personal skill simple-page-builder, clone repo về thấy project cũng có skill simple-page-builder, hoặc công ty deploy enterprise skill cùng tên. Cái nào thắng?

Thứ tự ưu tiên (từ cao xuống thấp)

Case study: Lan marketing lead

Lan có personal skill simple-page-builder để viết landing page theo style cá nhân: tone thân thiện, headline ngắn, CTA rõ. Sau đó Lan clone repo của công ty và thấy project cũng có skill simple-page-builder. Skill của project dùng brand voice formal hơn và có checklist pháp lý. Personal thắng project. Claude dùng skill cá nhân của Lan. Tuần sau, công ty deploy enterprise skill simple-page-builder vì mọi landing page phải theo brand guideline mới. Enterprise thắng personal. Dù Lan có skill cá nhân, enterprise version override hoàn toàn.

Khi nào hierarchy này có lý?

Otto giải thích:
“This lets organizations enforce standards through enterprise skills while still allowing individual customization.”
Công ty có thể enforce “mọi landing page phải có legal disclaimer” ở tầng enterprise. Mỗi người vẫn có thể tạo skill riêng với tên khác, ví dụ lan-landing-page-draft, để thêm style cá nhân.

Cách tránh conflict

Quy tắc đặt tên: Tên càng specific, càng ít khả năng collision.

Update và remove skill

Update

Mở ~/.claude/skills/simple-page-builder/SKILL.md bằng editor nào cũng được, sửa, save. Quan trọng: restart Claude Code để thay đổi có hiệu lực. Claude Code không hot-reload skill.

Remove

Xóa nguyên folder:
Restart Claude. Skill biến mất khỏi danh sách. 💡 Mẹo: Thay vì xóa, có thể rename folder để tạm disable:
Tên bắt đầu bằng _ thường không match naming convention Claude dùng — skill sẽ không load, nhưng bạn vẫn giữ content.

Ví dụ theo ngành — Skill đầu tiên của các role khác nhau

Chủ shop online — landing-page-brief

Kết quả: Người không biết viết landing page vẫn có một brief rõ ràng để đưa cho Claude, designer, hoặc freelancer triển khai.

Product manager — login-page-checklist

Course creator — register-page-builder

Designer — design-polish-checklist

Anti-patterns — Sai lầm hay gặp ở bài đầu

❌ Tên file skill.md (lowercase)

Claude nhận diện đúng SKILL.md (cap). skill.md, Skill.md, SKILL.MD sẽ không được load. Cách đúng: SKILL.md — cap SKILL, lowercase md.

❌ Folder không khớp name trong frontmatter

Không match. Claude bối rối. Cách đúng: Folder name = name frontmatter = chính xác.

❌ Description như documentation

Tại sao sai: Semantic matching không cần lý lẽ. Càng dài, overhead token startup càng cao. Cách đúng: Ngắn, chỉ action + trigger phrases:

❌ Quên restart Claude Code sau khi tạo/sửa

“Tôi tạo skill rồi, test không thấy trigger!” — 80% trường hợp là quên restart. Cách đúng: Mọi thay đổi SKILL.md/quit + claude lại. Nhớ thành reflex.

❌ Viết instructions quá mơ hồ

Tại sao sai: Claude không biết “beautiful” nghĩa gì → output mỗi lần khác. Cách đúng: Format template cụ thể, rõ từng bullet:

❌ Tạo form register quá dài

Triệu chứng: Skill yêu cầu họ tên, email, số điện thoại, địa chỉ, ngày sinh, nghề nghiệp, công ty, chức vụ, mã giới thiệu… ngay ở bước đầu. Tại sao sai: Người dùng non-code thường cần flow đơn giản. Form càng dài, khả năng bỏ cuộc càng cao. Cách đúng: Chỉ hỏi field bắt buộc. Những thông tin chưa cần thì để sau khi đăng ký thành công.

Áp dụng ngay

Bài tập 1: Tạo skill simple-page-builder theo bài (~5 phút)

Làm chính xác Bước 1 → 5 ở trên. Đừng skip. Mục tiêu: chạm tay vào flow một lần. Checklist:
  • ☐ Folder ~/.claude/skills/simple-page-builder/ đã tạo
  • ☐ File SKILL.md có frontmatter + instructions
  • ☐ Restart Claude Code
  • ☐ Hỏi “What skills are available?” → thấy simple-page-builder
  • ☐ Test bằng prompt landing page, login page, hoặc register page

Bài tập 2: Tạo skill thứ 2 — skill của riêng bạn (~10 phút)

Pick 1 skill đơn giản, dễ dùng ngay. Nếu bạn non-code, chọn một trong các gợi ý:
  • landing-page-brief
  • login-page-checklist
  • register-page-builder
  • design-polish-checklist
  • customer-reply-drafter
Bước 1: Đặt tên theo quy tắc lowercase-dash. Ví dụ:
Bước 2: Tạo folder:
Bước 3: Viết SKILL.md:
  • Frontmatter với name + description (150-300 chars, có trigger phrase cụ thể)
  • Body gồm 6 phần: Khi thực hiện, Input cần có, Quy tắc / conventions, Quy trình thực hiện, Output format, Lưu ý / tránh làm
Bước 4: Restart + test. Bước 5: Ghi lại:
  • Tên skill: __________
  • Trigger phrase test: __________
  • Lần đầu có trigger không? __________
  • Nếu không, description thiếu keyword gì? __________

Tóm tắt bài học

🎯 Skill = folder <name>/SKILL.md trong ~/.claude/skills/ (personal) hoặc .claude/skills/ (project). Cap SKILL, lowercase md — sai là không load. 🎯 4 bước tạo: mkdir folder → viết SKILL.md với frontmatter → restart Claude Code → verify qua “what skills are available”. 🎯 Claude match qua semantic matching description — startup chỉ load name + description (30-50 token/skill), full content load khi match + confirm. 🎯 Priority 4 tầng: Enterprise > Personal > Project > Plugins. Tên trùng → tầng cao thắng. Đặt tên cụ thể để tránh collision. 🎯 Update = edit SKILL.md + restart. Remove = delete folder + restart. Claude Code không hot-reload skill. 🎯 Với người non-code, skill nên bắt đầu từ workflow cụ thể: landing page, login page, register page, customer reply, content outline. Đừng bắt đầu bằng skill quá rộng kiểu “make website”.

Bài tiếp theo

Skill đầu tiên của bạn hiện là 1 file duy nhất. Đủ cho case đơn giản. Nhưng khi skill lớn hơn (cần template dài, script tự động, tool restriction cho security), bạn sẽ đụng tường: file phình to, context bloated, maintain cực. Bài 15.3 dạy bạn progressive disclosure + multi-file skill + 2 field nâng cao allowed-toolsmodel — cách build skill đủ lớn để mạnh, đủ gọn để nhanh. ➡️ Bài tiếp theo: Bài 15.3: Cấu hình & skill nhiều file

Tài liệu tham khảo

  • Anthropic Academy — “Creating your first skill”
  • Official video — “Creating your first skill”
  • agentskills.io — open standard fields
Bản quyền 2026 Anthropic. Phiên bản tiếng Việt tinh chế. Mọi quyền được bảo lưu.