Skills — Dạy Claude một lần, dùng mãi mãi

Skill là gì?

Agent Skill là một folder chứa file markdown (SKILL.md) — có thể kèm scripts và resources thêm — mà Claude Code tự động phát hiện và load khi request của bạn match với description của skill đó.

Định nghĩa chính thức từ Anthropic:

Điểm khác biệt then chốt: skill không phải là lệnh bạn phải gõ. Skill là kiến thức bạn dạy cho Claude một lần — Claude tự biết khi nào nên dùng kiến thức đó.

Cơ chế auto-trigger

Khi bạn gõ bất kỳ prompt nào, Claude không chỉ đọc prompt đó. Claude đọc xong rồi so sánh với toàn bộ danh sách skill đang available, xem description của skill nào match nhất, sau đó load skill đó vào context để thực thi.

Điểm quan trọng: khi không match, Claude chỉ load tên + description của skill (vài chục token). Full content của skill chỉ load khi match. Đây là lý do skill tiết kiệm context hơn CLAUDE.md — như đã thấy ở Bài 2.5: skill là on-demand, CLAUDE.md là always-on.

                    ┌─────────────────────────────────────┐
  Bạn gõi prompt   │                                     │
  ──────────────►  │  Claude Code                        │
                   │                                     │
                   │  1. Đọc prompt của bạn              │
                   │  2. Check danh sách available skills│
                   │     ├─ pr-review    (description)   │
                   │     ├─ commit-pr    (description)   │
                   │     ├─ code-explain (description)   │
                   │     └─ ...                          │
                   │  3. So sánh prompt vs descriptions  │
                   │                                     │
                   │         Match found?                │
                   │         /         \                 │
                   │        YES         NO               │
                   │         │           │               │
                   │  Load full skill  Proceed normally  │
                   │  content vào      với general       │
                   │  context          knowledge         │
                   │         │                           │
                   │  Execute với      Execute           │
                   │  skill knowledge                    │
                   └─────────────────────────────────────┘

Anatomy của SKILL.md

Một SKILL.md có hai phần bắt buộc: YAML frontmatter và body instructions.

Ví dụ thực tế: PR review skill

YAML frontmatter — phần quan trọng nhất

name: pr-review
description: Review PR theo team standards với security checks, accessibility,
  và performance. Trigger khi user nói "review PR", "check this branch",
  "before commit", "xem code này", "có vấn đề gì không".

# PR Review Skill

## Quy trình review (theo thứ tự)

### 1. Security check
- Không hardcode credentials, API keys, secrets
- Input validation ở tất cả entry points (không trust client data)
- SQL queries dùng parameterized (không string concat)
- Error messages không leak internal stack traces ra ngoài

### 2. Code quality
- Không có dead code (function không được gọi, variable không dùng)
- Naming rõ ràng — đọc là hiểu intent, không cần comment giải thích
- Function không quá 50 dòng, tách nếu dài hơn
- Mỗi function làm đúng 1 việc

### 3. Test coverage
- Happy path có test
- Edge cases: empty input, null, 0, negative number, string rỗng
- Error paths có test (không chỉ test khi mọi thứ ổn)

### 4. Output format
Trả về dạng:
- **CRITICAL** (must fix trước khi merge): [vấn đề]
- **MAJOR** (nên fix): [vấn đề]
- **MINOR** (có thể fix sau): [vấn đề]
- **SUGGESTION** (optional improvement): [gợi ý]

YAML frontmatter — phần quan trọng nhất

name: Định danh của skill. Dùng kebab-case, ngắn gọn.

description: Đây là trái tim của skill. Claude đọc description này để quyết định có nên load skill hay không. Description tốt cần:

Description quá generic: "Dùng khi review code" → Claude có thể trigger mọi lúc bạn hỏi về code.

Description quá specific: "Trigger chỉ khi user gõ đúng chữ 'review PR #123'" → Miss hàng loạt variation hợp lệ.

Description đúng: Mô tả rõ ràng task type, list 3-6 trigger phrase tự nhiên, không giới hạn cứng nhắc.

Body — instructions chi tiết

Body là phần Claude thực sự đọc khi skill được trigger. Viết như bạn đang viết instructions cho một developer mới rất giỏi nhưng không biết team context:

Body không có giới hạn độ dài — nhưng nhớ rằng toàn bộ body sẽ load vào context khi trigger. Skill 200 dòng sẽ tốn ít context hơn CLAUDE.md có 200 dòng về cùng topic nhưng load mọi lúc (xem Bài 2.5 để hiểu tradeoff).

• Mô tả skill làm gì (để Claude hiểu scope)
• List trigger keywords/phrases điển hình (để matching chính xác hơn)
• Đủ specific để không trigger nhầm, đủ broad để không miss variation
• Dùng heading để structure
• Bullet points cho checklist
• Code examples khi cần
• Explicit về format output bạn muốn

name: pr-review          # Tên ngắn, kebab-case
description: ...         # Claude dùng cái này để quyết định trigger

Bảng so sánh: Skill vs CLAUDE.md vs Slash Command vs Hook

Đây là bảng bạn cần thuộc lòng. Bốn công cụ này thoạt nhìn có vẻ overlap — nhưng mỗi cái có use case riêng biệt hoàn toàn.

Quy tắc quyết định nhanh

Bạn muốn Claude làm X. Câu hỏi:

Q1: X có relevant cho MỌI task trong project không?
    → YES: đẩy vào CLAUDE.md
    → NO: tiếp tục

Q2: Bạn muốn TỰ gọi khi cần, không auto?
    → YES: viết slash command
    → NO: tiếp tục

Q3: X phải xảy ra CHẮC CHẮN mỗi lần event E xảy ra?
    → YES: viết hook (xem Bài 2.11)
    → NO: tiếp tục

Q4: X là kiến thức/checklist/standard cho một loại task cụ thể?
    → YES: viết Skill ← bạn đang ở đây

Storage locations — đặt skill ở đâu?

Skill có thể lưu ở hai nơi, với ý nghĩa hoàn toàn khác nhau:

Personal skills: ~/.claude/skills/

Project skills: .claude/skills/

Bảng quyết định: personal vs project

• Theo bạn qua mọi project
• Không được commit vào git (nằm ngoài repo)
• Phù hợp cho: personal preferences, commit style của bạn, cách bạn muốn code được explain, debug workflow cá nhân
• Checked in vào git
• Ai clone repo đều có skill tự động
• Phù hợp cho: team standards, brand guidelines, coding conventions của tổ chức

project-root/
├── .claude/
│   └── skills/
│       ├── pr-review/
│       │   └── SKILL.md
│       ├── release-notes/
│       │   └── SKILL.md
│       └── brand-guidelines/
│           ├── SKILL.md
│           └── assets/
│               └── color-tokens.json
├── src/
└── ...

Ví dụ thực chiến: Tạo skill code-explainer từ scratch

Bước 0: Identify pattern

Bạn là tech lead, mỗi tháng có 2-3 junior developer onboard. Lần nào bạn cũng phải explain:

Sau lần thứ tư explain cùng một thứ, đây rõ ràng là một skill.

Bước 1: Tạo folder

Bước 2: Viết frontmatter

• Authentication flow trong codebase
• Cách error handling được chuẩn hóa
• Tại sao dùng repository pattern thay vì direct DB query

mkdir -p ~/.claude/skills/code-explainer
touch ~/.claude/skills/code-explainer/SKILL.md

Bước 2: Viết frontmatter

Bước 3: Viết body — 5 sections thiết yếu

name: code-explainer
description: Explain codebase concepts và architecture decisions cho
  developer mới hoặc junior. Trigger khi user nói "explain this",
  "how does X work", "giải thích", "tại sao lại dùng", "onboard",
  "junior muốn hiểu", "walk me through".

Bước 3: Viết body — 5 sections thiết yếu

Bước 4: Test với 3 prompt variations

# Code Explainer Skill

## Nguyên tắc giải thích

Luôn theo thứ tự: Why → What → How → Example.
- **Why**: Tại sao pattern/decision này tồn tại (business reason hoặc technical reason)
- **What**: Nó là gì (định nghĩa ngắn, không jargon)
- **How**: Cơ chế hoạt động (flow hoặc diagram nếu phức tạp)
- **Example**: Code snippet thực tế từ codebase

## Audience adjustment

Khi giải thích cho junior (hoặc không rõ level):
- Dùng analogy đời thực trước khi dùng technical term
- Hỏi "Bạn quen với X chưa?" trước khi assume
- Không skip bước nào trong flow — mọi bước đều quan trọng

Khi giải thích cho senior / code review:
- Đi thẳng vào tradeoff và reasoning
- Compare với alternatives (tại sao chọn A thay vì B)

## Khi giải thích authentication flow

1. Start từ entry point (request vào API)
2. Trace qua middleware chain
3. Explain JWT structure và validation
4. Explain token refresh logic
5. Show error cases (expired, invalid, missing)

Luôn kèm diagram ASCII nếu flow có branching.

## Khi giải thích architecture decisions

Format:
- **Context**: Vấn đề gì đã tồn tại trước khi quyết định này
- **Decision**: Team đã chọn gì
- **Rationale**: Tại sao (technical + business)
- **Tradeoffs**: Cái gì mất đi khi chọn cách này
- **Alternatives considered**: Những option khác đã được cân nhắc

## Output format

Kết thúc mỗi explanation bằng:
- 1-2 câu tóm tắt "Nếu chỉ nhớ một thứ: [X]"
- Gợi ý file/function nên đọc tiếp để hiểu sâu hơn

Bước 4: Test với 3 prompt variations

Cả ba nên trigger skill. Nếu không trigger, kiểm tra lại description — thêm keyword từ prompt variation đó vào description.

Bước 5: Iterate

Sau vài lần dùng, bạn nhận ra Claude đôi khi explain quá dài. Thêm vào body:

Prompt 1: "Explain authentication flow cho junior mới join"
Prompt 2: "Tại sao code này dùng repository pattern?"  
Prompt 3: "Walk me through cái error handling middleware"

Bước 5: Iterate

Tune description và body dựa trên thực tế dùng là process bình thường — skill tốt thường mất 2-3 lần iterate.

## Độ dài explanation

- Explanation ngắn (junior hỏi khái niệm đơn): 150-300 từ
- Explanation trung bình (flow hoặc pattern): 300-500 từ  
- Explanation dài (architecture decision phức tạp): 500-800 từ

Hỏi user "Bạn muốn version ngắn hay chi tiết?" nếu không rõ scope.

Case studies theo role

Engineering team: skill release-notes

Vấn đề: Mỗi sprint, lead engineer mất 1 tiếng viết release notes bằng cách manually đọc git log và Jira tickets.

Skill:

Body: Instructions để Claude chạy git log --oneline từ tag trước, match commit với Linear ticket ID trong commit message, group theo feature/bugfix/breaking change, format theo template markdown của team.

Kết quả: 1 tiếng → 5 phút. Skill chạy lệnh git, parse output, format đúng template.

Designer ship code (Megan use case): skill design-handoff

Vấn đề: Designer Megan đã học cách dùng Claude Code để tự ship UI changes (xem case study Megan ở Bài 2.1). Nhưng mỗi lần handoff component, cô ấy phải nhắc Claude về Figma variables naming, spacing scale, và dark mode requirements.

Skill:

name: release-notes
description: Generate release notes từ git log và Linear/Jira tickets.
  Trigger khi "release notes", "changelog", "sprint summary",
  "viết release", "prepare release".

Designer ship code (Megan use case): skill design-handoff

Body: Danh sách color tokens, spacing scale, typography scale của team; checklist: dark mode variant, hover/focus states, accessibility (WCAG 2.1 AA), responsive breakpoints; output format là markdown table với props, default values, và Figma link.

Kết quả: Megan không phải nhắc design system mỗi lần. Claude tự apply toàn bộ constraints.

DevOps: skill incident-postmortem

Vấn đề: Sau mỗi incident, team mất 2 tiếng viết postmortem từ đầu — format không nhất quán, action items hay bị bỏ sót.

Skill:

name: design-handoff
description: Generate component spec docs theo team design system.
  Trigger khi "design handoff", "component spec", "viết spec",
  "document component", "Figma to code".

DevOps: skill incident-postmortem

Body: Template 5-whys, checklist thu thập data (timeline, metrics, logs), format action items với owner/deadline/status, reminder về blameless culture.

Kết quả: Consistent postmortem format, không bỏ sót action items, mới member cũng follow cùng process.

Mobile team: skill icon-export

Vấn đề: Designer export icon từ Figma theo nhiều size khác nhau cho iOS và Android — mỗi lần phải nhớ conventions khác nhau.

Skill:

name: incident-postmortem  
description: Tạo postmortem report theo 5-whys framework với action
  items có owner và deadline. Trigger khi "postmortem", "incident report",
  "RCA", "root cause", "viết báo cáo sự cố".

Mobile team: skill icon-export

Body: iOS: naming convention (icon-name@1x.png, @2x, @3x), folder structure trong Xcode Assets.xcassets; Android: density buckets (mdpi/hdpi/xhdpi/xxhdpi/xxxhdpi), vector drawable preferred; command để batch convert SVG với inkscape CLI.

Open source maintainer: skill triage-issue

Vấn đề: Maintainer nhận 30-50 GitHub issues/tuần — phần lớn là duplicate, hoặc cần label và assign.

Skill:

name: icon-export
description: Hướng dẫn export và organize icon assets cho iOS và Android.
  Trigger khi "icon export", "export asset", "iOS icons", "Android icons",
  "icon set", "@2x @3x".

Open source maintainer: skill triage-issue

Body: Checklist phân loại (bug/feature/question/duplicate), mapping keywords → labels, template comment lịch sự khi close duplicate, gợi ý assignee theo domain expertise.

Marketing/Content team: skill blog-seo-check

Vấn đề: Content writer dùng Claude để viết blog post nhưng hay quên check SEO basics trước khi publish.

Skill:

name: triage-issue
description: Phân loại GitHub issue: detect duplicate, apply labels,
  suggest assignee. Trigger khi "triage", "issue này là gì",
  "categorize issue", "label issue", "assign issue".

Marketing/Content team: skill blog-seo-check

Body: Checklist H1/H2 structure, meta description 150-160 chars, internal link tối thiểu 2-3, image có alt text, focus keyword xuất hiện trong title + first paragraph + một H2, readability (Flesch score).

name: blog-seo-check
description: Audit blog post cho SEO: headers, meta description, internal
  links, image alt text, keyword density. Trigger khi "seo check",
  "review bài viết", "before publish", "audit content".

Khi nào tạo Skill? — Decision flowchart

Tóm tắt quy tắc:

• Xảy ra guaranteed mỗi lần event? → Hook
• Bạn muốn explicit invoke? → Slash command
• Relevant mọi task? → CLAUDE.md
• Pattern lặp, task-specific, auto-trigger? → Skill

Bạn nhận ra mình đang giải thích cùng một thứ cho Claude
                           │
                           ▼
        Bạn đã làm việc này ≥ 3 lần chưa?
              /                    \
            YES                     NO
             │                      │
             ▼                      ▼
   Nó có xảy ra tự động,      Ghi chú lại, chờ thêm
   không cần trigger của          lần nữa
   bạn, MỖI LẦN không fail?
         /          \
       YES            NO
        │              │
        ▼              ▼
     Viết Hook     Nó phải invoke
   (Bài 2.11)      explicit, bạn    NO
   thay vì Skill    muốn tự gọi? ────────►  Relevant
                       │                    cho MỌI
                      YES                   task không?
                       │                      │
                       ▼                     YES
                  Viết Slash               Đưa vào
                  Command               CLAUDE.md
                  (Bài 2.8)
                  thay vì Skill
                                    Còn lại:
                                   ┌──────────────┐
                                   │  Viết SKILL  │
                                   └──────────────┘

Anti-patterns

Anti-pattern 1: Description quá generic

Description generic → Claude trigger nhầm (load skill khi không cần) hoặc không trigger đúng lúc cần.

Anti-pattern 2: Description quá cứng nhắc

# WRONG
description: "Giúp Claude làm việc tốt hơn với code"

# RIGHT  
description: "Review security vulnerabilities trong code: injection, auth bypass,
  insecure dependencies. Trigger khi 'security review', 'audit code',
  'kiểm tra lỗ hổng', 'pentest checklist'."

Anti-pattern 2: Description quá cứng nhắc

Skill không trigger = skill vô dụng.

Anti-pattern 3: Nhồi mọi thứ vào 1 skill khổng lồ

Khi match, toàn bộ 500 dòng load vào context. Thay vào đó:

Mỗi skill nhỏ, focused. Chỉ load khi thực sự cần.

Anti-pattern 4: Hardcode paths và usernames

RIGHT:
skills/
├── pr-review/         (chỉ PR review)
├── commit-pr/         (chỉ commit message)
├── release-notes/     (chỉ release notes)
└── security-audit/    (chỉ security)

# WRONG
description: "Chỉ trigger khi user gõ đúng chữ 'security review PR #123'"

# RIGHT
description: "Trigger khi user đề cập security, vulnerability, auth issue,
  injection, OWASP, pentest — dù phrasing khác nhau."

Anti-pattern 4: Hardcode paths và usernames

Hardcode paths → skill chỉ dùng được trên máy của một người. Hardcode usernames → outdated sau 3 tháng.

Anti-pattern 5: Nhầm skill với hook

Nếu bạn muốn format code tự động sau MỖI lần Claude edit file — đó không phải skill, đó là hook (xem Bài 2.11). Skill là kiến thức Claude áp dụng khi recognize task type. Hook là automation chạy mỗi khi event xảy ra, guaranteed, không cần Claude "nhận ra".

Dấu hiệu bạn đang dùng skill cho việc của hook: bạn viết trong description "Trigger EVERY TIME Claude edits a file" — "every time" + "event" = hook territory.

Anti-pattern 6: Personal skill trong project repo (hoặc ngược lại)

Personal skill chứa style cá nhân ("Explain code theo cách tôi thích") → đừng checked in vào project repo, vì mọi teammate sẽ thấy Claude explain theo style của bạn, không phải của họ.

Team standard skill ("PR phải pass checklist security này") → phải vào project .claude/skills/, không phải personal ~/.claude/skills/, vì teammate cần có skill này khi clone repo.

Anti-pattern 7: Không version skill khi tech stack thay đổi

Skill deploy-staging được viết năm 2024 khi team dùng Heroku. Năm 2025 team migrate sang AWS ECS. Skill cũ vẫn còn trong .claude/skills/ nhưng instructions không còn đúng.

Cách tránh: Treat skill như code. Khi tech stack thay đổi, update hoặc archive skill cũ. Có thể thêm version note trong skill header:

# WRONG — trong SKILL.md body
Chạy test bằng `/Users/alice/workspace/myproject/scripts/run-tests.sh`
Reviewer mặc định: @alice-dev-2023

# RIGHT
Chạy test bằng `npm test` hoặc lệnh test trong CLAUDE.md của project
Reviewer: xem team/CODEOWNERS file trong repo

Anti-pattern 7: Không version skill khi tech stack thay đổi

<!-- Last updated: 2026-01 — migrated deploy to AWS ECS -->

Mẹo nâng cao

Mẹo 1: Test description với 5 variations trước khi deploy

Trước khi dùng skill trong production, thử 5 cách gõ khác nhau để trigger:

Skill tốt nên trigger cả 5. Nếu miss 2/5, tune lại description — thêm keywords từ những variation bị miss.

Mẹo 2: Composable skills

Skill không cần standalone. Skill release-notes có thể reference workflow của skill git-log-summary khác:

Variation 1: "review PR này trước khi merge"
Variation 2: "check code của branch feature/auth"
Variation 3: "có vấn đề gì với implementation này không"
Variation 4: "before I commit, anything to fix?"
Variation 5: "xem lại cái PR #456 đi"

Mẹo 2: Composable skills

git log $(git describe --tags --abbrev=0)..HEAD --oneline

## Bước 1: Thu thập git log

Chạy lệnh sau để lấy commits từ tag cuối:

Mẹo nâng cao (tiếp)

Mẹo 3: Tham khảo real skill example

Reference skills trong repo của bạn (thư mục skills/ hoặc .claude/skills/) là ví dụ real của một skill phức tạp — có frontmatter, có multi-phase workflow, có reference files, có principles. Đọc nó để hiểu skill có thể scale đến mức độ phức tạp nào.

Anthropic cũng có course riêng về Agent Skills: Introduction to Agent Skills — nên xem sau khi hoàn thành bài này.

Mẹo 4: Skill template trong organization

Nếu bạn là tech lead của một team lớn, tạo "skill template repo" — một repo riêng chứa các skill cơ bản mà mọi project nên có. Thành viên mới fork repo đó vào personal ~/.claude/skills/, xong là có ngay bộ skill cơ bản.

Ví dụ structure:

Mẹo 5: Document trigger keywords rõ ràng trong description

Thay vì hy vọng Claude suy ra, hãy explicit:

team-claude-skills/
├── README.md
├── commit-conventional/    (Conventional Commits format)
├── pr-review-standard/     (team PR standards)
├── code-explain-beginner/  (explain cho junior)
└── security-basics/        (OWASP top 10 checklist)

## Bước 2: Parse và format

Nếu project có skill `git-log-summary` available, invoke nó để parse output.
Nếu không, follow format: `[type] [scope]: [description] [ticket-id]`

Mẹo 5: Document trigger keywords rõ ràng trong description

Multi-language trigger list đặc biệt hữu ích nếu team của bạn mix tiếng Anh và tiếng Việt.

description: "... Trigger khi user dùng các từ/phrase sau:
  VI: 'review code', 'xem code', 'kiểm tra', 'có lỗi gì không'
  EN: 'review', 'check this', 'any issues', 'before merge', 'LGTM?'"

Áp dụng ngay

Bài tập 1 (20 phút): Viết skill đầu tiên của bạn

Bước 1: Nghĩ về 3 tháng gần nhất. Bạn đã nhắc Claude cùng một thứ ít nhất 3 lần chưa? Ghi ra:

Bước 2: Tạo skill folder:

Pattern lặp: ________________________________
Ví dụ câu nhắc: ______________________________
Tần suất: _____ lần/tháng

Bài tập 1 (20 phút): Viết skill đầu tiên của bạn

Bước 3: Viết SKILL.md với frontmatter và body. Checklist:

Bước 4: Test với 3 prompt variations khác nhau. Skill trigger cả 3? Nếu không, tune description.

Bước 5: Dùng skill trong 1 tuần, ghi lại:

Dựa vào data đó để iterate.

Bài tập 2 (15 phút): Khám phá skills hiện có

Bước 1: Check xem bạn đang có skills nào:

• [ ] name ngắn, kebab-case
• [ ] description có mô tả scope + ít nhất 3 trigger phrases
• [ ] Body có ít nhất 3 sections với instructions cụ thể
• [ ] Không hardcode paths hoặc usernames
• Số lần trigger đúng: _____
• Số lần trigger nhầm (false positive): _____
• Số lần miss (bạn cần nhắc mà skill không trigger): _____

# Personal skill (chỉ cho bạn)
mkdir -p ~/.claude/skills/ten-skill-cua-ban

# Project skill (cả team)
mkdir -p .claude/skills/ten-skill-cua-ban

Bài tập 2 (15 phút): Khám phá skills hiện có

Bước 2: Đọc SKILL.md của một skill có sẵn. Trigger keywords là gì? Scope là gì?

Bước 3: Thử invoke skill đó với 2-3 prompt variations. Hoạt động như expected không?

Bước 4: Nếu chưa có skill nào, vào Introduction to Agent Skills để xem Anthropic cung cấp skill template gì.

# Personal skills
ls ~/.claude/skills/ 2>/dev/null || echo "Chưa có personal skills"

# Project skills (từ trong project folder)
ls .claude/skills/ 2>/dev/null || echo "Chưa có project skills"

Tóm tắt

5 takeaways từ bài này:

🎯 Skill = kiến thức dạy một lần, Claude tự apply mãi mãi. Pattern lặp ≥3 lần là tín hiệu rõ ràng cần viết skill.

🎯 Description là linh hồn của skill. Claude dùng description để quyết định trigger — quá generic trigger nhầm, quá specific bỏ sót. Cần balance và test với nhiều prompt variations.

🎯 Personal skill theo bạn, project skill theo repo. Không nhầm hai loại — đặt sai chỗ gây ra inconsistency trong team hoặc mất skill khi đổi máy.

🎯 Skill tiết kiệm context hơn CLAUDE.md cho task-specific knowledge. Skill chỉ load khi match — PR review checklist không ngồi trong context khi bạn đang debug (xem Bài 2.5).

🎯 Skill không thay thế được hook hay slash command — mỗi công cụ có use case riêng. Hiểu bảng so sánh để dùng đúng tool cho đúng job.