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
- 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
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:| OS | Path |
|---|---|
| macOS | ~/.claude/skills/ |
| Linux | ~/.claude/skills/ |
| Windows | C:\Users\<username>\.claude\skills\ hoặc ~/.claude/skills/ trong Git Bash |
Xác minh Claude Code đã cài
Cấu trúc chúng ta sẽ build
references/, scripts/, hay assets/ — những thứ đó để Bài 15.3.
Bước 1: Tạo folder skill
Mở terminal, chạy:mkdir -ptạ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-builderlà 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
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:
simple-page-builder/ trong danh sách.
Bước 2: Viết file SKILL.md
Tạo fileSKILL.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-builderphải khớp tên folderdescriptionlà 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
- “building a landing page”
- “login page”
- “register page”
- “signup page”
- “auth screen”
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
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:Bước 4: Verify skill đã load
Trong Claude Code session mới, gõ: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ảiskill.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:- 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ạyclaude, 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
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”
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
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 skillsimple-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 skillsimple-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:| ❌ Chung chung | ✅ Cụ thể |
|---|---|
page | simple-page-builder |
landing | course-landing-page-builder |
login | friendly-login-page-checklist |
register | spa-register-page-builder |
design | mobile-form-copy-review |
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:_ 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
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 đúngSKILL.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
❌ Description như documentation
❌ 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 đổiSKILL.md → /quit + claude lại. Nhớ thành reflex.
❌ Viết instructions quá mơ hồ
❌ 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.mdcó 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-brieflogin-page-checklistregister-page-builderdesign-polish-checklistcustomer-reply-drafter
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
- 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 caoallowed-tools và model — 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