Viết Agent Skill chuẩn Anthropic: mô tả đúng, dưới 500 dòng, eval trước

Viết một skill rất dễ: một file SKILL.md với tên và mô tả. Viết một skill được Claude dùng đúng lúc và làm đúng việc thì khó hơn nhiều. Skill phổ biến nhất hay gặp hai lỗi: mô tả mơ hồ nên Claude không bao giờ gọi, hoặc thân bài dài lê thê giải thích những điều Claude đã biết, tốn context mỗi lần chạy. Anthropic có hẳn một trang Skill authoring best practices; bài này tóm tắt các nguyên tắc thực dụng nhất, kèm checklist trước khi chia sẻ skill cho team.

Nguyên tắc 1: ngắn gọn, mặc định Claude đã giỏi

Khi khởi động, chỉ tên và mô tả của mọi skill được nạp sẵn. SKILL.md được đọc khi skill liên quan, file phụ chỉ đọc khi cần. Nhưng một khi đã nạp, mỗi token của skill cạnh tranh với lịch sử hội thoại. Với từng đoạn, hãy hỏi: "Claude có thực sự cần lời giải thích này không?". Ví dụ trong tài liệu: đoạn hướng dẫn trích text PDF bản ngắn khoảng 50 token (chỉ nêu thư viện và 4 dòng code) hiệu quả hơn bản 150 token giải thích PDF là gì.

Nguyên tắc 2: chọn đúng "độ tự do"

Hình ảnh dễ nhớ: cây cầu hẹp hai bên vực thì cần lan can; cánh đồng trống thì chỉ cần chỉ hướng.

Nguyên tắc 3: tên và mô tả quyết định skill có được gọi không

• name: tối đa 64 ký tự, chỉ chữ thường, số, gạch nối; không chứa "anthropic", "claude". Nên dùng dạng V-ing: processing-pdfs, analyzing-spreadsheets. Tránh helper, utils.
• description: tối đa 1.024 ký tự, nói cả làm gì và khi nào dùng, kèm từ khoá người dùng hay gõ.
• Luôn viết ở ngôi thứ ba ("Processes Excel files…"), vì mô tả được chèn vào system prompt.

description: Generate descriptive commit messages by analyzing git diffs.
  Use when the user asks for help writing commit messages or reviewing
  staged changes.

Nguyên tắc 4: progressive disclosure

• Thân SKILL.md dưới 500 dòng; dài hơn thì tách file.
• SKILL.md đóng vai mục lục: "Điền form: xem FORMS.md; API: xem REFERENCE.md".
• Tham chiếu chỉ một cấp từ SKILL.md. File A trỏ sang B rồi trỏ sang C thì Claude có thể chỉ đọc lướt (head) và bỏ sót.
• File tham chiếu trên 100 dòng nên có mục lục ở đầu.
• Chia theo miền: reference/finance.md, reference/sales.md… hỏi về doanh thu thì chỉ đọc file finance.

Nguyên tắc 5: workflow, checklist và vòng phản hồi

Với việc nhiều bước, cho Claude một checklist để copy vào câu trả lời và đánh dấu dần. Với việc quan trọng, thêm vòng "chạy validator → sửa lỗi → chạy lại", chỉ đi tiếp khi validate pass. Script tiện ích tốt hơn để Claude tự viết code: ổn định hơn, và chỉ output của script tốn token, không phải nội dung script.

Nguyên tắc 6: eval trước, viết sau

1. Cho Claude làm task thật không có skill, ghi lại chỗ nó sai.
2. Viết 3 tình huống kiểm tra nhắm vào đúng các lỗi đó, đo baseline.
3. Viết lượng hướng dẫn tối thiểu để qua bài kiểm tra, rồi lặp lại.

Mẹo hay: dùng "Claude A" để cùng bạn viết skill, "Claude B" (phiên mới có skill) để chạy task thật, mang quan sát từ B về cho A sửa. Test với mọi model bạn sẽ dùng: thứ Opus hiểu ngay có thể chưa đủ rõ cho Haiku.

Lỗi thường gặp

• Đường dẫn kiểu Windows (scripts\helper.py), luôn dùng /.
• Đưa quá nhiều lựa chọn ("dùng pypdf, hoặc pdfplumber, hoặc…"); hãy chọn một mặc định kèm một lối thoát.
• Thông tin theo thời gian ("trước tháng 8 dùng API cũ"); chuyển vào mục "pattern cũ".
• Thuật ngữ không nhất quán, "hằng số ma thuật" không giải thích trong script.

Áp dụng thế nào?

• Dev: Mở các skill đang có, sửa mô tả theo công thức "làm gì + khi nào dùng + từ khoá", cắt mọi đoạn giải thích kiến thức phổ thông.
• Tech Lead: Đặt checklist review skill như review code: mô tả, độ dài, tham chiếu một cấp, có ít nhất 3 eval.
• PM: Biến quy trình lặp lại (viết PRD, tổng hợp feedback) thành skill bằng cách làm cùng Claude một lần rồi nhờ nó "đóng gói pattern vừa dùng".