15.1 · Skill là gì?

Mở đầu: Câu chuyện của Minh, một team lead

Tuần này, anh làm thế nào:

• Thứ Hai 9:30 — Mở PR của Hà, gõ vào Claude: "Review PR này theo format: What/Why/Changes, check typing, check test coverage, tag các security concerns theo OWASP, giữ tone feedback constructive không harsh." (110 từ)
• Thứ Ba 14:15 — Mở PR của Bảo. Gõ lại y nguyên 110 từ đó.
• Thứ Tư 10:45 — Mở PR của chính mình. Gõ lại y nguyên 110 từ đó.
• Thứ Năm 16:30 — Mở PR của Hà lần 2. Đã quên chính xác wording lần đầu, gõ lại gần giống nhưng không hoàn toàn giống. Review output hơi khác style lần trước.
• Thứ Sáu 11:00 — Bảo onboard, hỏi: "Anh review code kiểu gì? Chia sẻ prompt cho em." Minh... phải moi lại history tin nhắn Claude Code, copy-paste 110 từ, gửi Bảo qua Slack.

Tổng thời gian tuần

~25 phút gõ-lại + inconsistency giữa các review + Bảo phải học lại từ Slack message thay vì "học qua làm".

Giải pháp 2 phút

Minh tạo 1 file ~/.claude/skills/pr-review/SKILL.md với 110 từ đó + 1 dòng description. Từ giờ, mỗi khi anh gõ "review this PR", Claude tự load skill đó, review đúng format, đúng tone, mỗi lần đều như nhau. Bảo clone repo về, .claude/skills/pr-review/ đã ở đó, Claude của Bảo cũng review đúng y style của Minh.

Đây chính là bản chất skill: viết một lần, áp dụng mãi mãi, đồng nhất, portable qua người khác.

Skill là gì — Định nghĩa kỹ thuật

Skill = một folder chứa file SKILL.md + (optional) các file/script phụ, với frontmatter name và description mà Claude dùng để tự động kích hoạt khi request của bạn match.

Có 3 từ khóa quan trọng trong định nghĩa trên:

1. "Folder" — không phải file đơn lẻ

Otto, engineer ở Anthropic, nhấn mạnh: "Skills as organized folders that package expertise." Skill không phải 1 file .md. Nó là 1 thư mục mà trong đó, SKILL.md là entry point, và có thể có:

pr-review/                      ← tên skill = tên folder
├── SKILL.md                    ← entry point (luôn có, bắt buộc)
├── references/                 ← (optional) chi tiết deep dive
│   └── owasp-checklist.md
├── scripts/                    ← (optional) script executable
│   └── count-test-coverage.sh
└── assets/                     ← (optional) template, image
    └── review-template.md

Folder cho phép progressive disclosure — Claude chỉ đọc SKILL.md trước, rồi mới đọc file phụ nếu cần. Chi tiết ở Bài 15.3.

2. "Frontmatter" với name và description

Frontmatter là phần metadata ở đầu file SKILL.md, ngăn bởi ---:

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

When reviewing a PR, follow this checklist:
1. Run `git diff main...HEAD`
2. Check: ...

Hai field bắt buộc:

• name: tên skill (lowercase, dấu gạch ngang, max 64 chars, khớp với tên folder)
• description: mô tả khi nào nên dùng skill (max 1024 chars, quan trọng nhất)

Phần còn lại sau frontmatter là instructions — hướng dẫn Claude sẽ đọc khi skill được kích hoạt.

3. "Tự động kích hoạt qua semantic matching"

Đây là điểm khác biệt quan trọng nhất với slash command. Slash command bạn phải gõ /tên-command. Skill thì không cần.

Khi Claude Code khởi động, nó quét 4 location (chi tiết Bài 15.2), load chỉ name + description (chưa load full content). Rồi mỗi khi bạn gõ request:

Bạn: "Review this PR for me"
        ↓
Claude so sánh "Review this PR" với description
        của tất cả skill đã biết
        ↓
Match với skill pr-review (description: "Reviews pull requests...")
        ↓
Claude hỏi bạn xác nhận (confirmation prompt)
        ↓
Bạn OK → Claude load full SKILL.md → làm theo instructions

Đây gọi là semantic matching — không cần keyword exact, Claude hiểu ý định của bạn.

Cấu trúc một skill tối giản

Đây là skill đơn giản nhất có thể (2 field bắt buộc + vài dòng instructions):

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

When reviewing a pull request:

1. Run `git diff main...HEAD` to see the changes
2. Check for:
   - TypeScript typing issues
   - Missing tests for new code paths
   - Security concerns (SQL injection, XSS, secrets in code)
3. Write feedback with this structure:
   - **What works well:** (2-3 points)
   - **Issues to fix:** (critical/major/minor)
   - **Suggestions:** (optional improvements)
4. Tone: constructive, specific, avoid personal criticism

Một file duy nhất. Không dependencies. Không config gì thêm. Đây là mức tối thiểu để skill hoạt động.

Khi bạn tiến xa hơn, sẽ thêm field allowed-tools, model, folder references/, scripts/... — Bài 15.3.

Skill sống ở đâu?

Personal skills — ~/.claude/skills/

Nơi sống của skill của riêng bạn, đi theo bạn qua mọi project.

~/.claude/skills/
├── pr-description/
├── commit-message-style/
├── debug-nextjs-ssr/
└── explain-code-visually/

Windows path: C:\Users\<username>\.claude\skills\.

Phù hợp cho:

• Style cá nhân của bạn khi viết PR description
• Format commit message bạn ưa thích
• Cách bạn muốn Claude giải thích code (với diagram, analogy...)
• Checklist debug cho framework bạn chuyên sâu

Project skills — .claude/skills/ trong repo

Nơi sống của skill team bạn chia sẻ, commit vào repository.

my-app/
├── .claude/
│   └── skills/
│       ├── pr-review/              ← review standard của team
│       ├── brand-guidelines/       ← brand color, font, tone
│       └── onboarding-checklist/   ← cho new hire
├── src/
├── package.json
└── README.md

Ai clone repo về đều có những skill này. Không cần cài thêm. Push update → team pull về là có bản mới. Đây là cách chia sẻ chuẩn nhất cho team coding standards — chi tiết ở Bài 15.5.

Thứ tự ưu tiên (khi trùng tên)

Nếu bạn có pr-review ở cả personal và project, cái nào thắng? Có 4 tầng priority:

┌────────────────────────────────────────┐
│  1. Enterprise  (managed settings)     │ ← cao nhất
├────────────────────────────────────────┤
│  2. Personal    (~/.claude/skills)     │
├────────────────────────────────────────┤
│  3. Project     (.claude/skills)       │
├────────────────────────────────────────┤
│  4. Plugins     (installed plugins)    │ ← thấp nhất
└────────────────────────────────────────┘

Chi tiết về enterprise ở Bài 15.5. Debug conflict ở Bài 15.6.

Claude match skill với request như thế nào?

Cơ chế matching là điểm dễ gây hiểu lầm nhất. Hãy đi chậm.

Bước 1: Startup — load metadata only

Khi Claude Code khởi động, nó scan 4 location và load chỉ name + description của mỗi skill vào system prompt. Không load full content.

Chi phí token: Otto cho biết mỗi skill consume khoảng 30-50 token ở startup (chỉ riêng metadata). Có 20 skill → ~600-1000 token. Có 100 skill → ~3000-5000 token. Đây là lý do cho quy tắc "description < 1024 chars

tránh bloat.

Bước 2: Request matching

Bạn gõ: "Giải thích function này cho tôi".

Claude so sánh câu này với description của tất cả skill đã biết. Giả sử có skill mô tả "Explains code using visual diagrams and analogies" — semantic matching nhận ra "explain" + "function" overlap với "explain code".

Bước 3: Confirmation

Claude hỏi bạn:

I'd like to use the "explain-code-visually" skill for this.
It matches your request about explaining code. Proceed?
[y/n]

Bước này không tự ý bỏ qua. Nó bảo đảm bạn biết context nào Claude đang đưa vào conversation của mình. Quan trọng cho security và transparency.

Bước 4: Load full + execute

Bạn xác nhận → Claude đọc toàn bộ SKILL.md (bây giờ mới load chi tiết) → làm theo instructions.

Biểu đồ tổng quan

STARTUP                        RUNTIME (mỗi lần bạn gõ request)
─────────                     ────────────────────────────────
                              
Scan 4 locations               You: "Review this PR"
        ↓                              ↓
Load name+desc                 Claude semantic match
của từng skill                         ↓
(30-50 tok/skill)              Found: skill pr-review
        ↓                              ↓
System prompt                  Show confirmation
cache ready                            ↓
                               You confirm
                                       ↓
                               Claude loads full SKILL.md
                                       ↓
                               Claude follows instructions

Mô hình này là progressive disclosure — bạn chỉ "trả tiền" context window cho những skill thực sự được dùng.

Skill vs CLAUDE.md vs Slash Command

Đây là câu hỏi thường gặp nhất: "Tôi đã có CLAUDE.md / slash command rồi, skill thêm gì nữa?"

Sự khác biệt nằm ở khi nào load và ai trigger:

Câu hỏi quyết định: "Nó luôn luôn áp dụng, hay đôi khi áp dụng?"

┌──────────────────────────────────────────────────┐
│                                                  │
│   Instruction này có áp dụng                     │
│   mọi conversation của project này?              │
│                                                  │
│        ┌─── CÓ ──→  CLAUDE.md                    │
│        │                                         │
│        └─── KHÔNG ──→ Hỏi tiếp:                  │
│                                                  │
│            Bạn muốn trigger tay,                 │
│            hay muốn Claude tự nhận?              │
│                                                  │
│            ┌─── Trigger tay ──→ Slash command    │
│            │                                     │
│            └─── Tự nhận ──→ SKILL                │
│                                                  │
└──────────────────────────────────────────────────┘

Ví dụ cụ thể

Ví dụ theo ngành — Khi nào là skill?

Sales Operations

Pain: Tối nào Bảo — sales ops — cũng tổng hợp deal week-over-week. Paste lại format bảng, nhắc lại KPI quan trọng, yêu cầu Claude check CRM + Slack channel #sales. 15 phút mỗi ngày chỉ để "prompt lại".

Thành skill:

---
name: weekly-sales-digest
description: Generates weekly sales digest from CRM and Slack data. Use when asked for weekly sales update, sales summary, or end-of-week report.
---

Sources to pull: CRM deals closed this week, Slack #sales messages tagged
[win], emails with "Proposal" in subject...

Output format: ...

Kết quả: 15 phút/ngày → 1 phút (chỉ cần nói "tổng hợp sales tuần này").

Content Marketing

Pain: Linh viết 5 blog post/tuần. Mỗi post, cô phải paste lại brand guideline (tone, từ cấm, emoji policy), SEO checklist, CTA template. Tổng 200 dòng prompt prefix cho mỗi bài.

Thành skill:

---
name: blog-post-writer
description: Writes blog posts following company brand guidelines and SEO best practices. Use when writing a blog post, article, or web content.
---

[Instructions ngắn gọn]
[Link tới references/brand-tone.md cho chi tiết]
[Link tới references/seo-checklist.md]

Kết quả: 200 dòng prompt → 0 dòng. Tone nhất quán 100% các bài.

Finance Analyst

Pain: Hằng reconcile báo cáo tháng. Mỗi lần cần instruct Claude: chạy match_transactions.py, flag variance > $5000, xuất Excel 3 sheet (matched, unmatched, flagged). Paste 3 sheet template mỗi lần.

Thành skill với multi-file:

monthly-close/
├── SKILL.md                        ← instructions chính
├── scripts/
│   └── match_transactions.py       ← script executable
└── assets/
    └── excel-template.xlsx         ← template 3 sheet

Kết quả: Claude gọi script thay vì generate từ đầu (chính xác hơn), template auto-applied. 45 phút → 10 phút.

Legal Operations

Pain: Review NDA, mỗi lần phải nhắc Claude check 12 điều khoản chuẩn (jurisdiction, term, confidentiality scope, carve-outs, liability cap...). Claude thỉnh thoảng miss 1-2 điều khoản.

Thành skill:

---
name: nda-review
description: Reviews NDA contracts against company standard terms. Use when reviewing NDA, confidentiality agreement, or legal document starting with "Non-Disclosure".
allowed-tools: Read, Grep, Glob
---

[12-point checklist]
[Red flag patterns]

allowed-tools restrict Claude chỉ có thể đọc, không edit file contract → đảm bảo Claude không vô tình modify NDA.

Kết quả: 0 điều khoản bị miss, peace of mind cho legal team.

Healthcare Operations

Pain: Clinical research coordinator consolidate patient records hàng tuần. Pull lab results, imaging, notes vào unified timeline. Mỗi lần cần instruct: "theo thứ tự time, flag giá trị bất thường, list current medications...".

Thành skill:

---
name: patient-record-consolidation
description: Consolidates patient records into unified timeline. Use when processing patient data, creating medical summary, or preparing case review.
---

Process:
1. Timeline-based aggregation
2. Flag lab values outside normal range
3. Extract current medications
4. Privacy: never log patient names outside processing

Kết quả: 30 phút/patient → 5 phút. Zero inconsistency.

Skill là open standard — không vendor lock-in

Một điểm mà DBS tutorial nhấn mạnh: skill format là open standard (agentskills.io). Không chỉ hoạt động với Claude.

The skill format is actually an open standard. It doesn't just work across Claude, but it works across other tools like OpenAI's Codex or Google's Gemini and a growing list of other AI agents. So whatever you build today is not vendor-locked into Claude.

Skill pr-review bạn viết hôm nay có thể dùng ở:

• Claude Code (terminal + IDE)
• Claude.ai (web, paid plan)
• Claude API (programmatic)
• Các agentic tool khác implement cùng standard

Đây là điểm rất khác với "một prompt template riêng cho mỗi tool". Bạn đầu tư viết skill 1 lần, dùng nhiều chỗ.

Anti-patterns — Những sai lầm cần tránh

Biến CLAUDE.md constraint thành skill

Sai lầm

Tạo skill use-typescript-strict với description "Always use TypeScript strict mode".

Tại sao sai

Constraint này luôn luôn áp dụng. Nếu là skill, Claude phải "match" vào mỗi request — thừa thãi. Quan trọng hơn, nếu skill không trigger (do description mismatch), bạn mất constraint.

Cách đúng

Để trong CLAUDE.md của project.

Description quá chung chung

Sai lầm:

description: Helps with code.

Tại sao sai

Semantic matching cần overlap cụ thể. "Helps with code" match với mọi request liên quan code — Claude bối rối, trigger sai skill.

Cách đúng

Action cụ thể + trigger phrase:

description: Reviews pull requests for code quality issues. Use when asked to "review this PR", "check my changes", or "give me PR feedback".

Một skill "làm tất cả"

Sai lầm

Skill dev-helper với description liệt kê 10 thứ: "review code, write tests, format commits, debug errors, explain code...".

Tại sao sai

Mơ hồ → match không chính xác. Hơn nữa, khi 10 thứ gộp, file SKILL.md bị phình to.

Cách đúng

1 skill = 1 task. Có pr-review, test-generator, commit-format — 3 skill riêng, mỗi cái description rõ.

Nhồi cả 40 trang PDF vào SKILL.md

Sai lầm

Copy toàn bộ brand book 40 trang vào SKILL.md.

Tại sao sai

Mỗi lần skill kích hoạt, ăn hết 30% context window. Duplicate trong mỗi conversation.

Cách đúng

Progressive disclosure — SKILL.md ngắn, link tới references/brand-book.md, Claude chỉ đọc khi cần. Chi tiết Bài 15.3.

Áp dụng ngay

Bài tập: Xác định 3 skill candidate đầu tiên (~10 phút)

Bước 1

Mở lịch sử chat Claude Code gần nhất (7 ngày qua). Tìm ít nhất 3 lần bạn paste cùng 1 instruction nhiều lần.

Bước 2

Với mỗi lần paste, trả lời 3 câu:

Bước 3: Phân loại:

• Instruction nào luôn luôn áp dụng → để trong CLAUDE.md.
• Instruction nào chỉ áp dụng đôi khi, tự động → candidate cho skill.
• Instruction nào bạn muốn trigger tay (ví dụ: /format-diff) → candidate cho slash command.

Bước 4: Chọn 1 skill để build ở Bài 15.2. Ưu tiên cái:

• Bạn làm nhiều nhất (ít nhất 3 lần/tuần)
• Same format every time (không phải cái mỗi lần khác nhau)
• Dễ mô tả trigger phrase (không phải "help me with random stuff")

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

Tài liệu tham khảo

• agentskills.io — open standard specification
• Claude Code documentation — Skills — official docs
• Otto (Anthropic), "Claude Agent Skills Explained" — video