05 — Skills: Cấu Trúc & Cách Hoạt Động

Fundamentals — Kiến thức nền tảng

Skills là gì?

Skills là các gói hướng dẫn mở rộng khả năng của Claude. Mỗi skill là một file (hoặc thư mục) chứa instructions định nghĩa cách Claude xử lý một loại task cụ thể.

Khi bạn gõ /tên-skill trong Claude Code, Claude đọc toàn bộ hướng dẫn trong skill đó và áp dụng vào task hiện tại.

Ví dụ skill thực tế:

/commit → Claude tự phân tích diff và viết commit message chuẩn
/phan-tich-campaign → Claude phân tích dữ liệu ads theo quy trình MangoAds
/viet-copy → Claude viết copy quảng cáo theo tone và format của team

Nguyên lý thiết kế của Skills

Hiểu 3 nguyên lý này giúp bạn viết skill đúng hơn và hiệu quả hơn.

1. Progressive Disclosure — Tải từng lớp khi cần

Skills hoạt động theo hệ thống 3 lớp để tối ưu token:

Lớp	Nội dung	Khi nào được load
Lớp 1 — YAML frontmatter	`name`, `description`	Luôn luôn — có trong system prompt của Claude
Lớp 2 — SKILL.md body	Toàn bộ instructions	Khi Claude quyết định skill này phù hợp với task
Lớp 3 — File phụ	`references/`, `examples/`	Chỉ khi Claude chủ động điều hướng đến

Hệ quả thực tế: Frontmatter (lớp 1) phải đủ ngắn gọn để không tốn nhiều token, nhưng đủ rõ để Claude biết khi nào dùng skill. Tài liệu chi tiết đưa vào lớp 3.

2. Composability — Nhiều Skills chạy cùng lúc

Claude có thể load nhiều skills cùng một lúc. Skill của bạn phải hoạt động tốt khi đứng cạnh các skills khác — không nên giả định rằng nó là skill duy nhất đang chạy.

3. Portability — Chạy được trên mọi nền tảng

Một skill chạy được trên Claude.ai, Claude Code và API mà không cần sửa đổi, miễn là môi trường hỗ trợ các dependencies skill yêu cầu (ví dụ: có git, có node...).

Vị trí lưu trữ Skills

Skills có thể đặt ở 3 cấp độ, mỗi cấp có phạm vi áp dụng khác nhau:

Cấp độ	Đường dẫn	Áp dụng cho
Cá nhân	`~/.claude/skills/<tên-skill>/`	Tất cả project của bạn
Project	`.claude/skills/<tên-skill>/`	Project hiện tại
Enterprise	Cấu hình bởi admin	Toàn bộ team

Thứ tự ưu tiên khi trùng tên: Enterprise > Cá nhân > Project

Tip: Đặt skill dùng chung ở ~/.claude/skills/. Đặt skill đặc thù cho project vào .claude/skills/ trong repo.

Cấu trúc của một Skill

Dạng file đơn giản (phổ biến nhất)

~/.claude/skills/
└── viet-copy.md        ← tên file = tên slash command

Khi skill là một file .md đơn, tên file trở thành slash command: /viet-copy.

Dạng thư mục (cho skill phức tạp)

~/.claude/skills/
└── ten-skill/
    ├── SKILL.md           ← bắt buộc, file chính
    ├── scripts/           ← tùy chọn: code Python, Bash thực thi được
    │   ├── process_data.py
    │   └── validate.sh
    ├── references/        ← tùy chọn: tài liệu chi tiết, được load khi cần
    │   ├── api-guide.md
    │   └── examples/
    └── assets/            ← tùy chọn: templates, font, icon dùng trong output
        └── report-template.md

Khi skill là thư mục, SKILL.md là điểm vào chính. Các file phụ chỉ được load khi Claude điều hướng đến — giúp tối ưu token theo nguyên lý Progressive Disclosure.

Best practice: Giữ SKILL.md dưới 5.000 từ. Tài liệu chi tiết chuyển sang references/.

Quy tắc đặt tên bắt buộc

Đây là các lỗi phổ biến khiến skill bị từ chối khi upload:

Tên thư mục/file:

	Ví dụ	Kết quả
Dùng kebab-case	`phan-tich-campaign`	Đúng
Có dấu cách	`Phan Tich Campaign`	Sai
Dùng underscore	`phan_tich_campaign`	Sai
Có chữ hoa	`PhanTichCampaign`	Sai

File chính:

Phải đặt tên chính xác là SKILL.md (phân biệt hoa thường)
SKILL.MD, skill.md, Skill.md đều không được chấp nhận

Tên skill bị cấm:

Không được dùng claude hoặc anthropic trong tên (reserved)
Ví dụ: claude-helper, my-anthropic-skill → đều bị từ chối

Không được có README.md trong thư mục skill:

Mọi tài liệu đều đặt trong SKILL.md hoặc references/
Nếu chia sẻ skill trên GitHub, README.md đặt ở ngoài thư mục skill

Cấu trúc bên trong một file Skill

Mỗi file skill gồm 2 phần:

---
name: tên-skill
description: Mô tả khi nào Claude dùng skill này
---

# Phần hướng dẫn

Nội dung hướng dẫn Claude làm gì khi skill được kích hoạt.

Phần 1: Frontmatter (YAML giữa hai dấu `---`)

Đây là phần cấu hình. Claude đọc frontmatter để hiết skill này dùng cho việc gì và khi nào kích hoạt.

Bảng tất cả các trường frontmatter:

Trường	Bắt buộc	Ý nghĩa	Mặc định
`name`	Không	Tên skill, kebab-case, tối đa 64 ký tự. Trở thành `/slash-command`	Tên file/thư mục
`description`	Khuyến nghị	Claude dùng để quyết định khi nào kích hoạt. Tối đa 1024 ký tự. Không dùng XML tags	(trống)
`argument-hint`	Không	Gợi ý argument khi user gõ slash command, vd: `[campaign-id]`	(trống)
`disable-model-invocation`	Không	`true` = Claude không tự kích hoạt, chỉ user mới gọi được	`false`
`user-invocable`	Không	`false` = Ẩn khỏi menu `/`, chỉ Claude tự dùng	`true`
`allowed-tools`	Không	Tools được tự động approve khi skill chạy	(trống)
`model`	Không	Model Claude dùng khi skill này chạy	Model hiện tại
`context`	Không	`fork` = Chạy trong subagent độc lập	(trống)
`agent`	Không	Loại subagent khi `context: fork`	`general-purpose`
`license`	Không	License cho open-source skill. Vd: `MIT`, `Apache-2.0`	(trống)
`compatibility`	Không	Mô tả yêu cầu môi trường, tối đa 500 ký tự	(trống)
`metadata`	Không	Custom key-value pairs tùy ý (author, version, mcp-server...)	(trống)

Ví dụ frontmatter đầy đủ:

---
name: phan-tich-campaign
description: Phân tích hiệu suất campaign ads. Use when analyzing
  CTR/CPC/ROAS or reviewing campaign performance data.
argument-hint: [campaign-id]
allowed-tools: Read, Glob
metadata:
  author: MangoAds Team
  version: 1.0.0
---

Giới hạn bảo mật của frontmatter:

Không dùng ký tự < hoặc > (XML angle brackets) ở bất kỳ đâu trong frontmatter — frontmatter được đưa vào system prompt, content độc hại có thể inject instructions
Không dùng claude hoặc anthropic trong tên skill (reserved)

Phần 2: Body (nội dung hướng dẫn)

Phần này viết bằng Markdown. Claude đọc và tuân theo khi skill được kích hoạt.

Template cấu trúc được khuyến nghị:

---
name: ten-skill
description: [Skill làm gì] + [Khi nào dùng] + [Tính năng chính]
---

# Tên Skill

## Hướng dẫn

### Bước 1: [Bước đầu tiên]
Giải thích rõ ràng cần làm gì.

### Bước 2: [Bước tiếp theo]
...

## Ví dụ

### Ví dụ 1: [Tình huống phổ biến]
User nói: "..."
Hành động:
1. ...
2. ...
Kết quả: ...

## Xử lý lỗi

### Lỗi: [Thông báo lỗi phổ biến]
Nguyên nhân: ...
Cách xử lý: ...

Nguyên tắc viết instructions tốt:

Tránh	Nên làm
`Validate the data before proceeding`	`Chạy script validate.py --input {filename}. Nếu fail, kiểm tra: thiếu required fields, sai date format (dùng YYYY-MM-DD)`
`Helps with projects`	`Tạo project workspace trong Notion. Dùng khi user nói "tạo project", "setup workspace", "khởi tạo dự án"`
Instructions dài dòng, chôn vùi	Đặt thông tin quan trọng ở đầu, dùng `## QUAN TRỌNG` để highlight

Lưu ý: Code luôn deterministic hơn ngôn ngữ tự nhiên. Với các validation quan trọng, đặt logic vào scripts/ thay vì chỉ mô tả bằng lời.

Rules: Claude kích hoạt Skill khi nào?

Đây là phần quan trọng nhất khi viết skill. Claude dựa hoàn toàn vào trường description để quyết định có tự động dùng skill này không.

3 chế độ kích hoạt

Cấu hình	User gọi bằng `/`	Claude tự gọi	Khi nào dùng
Mặc định (không có gì)	Có	Có	Skill hỗ trợ chung, dùng được cả hai cách
`disable-model-invocation: true`	Có	Không	Skill có side-effect (deploy, send email, xóa file...)
`user-invocable: false`	Không	Có	Knowledge base nội bộ chỉ Claude dùng

Nguyên tắc an toàn: Skill nào có thể gây ra hành động không thể hoàn tác (gửi email, deploy, commit...) → luôn dùng disable-model-invocation: true.

Viết `description` hiệu quả

description là thứ duy nhất Claude đọc để quyết định có dùng skill không (lớp 1 trong Progressive Disclosure). Đây là field quan trọng nhất.

Công thức chuẩn:

[Skill làm gì] + [Khi nào dùng / trigger phrases] + [Tính năng chính]

Ví dụ xấu — không đủ thông tin:

# Quá chung chung
description: Helps with projects.

# Thiếu trigger phrases
description: Creates sophisticated multi-page documentation.

# Quá kỹ thuật, không có trigger người dùng
description: Implements entity model with hierarchical relationships.

Ví dụ tốt — đầy đủ thông tin:

# Rõ ràng, có trigger phrases cụ thể
description: Viết copy quảng cáo theo chuẩn MangoAds. Use when user
  wants to write ad copy, advertising content, Facebook/Google/TikTok
  ads, or any marketing copywriting. Trigger when user mentions: viết
  quảng cáo, copy ads, headline, caption, nội dung quảng cáo.

# Có negative trigger — tránh overtrigger
description: Advanced data analysis for CSV files. Use for statistical
  modeling, regression, clustering. Do NOT use for simple data
  exploration (use data-viz skill instead).

Ràng buộc kỹ thuật của description:

Tối đa 1024 ký tự
Không dùng ký tự < hoặc > (XML tags)
Viết song ngữ Anh-Việt để Claude nhận diện intent tốt nhất

Debug khi skill không trigger:

Hỏi thẳng Claude: "When would you use the [tên-skill] skill?" — Claude sẽ trích dẫn lại description. Điều chỉnh dựa trên câu trả lời.

Tính năng nâng cao

Argument — Truyền tham số vào Skill

Skill có thể nhận argument khi được gọi:

/phan-tich-campaign FB_2026_Q1

Trong file skill, dùng $ARGUMENTS để nhận giá trị này:

---
name: phan-tich-campaign
description: Phân tích campaign theo ID
argument-hint: [campaign-id]
---

Phân tích campaign có ID: $ARGUMENTS

Thực hiện theo các bước:
1. Tìm file data của campaign $ARGUMENTS trong thư mục reports/
2. ...

Các biến có thể dùng trong skill:

Biến	Giá trị
`$ARGUMENTS`	Toàn bộ arguments truyền vào
`$0`, `$1`, `$2`...	Argument theo vị trí (0-based)
`${CLAUDE_SESSION_ID}`	ID của session hiện tại
`${CLAUDE_SKILL_DIR}`	Đường dẫn thư mục chứa skill

Dynamic Context — Chạy lệnh trước khi Skill khởi động

Dùng !`lệnh` để inject output của shell command vào skill content. Claude nhận kết quả đã được render, không phải lệnh thô.

Ví dụ: Skill tự động lấy context của PR hiện tại:

---
name: review-pr
description: Review pull request hiện tại
allowed-tools: Bash(gh *)
---

## Context của PR này

- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Files changed: !`gh pr diff --name-only`

## Nhiệm vụ

Review PR ở trên và đưa ra nhận xét về:
1. Code quality và potential bugs
2. Security concerns
3. Performance issues

`allowed-tools` — Cấp quyền tool tự động cho Skill

Mặc định, mỗi khi Claude dùng một tool (đọc file, chạy lệnh...), nó sẽ hỏi permission. Với allowed-tools, các tool trong danh sách được tự động approve khi skill đang chạy.

---
name: doc-generator
description: Tự động tạo documentation từ source code
allowed-tools: Read, Glob, Grep, Write
---

Lưu ý bảo mật: Chỉ thêm tool vào allowed-tools khi bạn tin tưởng skill đó sẽ dùng tool an toàn. Không nên thêm Bash trừ khi cần thiết.

`context: fork` — Chạy Skill trong Subagent độc lập

Khi thêm context: fork, skill chạy trong một subagent riêng biệt — không có lịch sử hội thoại, không ảnh hưởng đến context chính.

---
name: audit-security
description: Kiểm tra security vulnerabilities trong codebase
context: fork
agent: Explore
allowed-tools: Read, Glob, Grep
---

Quét toàn bộ codebase tìm các vấn đề security phổ biến:
- SQL injection risks
- XSS vulnerabilities
- Hardcoded credentials
- Unsafe dependencies

Trả về báo cáo dạng markdown.

Khi nào dùng context: fork:

Task nặng, cần nhiều thời gian (không muốn block conversation chính)
Task cần đọc nhiều file (để tránh làm đầy context)
Muốn kết quả độc lập, không bị ảnh hưởng bởi lịch sử hội thoại

Loại agent có thể chọn:

Agent	Tối ưu cho
`Explore`	Đọc, tìm kiếm, phân tích file (read-only)
`Plan`	Lập kế hoạch, thiết kế kiến trúc
`general-purpose`	Mọi task khác

Ví dụ Skill hoàn chỉnh cho MangoAds

Skill: Phân tích Campaign (Marketing team)

---
name: phan-tich-campaign
description: Use when analyzing campaign performance, reviewing ads metrics,
  interpreting CTR/CPC/ROAS data, or generating campaign insights. Trigger
  when user mentions: phân tích campaign, hiệu suất quảng cáo, ROAS thấp,
  tối ưu ads, báo cáo campaign, review ads.
argument-hint: [campaign-id hoặc paste data trực tiếp]
---

## Quy trình phân tích chuẩn MangoAds

### Bước 1: Benchmark
So sánh với benchmark ngành:
- CTR Facebook Feed: 0.9–1.5% | Story: 0.5–0.9%
- CTR Google Search: 3–5% | Display: 0.1–0.3%
- ROAS tối thiểu: 3x (tùy ngành)

### Bước 2: Xác định vấn đề
Với mỗi chỉ số bất thường, trả lời:
- Chỉ số nào lệch? Lệch bao nhiêu %?
- Nguyên nhân có thể: Creative / Audience / Bid / Landing page?
- Mức độ ưu tiên: Critical / High / Medium?

### Bước 3: Action plan
Tạo bảng: | Vấn đề | Action cụ thể | Người làm | Deadline |

### Output format
- Dùng bảng cho số liệu
- Kết thúc bằng **"Quick wins"** — 3 việc làm được trong 24h

Skill: Deploy tự động (Dev — có side-effect)

---
name: deploy-staging
description: Deploy code lên môi trường staging
disable-model-invocation: true
allowed-tools: Bash(git *), Bash(npm *)
---

## Quy trình deploy staging

1. Kiểm tra working tree sạch: `git status`
2. Chạy tests: `npm test`
3. Build: `npm run build`
4. Push lên branch staging: `git push origin HEAD:staging`
5. Báo cáo kết quả và link preview

Nếu bất kỳ bước nào fail → dừng lại và báo lỗi chi tiết.

Skill này có disable-model-invocation: true vì deploy là hành động không thể hoàn tác — chỉ user mới được gọi bằng /deploy-staging.

Planning and Design — Lên kế hoạch & thiết kế

Xác định Use Case trước khi viết

Trước khi viết bất kỳ dòng nào, hãy xác định 2–3 use case cụ thể skill cần giải quyết.

Định nghĩa use case tốt

Use Case: Phân tích báo cáo campaign
Trigger: User nói "phân tích campaign", "review ads tháng này",
         "ROAS tháng 3 thấp phải làm gì"
Steps:
  1. Đọc file dữ liệu CSV / nhận data user paste vào
  2. So sánh với benchmark ngành
  3. Xác định campaign over-perform / under-perform
  4. Tạo action plan với deadline cụ thể
Result: Báo cáo phân tích + bảng action plan sẵn sàng gửi cho client

Tự hỏi trước khi viết:

User muốn đạt kết quả gì?
Task này cần bao nhiêu bước?
Cần tools gì (built-in hay MCP)?
Có domain knowledge / best practice nào cần nhúng vào?

3 loại Skill phổ biến

Loại 1: Tạo tài liệu & nội dung

Dùng cho: Tạo output nhất quán, chất lượng cao — tài liệu, slide, ads copy, báo cáo, code.

Ví dụ thực tế: Skill viet-copy, bao-cao-khach-hang, frontend-design

Kỹ thuật chính:

Nhúng style guide và brand standards vào instructions
Dùng template cố định để output luôn đúng format
Thêm quality checklist ở cuối trước khi trả kết quả
Không cần tools bên ngoài — dùng built-in capabilities của Claude

Loại 2: Workflow Automation

Dùng cho: Quy trình nhiều bước lặp lại có methodology nhất quán.

Ví dụ thực tế: Skill deploy-staging, review-pr, skill-creator

Kỹ thuật chính:

Workflow từng bước có validation gate
Template cho các cấu trúc lặp lại
Vòng lặp review và cải tiến
Error handling rõ ràng ở mỗi bước

Loại 3: MCP Enhancement

Dùng cho: Thêm workflow guidance lên trên tool access của MCP server.

Ví dụ thực tế: Skill kết hợp với Google Analytics MCP, Meta Ads MCP

Kỹ thuật chính:

Điều phối nhiều MCP calls theo đúng thứ tự
Nhúng domain expertise vào từng bước
Cung cấp context mà user thường không biết phải specify
Error handling cho các lỗi MCP phổ biến

Tiêu chí đánh giá thành công

Xác định trước khi viết — dùng để biết skill có hoạt động đúng không.

Định lượng:

Skill tự trigger trên 90% các query phù hợp
Hoàn thành workflow trong số tool calls tối thiểu
Không có failed API calls trong workflow

Định tính:

User không cần nhắc Claude bước tiếp theo phải làm gì
Workflow hoàn thành mà không cần user điều chỉnh
Kết quả nhất quán qua nhiều sessions

Testing and Iteration — Kiểm thử & cải tiến

Các mức độ testing

Skills có thể test ở nhiều mức độ tùy nhu cầu:

Manual testing trên Claude.ai — Chạy query trực tiếp, quan sát kết quả. Nhanh, không cần setup.
Scripted testing trong Claude Code — Tự động hóa test cases để validate qua nhiều lần thay đổi.
Programmatic testing qua API — Build evaluation suite chạy hệ thống với test set cố định.

Pro tip: Cách hiệu quả nhất là iterate trên một task khó cho đến khi Claude xử lý tốt, rồi extract approach đó thành skill. Sau đó mới mở rộng ra nhiều test case hơn.

1. Triggering tests

Mục tiêu: Đảm bảo skill load đúng lúc — không thiếu, không thừa.

Test cases cần có:

Skill trigger trên các query rõ ràng
Skill trigger trên các cách diễn đạt khác nhau (paraphrase)
Skill KHÔNG trigger trên topic không liên quan

Ví dụ test suite cho skill phan-tich-campaign:

Nên trigger:
- "Phân tích campaign tháng 3 giúp tôi"
- "ROAS đang thấp, phải làm sao?"
- "Review hiệu suất ads Q1 2026"

Không nên trigger:
- "Viết caption cho bài đăng Facebook"
- "Tìm hiểu về target audience"
- "Tạo báo cáo cho khách hàng" (nếu có skill riêng)

2. Functional tests

Mục tiêu: Xác nhận skill tạo ra output đúng.

Test cases cần có:

Output đúng format
Đầy đủ các phần theo yêu cầu
Edge cases được xử lý
Kết quả nhất quán khi chạy lại

Ví dụ:

Test: Phân tích campaign với data đầy đủ
Given: File CSV với 5 campaigns, đủ các cột CTR/CPC/ROAS
When: Skill thực thi
Then:
  - Có bảng so sánh benchmark
  - Có phần phân tích nguyên nhân
  - Có action plan với deadline
  - Kết thúc bằng Quick wins

3. Performance comparison

Mục tiêu: Chứng minh skill cải thiện kết quả so với không dùng skill.

Ví dụ so sánh:

Không có skill:
  - User phải giải thích lại quy trình mỗi lần
  - 10–15 lượt hỏi đáp
  - Kết quả không nhất quán giữa các lần

Có skill:
  - Workflow tự động kích hoạt
  - 1–2 câu hỏi làm rõ duy nhất
  - Kết quả nhất quán, đúng format mỗi lần

Tín hiệu cần iteration

Skill trigger quá ít (undertriggering):

Skill không load dù task phù hợp
User phải gọi thủ công bằng /tên-skill
Giải pháp: Thêm keyword vào description, bổ sung trigger phrases tiếng Việt và tiếng Anh

Skill trigger quá nhiều (overtriggering):

Skill load với các query không liên quan
User tắt skill vì annoying
Giải pháp: Thêm negative trigger, thu hẹp scope trong description

Instructions không được tuân theo:

Kết quả không nhất quán
Claude bỏ qua một số bước
Giải pháp: Rút ngắn SKILL.md, đặt thông tin quan trọng lên đầu, chuyển tài liệu chi tiết sang references/

Patterns and Troubleshooting — Các pattern & xử lý lỗi

Design Patterns

Các pattern dưới đây được đúc kết từ thực tế — đây là những cách tiếp cận hoạt động tốt, không phải template cứng nhắc.

Chọn hướng tiếp cận trước khi viết:

Problem-first: User mô tả vấn đề → skill điều phối tools đúng thứ tự. User chỉ cần nói outcome, skill lo phần còn lại.
Tool-first: User đã có tool/MCP → skill dạy Claude cách dùng tối ưu. User có access, skill cung cấp expertise.

Pattern 1: Sequential Workflow

Dùng khi: User cần quy trình nhiều bước theo thứ tự cố định.

## Workflow: Onboard Client mới

### Bước 1: Tạo workspace
Tạo thư mục project theo cấu trúc chuẩn MangoAds

### Bước 2: Setup tracking
Cài đặt UTM template và pixel tracking

### Bước 3: Tạo báo cáo template
Copy template báo cáo tháng vào thư mục client

### Bước 4: Thông báo team
Gửi Slack message vào #new-clients với thông tin client

Kỹ thuật chính:

Đánh số bước rõ ràng, có thứ tự
Mỗi bước có dependency với bước trước
Validation ở từng bước trước khi tiếp tục
Hướng dẫn rollback khi bước nào đó fail

Pattern 2: Multi-MCP Coordination

Dùng khi: Workflow cần phối hợp nhiều service/tool khác nhau.

## Workflow: Design-to-Ads handoff

### Phase 1: Export từ Figma (Figma MCP)
1. Export creative assets
2. Tạo design spec
3. Tạo asset manifest

### Phase 2: Lưu trữ (Drive MCP)
1. Tạo thư mục campaign trên Drive
2. Upload tất cả assets
3. Tạo shareable link

### Phase 3: Tạo task (Asana MCP)
1. Tạo tasks cho team ads
2. Đính kèm link assets
3. Assign cho đúng người

### Phase 4: Thông báo (Slack MCP)
1. Post tóm tắt vào #ads-team
2. Kèm link tài liệu và tasks

Kỹ thuật chính:

Phân chia phase rõ ràng theo từng service
Data passing giữa các phase
Validate trước khi chuyển phase
Centralized error handling

Dùng khi: Chất lượng output cải thiện qua nhiều vòng lặp.

## Tạo báo cáo campaign

### Draft đầu tiên
1. Đọc dữ liệu từ file CSV
2. Tạo bản thảo báo cáo
3. Lưu vào file tạm

### Kiểm tra chất lượng
Tự đánh giá:
- Có đủ 4 section bắt buộc không?
- Số liệu có được giải thích không?
- Có action plan không?

### Vòng lặp cải thiện
1. Fix từng vấn đề tìm thấy
2. Viết lại section cần sửa
3. Kiểm tra lại
4. Lặp lại đến khi đạt tiêu chuẩn

### Hoàn thiện
1. Apply format cuối cùng
2. Tạo executive summary
3. Lưu file final

Kỹ thuật chính:

Tiêu chí chất lượng rõ ràng, có thể đo được
Vòng lặp cải tiến có giới hạn (tránh loop vô tận)
Validation script nếu cần kiểm tra programmatic

Pattern 4: Context-aware Tool Selection

Dùng khi: Cùng một kết quả nhưng cần dùng tool khác nhau tùy tình huống.

## Lưu file output

### Quyết định vị trí lưu
1. Kiểm tra loại và kích thước file
2. Chọn nơi lưu phù hợp:
   - File lớn (>10MB): Google Drive
   - Tài liệu cộng tác: Notion
   - File code: GitHub
   - File tạm: local

### Thực hiện lưu
- Gọi tool tương ứng với lựa chọn trên
- Áp dụng metadata phù hợp với service
- Tạo access link nếu cần chia sẻ

### Giải thích cho user
Nói rõ tại sao chọn vị trí đó

Kỹ thuật chính:

Decision tree rõ ràng với tiêu chí cụ thể
Luôn có fallback option
Transparent về lý do lựa chọn

Pattern 5: Domain-specific Intelligence

Dùng khi: Skill cần thêm domain knowledge chuyên biệt ngoài việc chỉ gọi tools.

## Đề xuất tối ưu campaign

### Phân tích (trước khi hành động)
1. Đọc dữ liệu campaign
2. Áp dụng domain knowledge:
   - CTR < 1% trên Facebook Feed: vấn đề creative
   - CTR tốt nhưng conversion thấp: vấn đề landing page
   - CPC tăng đột biến: audience saturation
3. Đánh giá mức độ nghiêm trọng: Critical / High / Medium

### Hành động
Nếu đủ confidence:
  - Đề xuất thay đổi cụ thể với lý do
  - Estimate impact dự kiến
Nếu cần thêm data:
  - Hỏi user thêm thông tin
  - Liệt kê data còn thiếu

### Audit trail
- Ghi lại phân tích và lý do đề xuất
- Tạo báo cáo tóm tắt

Kỹ thuật chính:

Domain expertise nhúng trực tiếp vào logic (không để Claude tự suy)
Kiểm tra trước khi hành động
Ghi lại reasoning để audit sau

Troubleshooting

Skill không upload được

Lỗi: "Could not find SKILL.md"

Nguyên nhân: Tên file sai (skill.md, SKILL.MD...)
Fix: Đổi tên chính xác thành SKILL.md

Lỗi: "Invalid frontmatter"

# Sai — thiếu dấu ---
name: my-skill
description: Does things

# Sai — quote không đóng
name: my-skill
description: "Does things

# Đúng
---
name: my-skill
description: Does things
---

Lỗi: "Invalid skill name"

Nguyên nhân: Tên có dấu cách hoặc chữ hoa
Fix: Đổi sang kebab-case: my-cool-skill

Skill không tự trigger

Triệu chứng: Claude không tự dùng skill dù task phù hợp.

Checklist kiểm tra description:

Có quá chung chung không? ("Helps with ads" không đủ)
Có trigger phrases người dùng thực sự hay nói không?
Có đề cập loại file liên quan nếu cần không?

Cách fix:

Thêm nhiều trigger phrases hơn, cả tiếng Anh lẫn tiếng Việt
Thêm keyword kỹ thuật (tên công cụ, tên platform, định dạng file)

Skill trigger quá nhiều

Triệu chứng: Skill load cả khi task không liên quan.

Cách fix — thêm negative trigger vào description:

description: Phân tích campaign Facebook/Google Ads. Use for CTR, CPC,
  ROAS analysis. Do NOT use for general marketing questions or content
  creation tasks (use viet-copy skill instead).

Instructions không được tuân theo

Nguyên nhân phổ biến:

Instructions quá dài dòng — Claude bỏ qua phần ở cuối. Fix: chuyển tài liệu chi tiết sang references/, để SKILL.md ngắn gọn.
Thông tin quan trọng bị chôn vùi — Fix: đặt lên đầu, dùng heading ## QUAN TRỌNG hoặc ## CRITICAL.
Ngôn ngữ mơ hồ — Fix: thay thế bằng chỉ dẫn cụ thể có thể kiểm chứng được.

Skill chạy chậm / response kém chất lượng

Nguyên nhân: SKILL.md quá lớn, hoặc bật quá nhiều skills cùng lúc.

Cách fix:

Giữ SKILL.md dưới 5.000 từ, chuyển tài liệu sang references/
Nếu bật hơn 20-50 skills: tắt bớt những skill không dùng thường xuyên

Resources and References — Tài nguyên & tham chiếu

Checklist trước khi publish Skill

Dùng checklist này để validate skill trước và sau khi upload.

Trước khi bắt đầu viết

Đã xác định 2–3 use case cụ thể
Đã xác định cần tools gì (built-in hay MCP)
Đã chọn đúng loại skill (Document creation / Workflow / MCP Enhancement)
Đã lên kế hoạch cấu trúc thư mục

Trong quá trình viết

Trước khi upload

Test trigger trên các query rõ ràng
Test trigger trên các cách nói khác (paraphrase)
Xác nhận skill KHÔNG trigger trên topic không liên quan
Functional tests pass
Tool integration hoạt động (nếu có)

Sau khi upload

Test trong hội thoại thực tế
Theo dõi dấu hiệu under/over-triggering
Thu thập feedback từ người dùng
Iterate trên description và instructions
Cập nhật version trong metadata khi thay đổi lớn

Quản lý Skills

# Xem tất cả skills đã cài
ls ~/.claude/skills/

# Xem nội dung một skill
cat ~/.claude/skills/tên-skill.md

# Xóa skill
rm ~/.claude/skills/tên-skill.md

👉 Đọc file tiếp theo: 06-agents-va-sdk.md

Fundamentals — Kiến thức nền tảng​

Skills là gì?​

Nguyên lý thiết kế của Skills​

1. Progressive Disclosure — Tải từng lớp khi cần​

2. Composability — Nhiều Skills chạy cùng lúc​

3. Portability — Chạy được trên mọi nền tảng​

Vị trí lưu trữ Skills​

Cấu trúc của một Skill​

Dạng file đơn giản (phổ biến nhất)​

Dạng thư mục (cho skill phức tạp)​

Quy tắc đặt tên bắt buộc​

Cấu trúc bên trong một file Skill​

Phần 1: Frontmatter (YAML giữa hai dấu ---)​

Phần 2: Body (nội dung hướng dẫn)​

Rules: Claude kích hoạt Skill khi nào?​

3 chế độ kích hoạt​

Viết description hiệu quả​

Tính năng nâng cao​

Argument — Truyền tham số vào Skill​

Dynamic Context — Chạy lệnh trước khi Skill khởi động​

allowed-tools — Cấp quyền tool tự động cho Skill​

context: fork — Chạy Skill trong Subagent độc lập​

Ví dụ Skill hoàn chỉnh cho MangoAds​

Skill: Phân tích Campaign (Marketing team)​

Skill: Deploy tự động (Dev — có side-effect)​

Planning and Design — Lên kế hoạch & thiết kế​

Xác định Use Case trước khi viết​

Định nghĩa use case tốt​

3 loại Skill phổ biến​

Loại 1: Tạo tài liệu & nội dung​

Loại 2: Workflow Automation​

Loại 3: MCP Enhancement​

Tiêu chí đánh giá thành công​

Testing and Iteration — Kiểm thử & cải tiến​

Các mức độ testing​

1. Triggering tests​

2. Functional tests​

3. Performance comparison​

Tín hiệu cần iteration​

Patterns and Troubleshooting — Các pattern & xử lý lỗi​

Design Patterns​

Pattern 1: Sequential Workflow​

Pattern 2: Multi-MCP Coordination​

Pattern 3: Iterative Refinement​

Pattern 4: Context-aware Tool Selection​

Pattern 5: Domain-specific Intelligence​

Troubleshooting​

Skill không upload được​

Skill không tự trigger​

Skill trigger quá nhiều​

Instructions không được tuân theo​

Skill chạy chậm / response kém chất lượng​

Resources and References — Tài nguyên & tham chiếu​

Checklist trước khi publish Skill​

Trước khi bắt đầu viết​

Trong quá trình viết​

Trước khi upload​

Sau khi upload​

Quản lý Skills​

Tiếp theo​

Fundamentals — Kiến thức nền tảng

Skills là gì?

Nguyên lý thiết kế của Skills

1. Progressive Disclosure — Tải từng lớp khi cần

2. Composability — Nhiều Skills chạy cùng lúc

3. Portability — Chạy được trên mọi nền tảng

Vị trí lưu trữ Skills

Cấu trúc của một Skill

Dạng file đơn giản (phổ biến nhất)

Dạng thư mục (cho skill phức tạp)

Quy tắc đặt tên bắt buộc

Cấu trúc bên trong một file Skill

Phần 1: Frontmatter (YAML giữa hai dấu `---`)

Phần 2: Body (nội dung hướng dẫn)

Rules: Claude kích hoạt Skill khi nào?

3 chế độ kích hoạt

Viết `description` hiệu quả

Tính năng nâng cao

Argument — Truyền tham số vào Skill

Dynamic Context — Chạy lệnh trước khi Skill khởi động

`allowed-tools` — Cấp quyền tool tự động cho Skill

`context: fork` — Chạy Skill trong Subagent độc lập

Ví dụ Skill hoàn chỉnh cho MangoAds

Skill: Phân tích Campaign (Marketing team)

Skill: Deploy tự động (Dev — có side-effect)

Planning and Design — Lên kế hoạch & thiết kế

Xác định Use Case trước khi viết

Định nghĩa use case tốt

3 loại Skill phổ biến

Loại 1: Tạo tài liệu & nội dung

Loại 2: Workflow Automation

Loại 3: MCP Enhancement

Tiêu chí đánh giá thành công

Testing and Iteration — Kiểm thử & cải tiến

Các mức độ testing

1. Triggering tests

2. Functional tests

3. Performance comparison

Tín hiệu cần iteration

Patterns and Troubleshooting — Các pattern & xử lý lỗi

Design Patterns

Pattern 1: Sequential Workflow

Pattern 2: Multi-MCP Coordination

Pattern 3: Iterative Refinement

Pattern 4: Context-aware Tool Selection

Pattern 5: Domain-specific Intelligence

Troubleshooting

Skill không upload được

Skill không tự trigger

Skill trigger quá nhiều

Instructions không được tuân theo

Skill chạy chậm / response kém chất lượng

Resources and References — Tài nguyên & tham chiếu

Checklist trước khi publish Skill

Trước khi bắt đầu viết

Trong quá trình viết

Trước khi upload

Sau khi upload

Quản lý Skills

Tiếp theo