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:
OSPath
macOS~/.claude/skills/
Linux~/.claude/skills/
WindowsC:\Users\<username>\.claude\skills\ hoặc ~/.claude/skills/ trong Git Bash

Xác minh Claude Code đã cài

claude --version
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

~/.claude/skills/
└── simple-page-builder/
    └── SKILL.md
Đơ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:
mkdir -p ~/.claude/skills/simple-page-builder
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:
ls -la ~/.claude/skills/
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):
cat > ~/.claude/skills/simple-page-builder/SKILL.md << 'EOF'
---
name: simple-page-builder
description: Creates landing pages, login screens, and register screens from simple business goals. Use when building a landing page, login page, register page, signup page, or auth screen.
---

## Khi thực hiện

Giúp người dùng tạo hoặc chỉnh một trang web đơn giản theo mục tiêu kinh doanh rõ ràng.

Ưu tiên 3 loại trang:

- Landing page
- Login page
- Register / signup page

## Input cần có

Nếu người dùng chưa nói rõ, hãy hỏi ngắn gọn:

- Loại trang cần làm: landing, login, hay register
- Sản phẩm / dịch vụ là gì
- Khách hàng mục tiêu là ai
- Tone mong muốn: chuyên nghiệp, thân thiện, cao cấp, trẻ trung
- Màu chủ đạo hoặc brand style nếu có

Nếu người dùng không biết, dùng mặc định:

- Tone: rõ ràng, đáng tin, dễ đọc
- Layout: mobile-first
- CTA: một hành động chính trên mỗi màn hình

## Quy tắc / conventions

- Viết cho người dùng cuối, không viết như tài liệu kỹ thuật
- Ưu tiên nội dung dễ hiểu hơn thuật ngữ chuyên môn
- Không tạo quá nhiều lựa chọn trên một màn hình
- Landing page phải có CTA rõ ràng
- Login page phải có trạng thái lỗi, forgot password và loading state
- Register page phải có validation cơ bản, consent nếu cần và success state

## Quy trình thực hiện

1. Xác định loại trang và mục tiêu chính.
2. Nếu thiếu thông tin quan trọng, hỏi tối đa 3 câu.
3. Đề xuất cấu trúc trang trước khi viết chi tiết.
4. Viết nội dung mẫu cho từng section hoặc từng trạng thái.
5. Nếu đang ở trong codebase, đọc style hiện có trước khi đề xuất file cần sửa.
6. Trả kết quả theo format bên dưới.

## Output format

Trả lời theo format:

### Tóm tắt
Một đoạn ngắn nói trang này phục vụ mục tiêu gì.

### Cấu trúc đề xuất
- Section / màn hình 1
- Section / màn hình 2
- Section / màn hình 3

### Nội dung mẫu
Copywriting hoặc microcopy có thể dùng ngay.

### Trạng thái cần có
Loading, error, success, empty state nếu phù hợp.

### Việc cần làm tiếp theo
Danh sách 3-5 bước rõ ràng để triển khai.

## Lưu ý / tránh làm

- Không dùng jargon kỹ thuật nếu người dùng không yêu cầu.
- Không tự thêm field nhạy cảm vào form register nếu không có lý do.
- Không đề xuất flow đăng ký quá dài.
- Không tạo landing page chỉ có text; phải có cấu trúc section rõ ràng.
EOF

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

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

---
name: simple-page-builder
description: Creates landing pages, login screens, and register screens from simple business goals. Use when building a landing page, login page, register page, signup page, or auth screen.
---
  • 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:
# Nếu đang trong Claude Code session:
/quit

# Mở lại:
claude
Trong VS Code/JetBrains extension: đóng panel Claude, mở lại.

Bước 4: Verify skill đã load

Trong Claude Code session mới, gõ:
What skills are available?
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:
Tạo landing page cho lớp yoga online dành cho dân văn phòng bận rộn. Tone nhẹ nhàng, đáng tin, màu xanh lá.
Bạn sẽ thấy Claude nhận ra skill:
I'll use the "simple-page-builder" skill for this. [Loading skill]
Kết quả mong đợi sẽ có format gần như sau:
### Tóm tắt
Landing page giúp người bận rộn hiểu nhanh lợi ích của lớp yoga online và đăng ký học thử.

### Cấu trúc đề xuất
- Hero: lời hứa chính + nút đăng ký học thử
- Pain points: đau lưng, stress, thiếu thời gian
- Solution: lớp học 30 phút, học tại nhà, lịch linh hoạt
- Benefits: giảm căng thẳng, cải thiện tư thế, ngủ tốt hơn
- Social proof: học viên đã tham gia, review ngắn
- FAQ: cần dụng cụ gì, có phù hợp người mới không

### Nội dung mẫu
Headline: Yoga 30 phút mỗi ngày cho dân văn phòng bận rộn
CTA: Đăng ký học thử miễn phí

### Trạng thái cần có
- Form gửi thành công
- Form thiếu email
- Loading khi gửi đăng ký

### Việc cần làm tiếp theo
1. Chọn ảnh hero phù hợp
2. Chốt offer học thử
3. Viết 3 testimonial thật
4. Tạo form đăng ký
Test tiếp với login page:
Thiết kế nội dung cho màn hình login của app học tiếng Anh. Người dùng là học sinh cấp 2.
Test tiếp với register page:
Tạo register page cho app đặt lịch spa. Form cần đơn giản, không làm khách sợ.
Đã 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:
❌ Chung chung✅ Cụ thể
pagesimple-page-builder
landingcourse-landing-page-builder
loginfriendly-login-page-checklist
registerspa-register-page-builder
designmobile-form-copy-review
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.
/quit
claude

Remove

Xóa nguyên folder:
rm -rf ~/.claude/skills/simple-page-builder
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:
mv ~/.claude/skills/simple-page-builder ~/.claude/skills/_disabled-simple-page-builder
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

---
name: landing-page-brief
description: Creates a clear landing page brief for a product or service. Use when planning a landing page, sales page, offer page, or campaign page.
---

## Khi thực hiện

Tạo brief landing page dễ hiểu cho một sản phẩm, dịch vụ, khóa học hoặc chiến dịch.

## Input cần có

- Sản phẩm / dịch vụ
- Khách hàng mục tiêu
- Ưu đãi chính
- CTA mong muốn

## Quy trình thực hiện

1. Tóm tắt offer bằng 1 câu.
2. Xác định nỗi đau chính của khách hàng.
3. Đề xuất cấu trúc landing page 6-8 sections.
4. Viết headline, subheadline và CTA.
5. Liệt kê proof cần có: testimonial, hình ảnh, số liệu, cam kết.

## Output format

- Tóm tắt offer
- Cấu trúc landing page
- Copy mẫu
- Proof cần bổ sung
- Next steps
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

---
name: login-page-checklist
description: Reviews login page content and states. Use when creating a login page, improving sign-in UX, or checking auth screen copy.
---

## Khi thực hiện

Kiểm tra màn hình login từ góc nhìn người dùng cuối.

## Quy tắc / conventions

- Login phải rõ người dùng cần nhập gì.
- Error message phải giúp sửa lỗi, không đổ lỗi cho user.
- Forgot password phải dễ thấy.
- Loading state phải ngăn bấm submit nhiều lần.

## Output format

### Điểm ổn
### Vấn đề cần sửa
### Microcopy đề xuất
### Checklist trạng thái

Course creator — register-page-builder

---
name: register-page-builder
description: Creates simple registration pages for courses, events, and services. Use when building a register page, signup form, enrollment page, or booking form.
---

## Khi thực hiện

Tạo register page đơn giản, ít friction, phù hợp với người mới.

## Input cần có

- Người đăng ký là ai
- Họ đăng ký để nhận gì
- Thông tin bắt buộc cần lấy
- Có thanh toán ngay hay không

## Lưu ý / tránh làm

- Không hỏi quá nhiều field.
- Không yêu cầu thông tin nhạy cảm nếu chưa cần.
- Không dùng CTA chung chung như Submit.

## Output format

- Form fields
- Validation rules
- Error messages
- Success message
- CTA copy

Designer — design-polish-checklist

---
name: design-polish-checklist
description: Reviews simple web pages for visual polish. Use when checking spacing, visual hierarchy, button copy, empty states, or mobile layout.
---

## Khi thực hiện

Review một page từ góc nhìn designer trước khi ship.

## Quy trình thực hiện

1. Kiểm tra hierarchy: headline, subheadline, CTA.
2. Kiểm tra spacing giữa section.
3. Kiểm tra button states: default, hover, disabled, loading.
4. Kiểm tra mobile layout.
5. Đề xuất 5 chỉnh sửa có impact cao nhất.

## Output format

- Top 5 fixes
- Before / after copy nếu có
- Mobile risks
- Final 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

~/.claude/skills/simple-page-builder/SKILL.md
frontmatter: name: simple_page_builder  ← sai, underscore
Không match. Claude bối rối. Cách đúng: Folder name = name frontmatter = chính xác.

❌ Description như documentation

description: This is an excellent tool that helps you create beautiful, high converting, responsive, professional, modern, clean, advanced landing pages and authentication screens with many options...
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:
description: Creates landing pages, login screens, and register screens from simple business goals. Use when building a landing page, login page, register page, signup page, or auth screen.

❌ 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ồ

When creating a landing page, make it beautiful.
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:
1. Xác định audience và offer.
2. Tạo sections: Hero / Problem / Solution / Benefits / Proof / CTA / FAQ.
3. Mỗi section cần headline, body copy, và CTA nếu phù hợp.
4. Output gồm: structure, copy mẫu, states, next steps.

❌ 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ụ:
landing-page-brief
register-page-builder
friendly-login-page-checklist
Bước 2: Tạo folder:
mkdir -p ~/.claude/skills/<tên-của-bạn>
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.