Skill Frontmatter: 4 trường metadata giúp Claude tự động 'hiểu' ý định

Hiểu sâu 4 trường YAML quyết định khi nào Skill tự động chạy. Viết description để Claude nhận ra ý định, tối ưu autoInvoke cho workflow hands-free.

Định nghĩa

YAML frontmatter trong Skills là phần metadata khai báo ở đầu file SKILL.md, đóng vai trò như "bộ não điều phối" giúp Claude quyết định khi nào nên tự động gọi một capability thay vì chờ bạn gõ lệnh thủ công. Đây là cơ chế chuyển đổi từ manual invocation (gõ /) sang auto-invocation (Claude tự hiểu ý định).

Giải thích chi tiết

`name`: Định danh máy và lệnh gọi

Trường name là định danh kỹ thuật (machine identifier) dùng để gọi Skill qua slash command. Quy tắc bắt buộc:

Dùng lowercase-kebab-case (ví dụ: security-audit, deploy-prod, fix-lint)
Phải unique trong scope (global ~/.claude/skills/ hoặc project-local .claude/skills/)
Không chứa khoảng trắng hay ký tự đặc biệt

Khi khai báo name: deploy-staging, bạn có thể gọi thủ công bằng /deploy-staging bất kỳ lúc nào.

`description`: Bộ lọc ngữ nghĩa (Semantic Router)

Đây là trường quan trọng nhất nhưng dễ hiểu nhầm nhất. description không phải documentation cho người đọc — nó là logic thực thi (executable logic) được inject vào system prompt của Claude.

Claude dùng description để semantic matching: so sánh ý định của bạn (trong câu hỏi) với mô tả này để quyết định "có nên gọi Skill này không?".

Cấu trúc tối ưu:

description: "Hành động cụ thể. Kích hoạt khi người dùng hỏi về X, Y, hoặc Z."

Ví dụ tốt:

description: "Extract text from PDF and summarize key points. Use when users ask to process PDF files, read scanned documents, or analyze PDF content."

Ví dụ xấu (sẽ không bao giờ trigger):

description: "PDF tools"

Ràng buộc kỹ thuật nghiêm ngặt:

Tối đa khoảng 200 ký tự (không có tài liệu chính thức, nhưng dài quá sự bị cắt trong context)
Phải là single-line: Không được dùng folded style (>) hoặc literal block (|) của YAML
Parser của Claude dùng regex-based extractor thay vì YAML parser đầy đủ. Nếu bạn dùng Prettier với proseWrap: true, nó sẽ tự động wrap description thành multiline → Skill bị silently ignore (không discover được mà không báo lỗi)

`autoInvoke`: Trigger tự động từ ngôn ngữ tự nhiên

autoInvoke là mảng các cụm từ trigger (string array). Khi bạn nói đúng cụm từ này trong conversation, Claude sẽ tự động gọi Skill mà không cần bạn gõ /.

Ví dụ:

autoInvoke:
  - "that worked"
  - "problem solved"
  - "finally fixed"

Khi bạn nói "Great, that worked!" sau khi debug xong, Skill post-debug-report có thể tự động chạy để ghi lại solution vào knowledge base.

Lưu ý: autoInvoke thường đi kèm với effort để tránh trigger trên những việc tầm thường.

`effort`: Kiểm soát độ phức tạp (Complexity Gate)

Trường effort (thường implement qua comment trong YAML hoặc logic gate trong body) là bộ lọc ngầm để ngăn Skill auto-invoke trên những task quá đơn giản.

Cơ chế: Claude kiểm tra conversation history trước khi auto-invoke. Nếu detect dấu hiệu "struggle" (ví dụ: nhiều lần thử lỗi, stack trace dài, thời gian debug > 5 phút) → đánh dấu là "non-trivial" và cho phép auto-invoke. Nếu chỉ là sửa typo đơn giản → block.

Ví dụ trong YAML:

# effort: high (only invoke on non-trivial debugging sessions)
name: deep-debug
autoInvoke:
  - "finally"

Điều này ngăn việc Skill ghi lại "tài liệu" cho mỗi lần sửa lỗi chính tả, nhưng vẫn capture những session debug phức tạp đáng học hỏi.

Ví dụ thực tế

Skill `/deploy` tự động release lên staging

Bạn tạo Skill để deploy lên môi trường staging của dự án thương mại điện tử kiểu Shopee khi code đã pass test:

---
name: deploy-staging
description: "Deploy current branch to staging environment via Docker Compose. Use when user mentions deploy, release to staging, or push preview."
autoInvoke:
  - "deploy now"
  - "push to staging"
---

Khi bạn nói "Okay, deploy now" sau khi review code, Claude tự động chạy docker-compose up và report kết quả, không cần bạn nhớ lệnh cụ thể hay SSH vào server thủ công.

Skill `/test` chỉ kích hoạt khi debug phức tạp

Skill này chỉ chạy tự động khi bạn vừa trải qua session debug nghiêm trọng (ví dụ: fix bug thanh toán VietQR mất 20 phút với 5 lần thử lỗi):

---
name: regression-test
description: "Generate regression tests from recent debugging session. Use when user fixed a complex bug and needs test coverage."
autoInvoke:
  - "finally fixed"
  - "that was hard"
# effort: high - implicit gate
---

Nếu bạn chỉ sửa lỗi thiếu dấu chấm phẩy và nói "done", Skill không kích hoạt. Nhưng nếu bạn vừa debug liên tục và nói "finally fixed", Skill tự động mở ra, đọc git diff, và viết test case bao phủ lỗi vừa fix.

Phân biệt Skill nhờ description chính xác

Giả sử bạn có 2 Skill: một để viết API docs cho tích hợp ZaloPay, một để viết user guide cho người bán hàng. Nếu cả hai đều có description mơ hồ như "Write documentation", Claude sẽ confused và gọi sai hoặc không gọi.

Cách fix:

# api-docs.md
name: api-docs
description: "Generate OpenAPI/Swagger documentation from code comments and function signatures. Use when user asks to document APIs, payment endpoints, or technical interfaces."

# user-guide.md
name: user-guide
description: "Write end-user facing documentation, tutorials, or README for product features. Use when user asks to explain how to use the seller dashboard, create user manual, or write getting-started guide."

Giờ khi bạn nói "document the payment callback endpoint", Claude chọn api-docs. Khi bạn nói "write a guide for new sellers", Claude chọn user-guide.

Ứng dụng

Developer solo muốn "vibe coding" hands-free Dùng autoInvoke để tạo luồng làm việc liền mạch. Ví dụ: nói "ship it" → tự động chạy test → nếu pass thì commit → push → tạo PR. Không cần chạm bàn phím ngoài việc nói ý định.

Team lead chuẩn hóa workflow Tạo các Skill với description rõ ràng để team member mới không cần nhớ cú pháp. Họ chỉ cần mô tả công việc bằng ngôn ngữ tự nhiên, Claude sẽ route đúng Skill (như một "internal Google" cho quy trình làm việc).

Người mới tránh cognitive overload Thay vì phải nhớ 20 lệnh slash command khác nhau, người mới chỉ cần đọc danh sách Skill trong .claude/skills/ và hiểu chúng được trigger khi nào nhờ description. Hệ thống tự động gợi ý đúng lúc.

So sánh

Đặc điểm	YAML Frontmatter trong Skills	Frontmatter trong Jekyll/Hugo	Function Signature trong Code
Mục đích	Routing logic (khi nào chạy)	Static metadata (title, date)	Định nghĩa interface
Ngôn ngữ	YAML + Natural language	YAML	Programming language syntax
Tính thực thi	Có — Claude đọc để quyết định	Không — chỉ để render	Có — compiler/linker dùng
Động lực trigger	Declarative (model tự quyết)	Static (được truy vấn)	Imperative (explicit call)
Lỗi cú pháp	Silent ignore (khó debug)	Build error rõ ràng	Compile-time error

Kết luận: Frontmatter trong Skills là sự kết hợp giữa metadata và code. Nó giống như bạn viết một hàm should_run() bằng ngôn ngữ tự nhiên trong YAML, và Claude thực thi logic đó mỗi lần bạn nói chuyện.