15.2 · Tạo skill đầu tiên của bạn

Mở đầu: Từ "lý thuyết" tới "hành"

Trong bài này, chúng ta build skill pr-description — một skill viết PR description theo format What/Why/Changes. Đây là case đã được Anthropic dùng làm ví dụ trong video chính thức, vì nó đơn giản (1 file duy nhất, không script, không tool restriction) nhưng đủ để 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

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

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/
└── pr-description/                  ← tạo folder mới
    └── SKILL.md                     ← tạo file duy nhất

Đơ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/pr-description

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

Kiểm tra folder đã tạo:

ls -la ~/.claude/skills/

Bạn sẽ thấy pr-description/ 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/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

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

### Frontmatter (giữa hai `---`)

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.

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

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)

When writing a PR description:

1. Run git diff main...HEAD ...
2. Write a description following this format:

## What ## Why ## Changes

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

---

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:

/quit

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

Bước 5: Test skill

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

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"

Rồi trong Claude Code:

Write a PR description for my changes

Bạn sẽ thấy:

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

**Đã 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

---

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

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/, ...

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

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

┌───────────────────────────────────────────────────┐
│  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                    │
└───────────────────────────────────────────────────┘

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

• 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

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.

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)

┌────────────────────────────────────────────┐
│  🏢 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             │
└────────────────────────────────────────────┘

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:

This lets organizations enforce standards through enterprise skills while still allowing individual customization.

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.

Update và remove skill

Update

Mở ~/.claude/skills/pr-description/SKILL.md bằng editor nào cũng được, sửa, save.

/quit
claude

Remove

Xóa nguyên folder:

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

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

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

Account Executive — sales-call-prep

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

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

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

~/.claude/skills/pr-description/SKILL.md
   frontmatter: name: pr_description  ← 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
comprehensive pull request descriptions following industry best
practices with multiple formatting options and customizable
templates for various use cases...  [500+ chars]

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: Writes pull request descriptions. Use when creating a PR, writing a PR description, or summarizing changes.

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 writing a PR description, make it good.

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:

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:

• 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

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:

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ể)
• Instructions: 3-5 bullet/step ngắn gọn

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

Tài liệu tham khảo

• Anthropic Academy — "Creating your first skill"
• Official video — "Creating a PR description skill"
• agentskills.io — open standard fields