Xây dựng Skills cho Claude — Phần 1: Giới thiệu và Kiến trúc cơ bản

Dịch và biên soạn từ "The Complete Guide to Building Skills for Claude" của Anthropic.

Skill là một trong những cách mạnh mẽ nhất để tuỳ biến Claude theo nhu cầu cụ thể của bạn. Thay vì phải giải thích lại quy trình, sở thích và kiến thức chuyên môn trong mỗi cuộc trò chuyện, bạn chỉ cần "dạy" Claude một lần và hưởng lợi mãi mãi. Bài viết này mở đầu serial 6 phần, giúp bạn hiểu rõ nền tảng trước khi bắt tay vào xây dựng.

Skill là gì?

Skill là một tập hợp các chỉ dẫn (instructions) được đóng gói dưới dạng một thư mục đơn giản, dạy Claude cách xử lý các tác vụ hoặc quy trình cụ thể. Về bản chất, một skill bao gồm:

• SKILL.md (bắt buộc): File hướng dẫn chính, viết bằng Markdown với YAML frontmatter
• scripts/ (tuỳ chọn): Mã thực thi như Python, Bash
• references/ (tuỳ chọn): Tài liệu tham khảo được tải khi cần
• assets/ (tuỳ chọn): Template, font, icon dùng trong output

Nói đơn giản: skill giống như một "sổ tay hướng dẫn" mà bạn trao cho Claude. Khi người dùng yêu cầu một việc phù hợp, Claude sẽ tự động mở đúng sổ tay và làm theo.

Tại sao cần Skills?

Skills đặc biệt hữu ích khi bạn có các quy trình lặp đi lặp lại:

• Tạo giao diện frontend từ design specs
• Nghiên cứu với phương pháp luận nhất quán
• Viết tài liệu theo đúng style guide của team
• Điều phối các quy trình nhiều bước phức tạp

Ví dụ thực tế tại Việt Nam: Nếu bạn là một agency làm web cho nhiều khách hàng, bạn có thể tạo skill giúp Claude tự động tạo cấu trúc dự án Shopify theo chuẩn của công ty, bao gồm cả template Liquid, cấu trúc thư mục, và checklist QA. Mỗi dự án mới sẽ bắt đầu nhanh hơn và đồng nhất hơn.

Ai nên đọc serial này?

• Developer muốn Claude tuân theo quy trình cụ thể một cách nhất quán
• Power user muốn chuẩn hoá cách Claude làm việc
• Team leader muốn đồng bộ cách sử dụng Claude trong tổ chức

Kết quả mong đợi: sau khi đọc xong serial 6 phần, bạn có thể xây dựng một skill hoàn chỉnh trong khoảng 15-30 phút bằng skill-creator.

Nguyên tắc thiết kế cốt lõi: Progressive Disclosure

Đây là nguyên tắc quan trọng nhất cần hiểu. Skills sử dụng hệ thống 3 cấp độ để tối ưu hoá token:

Cấp 1: YAML Frontmatter (luôn được tải)

Phần frontmatter luôn nằm trong system prompt của Claude. Nó cung cấp vừa đủ thông tin để Claude biết khi nào nên kích hoạt skill mà không cần tải toàn bộ nội dung.

---
name: project-setup
description: Tạo cấu trúc dự án web theo chuẩn công ty. Dùng khi người dùng nói "tạo dự án mới", "setup project", hoặc "khởi tạo workspace".
---

Cấp 2: Nội dung SKILL.md (tải khi cần)

Phần thân của file SKILL.md chỉ được tải khi Claude nhận thấy skill phù hợp với tác vụ hiện tại. Đây là nơi chứa toàn bộ hướng dẫn chi tiết.

Cấp 3: File liên kết (tải theo yêu cầu)

Các file trong thư mục references/, scripts/, assets/ chỉ được Claude truy cập khi thực sự cần thiết. Điều này giữ cho context window không bị quá tải.

Cơ chế này giống như cách bạn tra cứu sách: bạn đọc mục lục trước (cấp 1), lật đến chương cần đọc (cấp 2), và chỉ mở phụ lục khi cần tra chi tiết (cấp 3).

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

your-skill-name/
├── SKILL.md          # Bắt buộc - file hướng dẫn chính
├── scripts/          # Tuỳ chọn - mã thực thi
│   ├── process_data.py
│   └── validate.sh
├── references/       # Tuỳ chọn - tài liệu tham khảo
│   ├── api-guide.md
│   └── examples/
└── assets/           # Tuỳ chọn - template, tài nguyên
    └── report-template.md

Quy tắc đặt tên quan trọng

• SKILL.md phải viết đúng chính tả, phân biệt hoa thường. Không chấp nhận skill.md, SKILL.MD, hay bất kỳ biến thể nào
• Tên thư mục phải dùng kebab-case: notion-project-setup
• Không dùng dấu cách: Notion Project Setup (sai)
• Không dùng gạch dưới: notion_project_setup (sai)
• Không viết hoa: NotionProjectSetup (sai)
• Không đặt file README.md trong thư mục skill

YAML Frontmatter: Phần quan trọng nhất

YAML frontmatter là cách Claude quyết định có nên tải skill hay không. Đây là phần bạn cần đầu tư nhiều nhất.

Định dạng tối thiểu

---
name: your-skill-name
description: Mô tả skill làm gì. Dùng khi người dùng yêu cầu [cụm từ cụ thể].
---

Các trường bắt buộc

• name (bắt buộc): Dạng kebab-case, không dấu cách, không viết hoa, nên trùng tên thư mục
• description (bắt buộc): Phải bao gồm CẢ hai thông tin: skill làm gì VÀ khi nào nên dùng. Dưới 1024 ký tự. Không chứa thẻ XML

Các trường tuỳ chọn

• license: Nếu phát hành mã nguồn mở (MIT, Apache-2.0)
• compatibility: Yêu cầu môi trường (1-500 ký tự)
• allowed-tools: Giới hạn quyền truy cập công cụ
• metadata: Các cặp key-value tuỳ chỉnh như author, version, mcp-server

Hạn chế bảo mật

• Cấm dùng dấu ngoặc nhọn XML (< >) trong frontmatter
• Không được đặt tên skill chứa "claude" hoặc "anthropic" (từ khoá dành riêng)

Lý do: Frontmatter xuất hiện trong system prompt của Claude. Nội dung độc hại có thể inject các chỉ dẫn không mong muốn.

Skills + MCP: Mối quan hệ bổ sung

Nếu bạn đã biết về MCP (Model Context Protocol), bạn sẽ thấy Skills và MCP là hai mảnh ghép hoàn hảo. Anthropic dùng phép ẩn dụ nhà bếp rất hay:

• MCP là gian bếp chuyên nghiệp: cung cấp quyền truy cập công cụ, nguyên liệu và thiết bị (kết nối với Notion, Asana, Linear, GitHub...)
• Skills là công thức nấu ăn: hướng dẫn từng bước cách tạo ra thứ gì đó có giá trị từ những công cụ và nguyên liệu đó

MCP (Kết nối)	Skills (Kiến thức)
Kết nối Claude với dịch vụ của bạn	Dạy Claude cách sử dụng dịch vụ hiệu quả
Cung cấp truy cập dữ liệu real-time và gọi công cụ	Nắm bắt quy trình và best practices
Claude CÓ THỂ làm gì	Claude NÊN làm như thế nào

Không có Skills, điều gì xảy ra?

• Người dùng kết nối MCP nhưng không biết bắt đầu từ đâu
• Mỗi cuộc trò chuyện phải bắt đầu lại từ đầu
• Kết quả không nhất quán vì mỗi người prompt khác nhau
• Người dùng đổ lỗi cho connector trong khi vấn đề thực sự là thiếu hướng dẫn quy trình

Có Skills, bạn được gì?

• Quy trình được xây dựng sẵn, tự động kích hoạt khi cần
• Sử dụng công cụ nhất quán và đáng tin cậy
• Best practices được nhúng vào mọi tương tác
• Đường cong học tập thấp hơn cho integration của bạn

Composability: Kết hợp nhiều Skills

Claude có thể tải nhiều skill đồng thời. Khi thiết kế skill, hãy đảm bảo nó hoạt động tốt cùng các skill khác, không giả định rằng nó là khả năng duy nhất có sẵn.

Ví dụ: Bạn có thể có skill "tạo dự án" và skill "review code" cùng hoạt động. Khi người dùng nói "tạo dự án mới và review cấu trúc code", cả hai skill sẽ phối hợp liền mạch.

Portability: Viết một lần, chạy mọi nơi

Skills hoạt động giống nhau trên Claude.ai, Claude Code và API. Bạn tạo skill một lần và nó chạy trên tất cả các nền tảng mà không cần sửa đổi, miễn là môi trường hỗ trợ các dependency mà skill yêu cầu.

Anthropic đã công bố Agent Skills như một tiêu chuẩn mở. Giống MCP, họ tin rằng skills nên portable giữa các công cụ và nền tảng khác nhau.

Hai lộ trình học trong serial này

Tuỳ theo mục tiêu, bạn có thể chọn lộ trình phù hợp:

• Xây dựng skill độc lập (không MCP): Tập trung vào Phần 1-3 (Cơ bản, Thiết kế, Testing)
• Tăng cường MCP integration: Đọc thêm phần "Skills + MCP" trong mỗi bài và Phần 5 (Patterns)

Cả hai lộ trình đều chia sẻ chung yêu cầu kỹ thuật. Bạn chọn phần nào phù hợp với use case của mình.

Tổng kết Phần 1

Bạn đã nắm được:

• Skill là gì và tại sao cần skill
• Nguyên tắc Progressive Disclosure 3 cấp
• Cấu trúc thư mục và quy tắc đặt tên
• YAML frontmatter cơ bản
• Mối quan hệ Skills + MCP (phép ẩn dụ nhà bếp)
• Composability và Portability

Trong Phần 2, chúng ta sẽ đi sâu vào cách thiết kế và lập kế hoạch skill: bắt đầu từ use case, phân loại skill, xác định tiêu chí thành công, và viết description chuẩn.