Tạo skill đầu tiên của bạ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:

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.

~/.claude/skills/
└── pr-description/                  ← tạo folder mới
    └── SKILL.md                     ← tạo file duy nhất

claude --version

Bước 1: Tạo folder skill

Mở terminal, chạy:

Giải thích:

Kiểm tra folder đã tạo:

• 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/pr-description → path đầy đủ tới folder skill
• Tên folder = tên skill. Quy tắc: lowercase, dấu gạch ngang, không gạch dưới (_), không space

mkdir -p ~/.claude/skills/pr-description

Bước 1: Tạo folder skill (tiếp)

Bạn sẽ thấy pr-description/ trong danh sách.

ls -la ~/.claude/skills/

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 ---)

cat > ~/.claude/skills/pr-description/SKILL.md << 'EOF'

name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed.

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed
EOF

Frontmatter (giữa hai ---)

Tại sao liệt kê 3 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)

• name: pr-description — phải khớp tên folder
• description — 3 loại trigger phrase:
• "creating a PR" → user có thể nói "create a PR"
• "writing a PR" → user có thể nói "write PR description for me"
• "summarize changes for a pull request" → variation khác

name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.

Instructions (dưới frontmatter)

Phần này Claude đọc khi skill được kích hoạt. Template cụ thể → output nhất quán 100%.

When writing a PR description:

1. Run `git diff main...HEAD` ...
2. Write a description following this format:
   ## What
   ## Why
   ## Changes

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.

# Nếu đang trong Claude Code session:
/quit

# Mở lại:
claude

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. pr-description phải nằm trong đó.

Nếu không thấy:

• Check lại tên file: SKILL.md (cap SKILL) — không phải skill.md, Skill.md, SKILL.MD
• Check lại path: ~/.claude/skills/pr-description/SKILL.md — không phải ~/.claude/skills/SKILL.md
• Chạy claude --debug để xem loading error
• Chi tiết debug ở Bài 15.6

What skills are available?

Bước 5: Test skill

Tạo một branch thay đổi gì đó để có git diff:

Rồi trong Claude Code:

cd /path/to/your/project
git checkout -b test-pr-skill
echo "// test change" >> src/utils.ts
git add src/utils.ts
git commit -m "test"

Bước 5: Test skill (tiếp)

Bạn sẽ thấy:

Write a PR description for my changes

Bước 5: Test skill (tiếp)

Đã xong. Skill đầu tiên của bạn đã hoạt động.

Quan trọng là:

• Claude tự biết dùng skill pr-description (bạn không gõ /pr-description)
• Claude chạy git diff theo instruction
• Format What/Why/Changes đúng template bạn viết
• Lần tới gõ "PR description for this branch", Claude vẫn dùng đúng skill này, output đúng format

I'll use the "pr-description" skill for this. [Loading skill]

Running: git diff main...HEAD
[shows diff]

## What
Adds a utility comment marker to src/utils.ts.

## Why
Testing the PR description skill functionality.

## Changes
- Added test comment to src/utils.ts

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 dev 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 thư mục theo thứ tự:

Load chỉ name + description của mỗi skill (không phải 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à:

Đâ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. "Write PR description", "draft a pull request", "summarize my changes for the PR" đều có thể trigger — nếu description của bạn cover đủ variation.

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:

Bạn có thể config để auto-accept skill confirmation nếu muốn — xem docs. Nhưng mặc định là luôn hỏi.

• 10 skill personal → 300-500 token overhead startup
• 50 skill + 20 project skill → ~2100-3500 token overhead
• 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 (description mơ hồ) — bạn có cơ hội deny

┌───────────────────────────────────────────────────┐
│  User: "Write a PR description for my changes"    │
└───────────────────────────────────────────────────┘
                       ↓
┌───────────────────────────────────────────────────┐
│  Claude compares this sentence semantically       │
│  with ALL skill descriptions:                     │
│                                                   │
│  pr-description: "Writes pull request             │
│    descriptions. Use when creating a PR..."       │
│    → STRONG match (PR, description, write)        │
│                                                   │
│  commit-style: "Formats commit messages..."       │
│    → Weak match                                   │
│                                                   │
│  test-generator: "Writes unit tests..."           │
│    → No match                                     │
└───────────────────────────────────────────────────┘
                       ↓
┌───────────────────────────────────────────────────┐
│  Claude: "I'd like to use pr-description skill.   │
│           Proceed? [y/n]"                         │
└───────────────────────────────────────────────────┘
                       ↓ (you confirm)
┌───────────────────────────────────────────────────┐
│  Claude loads full SKILL.md content into context  │
│  Reads instructions → executes                    │
└───────────────────────────────────────────────────┘

1. Enterprise managed settings  ← platform admin deploy
   (path tùy OS, xem Bài 15.5)

2. ~/.claude/skills/             ← Personal (của bạn)
   pr-description/, commit-style/, ...

3. <current-repo>/.claude/skills/  ← Project (của repo hiện tại)
   brand-guide/, team-review/, ...

4. Installed plugins             ← Plugin marketplace
   plugin-foo/skills/bar/, ...

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 code-review, clone repo về thấy project cũng có skill code-review, hoặc công ty deploy enterprise skill code-review. Cái nào thắng?

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

Case study: Minh team lead

Minh có personal skill code-review (style của cá nhân anh, hơi informal).

Clone về project thấy project skill code-review cũng tồn tại (team đã agree style formal hơn).

→ Personal thắng project. Claude dùng skill cá nhân của Minh.

Nhưng tuần sau, công ty deploy enterprise skill code-review (mandatory, có compliance check OWASP).

→ Enterprise thắng personal. Dù Minh 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:

Công ty có thể enforce "review phải check security" ở tầng enterprise. Mỗi dev vẫn có thể tạo skill riêng với tên khác (personal-code-review) để 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.

┌────────────────────────────────────────────┐
│  🏢 1. Enterprise (managed settings)       │ ← cao nhất
│      - deploy bởi admin                    │
│      - override tất cả                     │
├────────────────────────────────────────────┤
│  👤 2. Personal (~/.claude/skills)         │
│      - skill của riêng bạn                 │
├────────────────────────────────────────────┤
│  📦 3. Project (.claude/skills in repo)    │
│      - commit vào Git, share team          │
├────────────────────────────────────────────┤
│  🔌 4. Plugins (installed plugins)         │ ← thấp nhất
│      - third-party marketplace             │
└────────────────────────────────────────────┘

Update và remove skill

Update

Mở ~/.claude/skills/pr-description/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:

/quit
claude

Remove

Restart Claude. Skill biến mất khỏi danh sách.

rm -rf ~/.claude/skills/pr-description

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

💼 Account Executive — sales-call-prep

Kết quả Thùy — AE: 45 phút prep/call → 5 phút (đọc briefing + điều chỉnh).

📣 Content Marketer — blog-outline

name: sales-call-prep
description: Prepares briefing for upcoming sales call. Use when preparing for a call, prep for meeting with prospect, or asked for call briefing.

For upcoming sales call:
1. Check CRM for account history (deals, interactions)
2. Search previous emails with the contact
3. Web search for recent news about their company (last 90 days)
4. Output: 1-page briefing with:
   - Account context (stage, ACV, decision makers)
   - 3 relevant talking points
   - 5 discovery questions
   - Potential objections + responses

📣 Content Marketer — blog-outline

💰 Finance Analyst — variance-analyst

name: blog-outline
description: Creates blog post outline from topic idea. Use when starting a blog post, outlining an article, or planning content.

Given a topic, create:
1. Working title (60 chars max for SEO)
2. Target keyword + 3 semantic variations
3. Hook (2-3 sentence opener)
4. 5-7 H2 sections with bullet points
5. CTA aligned with funnel stage
6. Estimated reading time

💰 Finance Analyst — variance-analyst

🎧 Customer Support Lead — escalation-drafter

name: variance-analyst
description: Analyzes budget vs actual variance for monthly reports. Use when analyzing variance, comparing actual to forecast, or preparing variance commentary.

For variance analysis:
1. Compare actuals vs budget for each line item
2. Flag variances > 10% or > $10K
3. Classify: volume-driven, price-driven, timing, other
4. Draft commentary for each flagged item (1-2 sentences)
5. Output: table with columns: Item, Budget, Actual, Variance $, Variance %, Driver, Commentary

🎧 Customer Support Lead — escalation-drafter

name: escalation-drafter
description: Drafts escalation message for tickets needing engineering attention. Use when escalating a ticket, writing handoff to engineering, or preparing urgent issue summary.

Escalation format:
- **Summary:** 1-line issue description
- **Impact:** users affected, severity
- **Reproduction:** exact steps
- **What we tried:** attempted fixes with results
- **Ask:** specific request for eng team
- **Customer context:** account tier, current mood

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. Memorize đi.

❌ 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

~/.claude/skills/pr-description/SKILL.md
   frontmatter: name: pr_description  ← sai, underscore

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

description: This is an excellent tool that helps you create
comprehensive pull request descriptions following industry best
practices with multiple formatting options and customizable
templates for various use cases...  [500+ chars]

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

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

description: Writes pull request descriptions. Use when creating a PR, writing a PR description, or summarizing changes.

❌ Viết instructions quá mơ hồ

Tại sao sai: Claude không biết "good" nghĩa gì → output mỗi lần khác.

Cách đúng: Format template cụ thể, rõ từng bullet:

When writing a PR description, make it good.

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

1. Run git diff main...HEAD
2. Output với sections: What / Why / Changes
3. What: 1 sentence
4. Why: 1-2 sentences context
5. Changes: bullet list, grouped by area

Áp dụng ngay

Bài tập 1: Tạo skill pr-description 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:

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

Quay lại danh sách candidate bạn liệt kê ở Bài 15.1 (3 skill). Pick 1 đơn giản nhất.

Bước 1: Đặt tên theo quy tắc lowercase-dash. Ví dụ: commit-message, daily-brief, code-explain-visually.

Bước 2: Tạo folder:

Bước 3: Viết SKILL.md:

Bước 4: Restart + test.

Bước 5: Ghi lại:

• ☐ Folder ~/.claude/skills/pr-description/ đã tạo
• ☐ File SKILL.md với frontmatter + instructions
• ☐ Restart Claude Code
• ☐ Hỏi "What skills are available?" → thấy pr-description
• ☐ Test với branch có diff, nhờ write PR description → output đúng format What/Why/Changes
• Frontmatter với name + description (150-300 chars, có trigger phrase cụ thể)
• Instructions: 3-5 bullet/step ngắn gọn
• Tên skill: __________
• Trigger phrase test: __________
• Lần đầu có trigger không? __________
• Nếu không, description thiếu keyword gì? __________

mkdir -p ~/.claude/skills/<tên-của-bạn>

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.