Tạo Custom Skill: Package kiến thức thành markdown — Bí quyết để agent nhớ 'nghề' của bạn

Bạn đã từng ngồi mở chat mới với Claude Code và phải giải thích lại từ đầu: "Nhớ nhé, project này dùng TypeScript strict mode, styling theo BEM, và luôn chạy test trước khi commit"? Đó là thuế chuyển giao bối cảnh (context establishment tax) — bạn trả tiền inference không chỉ cho công việc, mà còn cho việc tái lập lại qui trình đã nói 100 lần. Custom Skill (SKILL.md) sinh ra để xóa bỏ chi phí lặp lại này, biến AI từ "tư vấn viên mỗi ngày mới" thành "nhân viên có sổ tay làm việc vĩnh viễn" — chỉ cần một lần đóng gói, dùng mãi mãi qua mọi session.

Vấn đề

Khi làm việc với AI agent ở Level 0, bạn sớm nhận ra hiện tượng "Groundhog Day": mỗi lần bắt đầu context mới, bạn phải briefing lại toàn bộ qui trình. "Project này dùng FastAPI hay Flask? Coding standard là gì? Có cần viết test không?"

Cách tiếp cận cũ — dùng system prompt dài 5.000 tokens — có ba lỗ hổng:

1. Tính tạm thời: System prompt biến mất khi chat kết thúc. Không có cơ chế persist, bạn phải mang "gánh nặng nhận thức" (cognitive load) để nhớ rõ agent cần biết gì.

2. Context pollution: Nhồi nhét 10 qui trình khác nhau vào một prompt khiến agent bị "ngộp". Attention mechanism của LLM phân tán xác suất quá mỏng, dẫn đến hiện tượng "lost in the middle" — bỏ qua ràng buộc quan trọng nằm giữa đoạn văn bản.

3. Lãng phí token: Mỗi turn đều phải truyền lại toàn bộ qui trình (5.000 tokens) chỉ để agent thực hiện một task nhỏ (500 tokens output). Chi phí tích lũy nhanh chóng trong production.

Ý tưởng cốt lõi

Cái hay của Custom Skill là Inversion of Control cho Prompting. Thay vì bạn (người dùng) phải nhớ "agent cần biết gì", bạn viết một lần employee handbook (sổ tay nhân viên) và để agent tự tra cứu khi cần.

Đây là kiến trúc Progressive Disclosure ba tầng — chỉ load những gì cần thiết, khi cần thiết:

Tầng 1: Metadata là Router (The Job Description)

YAML frontmatter đóng vai trò "mô tả công việc dán trên cửa phòng":

• name: Tối đa 64 ký tự, định danh duy nhất (vd: data-analysis-vn)
• description: Tối đa 200 ký tự — đây là "routing hash" tín hiệu cao (high-signal routing hash)

Claude chỉ quét phần này (rẻ tiền về token) để quyết định có nên load skill hay không. 200 ký tự ép buộc bạn viết cực kỳ súc tích về mục đích sử dụng, không phải cách thực hiện.

---
name: data-analysis-vn
description: "Phân tích CSV tiếng Việt: làm sạch dữ liệu bẩn, xử lý missing value, phát hiện outlier, vẽ biểu đồ matplotlib. Dùng khi user đưa file .csv hoặc nói 'phân tích dữ liệu', 'làm sạch data'."
---

Tầng 2: Body là Training Manual

Phần markdown chỉ load khi description match với intent. Đây là nơi chứa:

• Workflow bắt buộc (các bước tuần tự)
• Negative constraints (cấm kỵ: KHÔNG BAO GIỜ xóa cột mà không confirm 2 lần)
• Guardrails kỹ thuật (encoding UTF-8, backup raw data trước transform)

## Quy trình bắt buộc
1. **Backup**: Copy raw file vào `backup_{{timestamp}}/` trước mọi thao tác
2. **Encoding Check**: Kiểm tra UTF-8 vs UTF-8-BOM, xử lý dấu tiếng Việt bị mã hóa sai (á → á)
3. **Profiling**: Hiển thị `.info()` và `.describe()` trước khi làm sạch
4. **Cleaning**: Missing numeric → median; categorical → mode; never drop rows >5% without asking
5. **Visualization**: Mặc định vẽ histogram, boxplot, correlation heatmap

## Ràng buộc tuyệt đối
- **KHÔNG BAO GIỜ** dùng `inplace=True` trong pandas mà không có checkpoint
- **KHÔNG BAO GIỜ** xóa cột chỉ vì "có vẻ không cần thiết"
- Nếu file > 100MB, sampling 10% trước khi full processing để tránh OOM

Tầng 3: Assets là Tool Chest (Lazy Loading)

Folder kèm theo skill có thể chứa:

• scripts/: Python/JS utilities tái sử dụng
• references/: Schema mẫu, template báo cáo
• examples/: Ví dụ input/output điển hình

Chỉ load khi skill đang chạy thực sự cần đến (ví dụ: gọi scripts/clean_vietnamese_text.py).

Cơ chế Đóng gói & Phân phối

Skill được đóng gói thành ZIP với folder root trùng tên skill:

data-analysis-vn.zip
└── data-analysis-vn/          ← Tên folder phải khớp tên skill
    ├── SKILL.md
    └── scripts/
        └── clean_vi.py

• Global: ~/.claude/skills/ — dùng cho mọi project (vd: qui trình chuẩn hóa dữ liệu)
• Project-level: .claude/skills/ trong repo — chỉ áp dụng cho codebase cụ thể (vd: qui trình build microservice nội bộ)

Auto-invocation: Khác với MCP hay Tools cần @mention, Skill được trigger tự động qua semantic matching của description. Agent tự quyết định "à, user đang nói về CSV → match với skill data-analysis-vn" mà không cần bạn gõ lệnh.

Tại sao nó hoạt động

Bản chất của Progressive Disclosure là Attention Hygiene (vệ sinh attention). LLM không có "ổ cứng" trong working memory — chúng có một canvas attention hữu hạn.

Tại sao giới hạn 200 ký tự là "đòn bẩy" thiết kế thông minh?

Con số 200 ép buộc bạn nén mô tả thành semantic vector đặc trưng (distinctive embedding). Thay vì mô tả dài 500 tokens bị "trôi" trong không gian vector, 200 ký tự buộc bạn chọn từ khóa độc nhất ("phân tích CSV tiếng Việt" thay vì "xử lý data"). Kết quả: pattern matching giữa user intent và skill chính xác hơn 40% so với description mơ hồ dài dòng (theo nguyên lý từ SkillsBench, 2025).

Tách biệt Routing vs Execution

Giống như bệnh viện hiện đại: bác sĩ không mang 50 quyển sách y khoa đi khám bệnh. Họ chỉ mang thẻ chuyên khoa (metadata) — khi nào chắc chắn cần đến khoa Tim mạch, họ mới lấy sách Cardiology Advanced ra đọc.

Điều này giải quyết vấn đề context interference: khi agent chỉ load một skill duy nhất, toàn bộ context window (200k tokens của Claude 3.5) dồn vào qui trình đó, thay vì phải "cân bằng" giữa 10 qui trình khác nhau.

So sánh với cách tiếp cận cũ

Ý nghĩa thực tế

Câu chuyện thực tế: Một developer trên Reddit báo cáo xây dựng pipeline 15 skill liên kết để sản xuất sách — từ "nghiên cứu outline" → "viết chương" → "fact-check" → "format LaTeX". Thay vì 30 phút briefing cho mỗi chương, anh ấy chỉ gõ "Viết chương 3 theo outline đã duyệt" và agent tự kích hoạt chuỗi 15 skill, tự động handoff qua các phase.

Benchmark: Giảm thiểu 90% thời gian "setup scaffolding" — từ 30 phút xuống còn một câu lệnh đơn giản.

Ai đang dùng:

• Claude Code power users: Xây dựng thư viện skill cho React Native, Python data science, hoặc qui trình CI/CD nội bộ
• GitBook: Dùng skill để tạo documentation agent tự động cập nhật
• Doanh nghiệp SME Việt Nam: Đóng gói qui trình "làm sạch hóa đơn VietQR" hoặc "tạo báo cáo thuế" thành skill tái sử dụng cho team kế toán

Hạn chế — Skill KHÔNG làm được gì?:

• Bootstrap problem: Claude "không giỏi viết skill cho chính nó" (theo cộng đồng). Bạn cần một skill meta ("skill-developer") để viết các skill khác hiệu quả.
• Giới hạn mô tả: 200 ký tự có thể gây mơ hồ nếu domain phức tạp (vd: phân biệt "financial audit" vs "compliance audit").
• Packaging friction: Cấu trúc ZIP phải chính xác (folder root trùng tên skill). Lỗi phổ biến: zip các file loose thay vì folder, dẫn đến skill không load được.
• Code execution requirement: Các executable bundles cần bật sandboxing, không chạy được trên API-only deployments.

Đào sâu hơn

Tài liệu chính thức:

• Anthropic Claude Help Center: How to create custom skills — Spec chính thức về YAML frontmatter và giới hạn ký tự.

Bài liên quan TroiSinh:

Đọc tiếp:

Mở rộng:

• GitBook: skill.md explained — Pattern documentation cho AI agents từ góc độ technical writing.
• Reddit: I built 15 custom skills for Claude Code — Case study thực tế về book production pipeline.