Tạo skill Claude Code viết báo cáo tuần theo mẫu công ty

Chiều thứ Sáu nào cũng vậy: mở 5 file ghi chú, chép số từ Excel, căn lại bảng trong Word cho đúng mẫu. Một tiếng trôi qua cho việc lặp lại y hệt tuần trước.

ghi chú rời rạc + bảng Excel + mẫu Word trống

• Gõ /bao-cao-tuan 2026-W42
• Claude đọc ghi chú và số liệu
• Script tính % thay đổi
• File Word đúng mẫu công ty

Bài toán: thứ Sáu nào cũng mất 1 tiếng gom báo cáo

Kết luận trước: báo cáo tuần là việc lặp lại, có đầu vào và đầu ra cố định. Đây đúng là loại việc nên đóng gói thành skill.

Một báo cáo tuần ở văn phòng thường có ba phần giống nhau mỗi tuần:

• Đầu vào: ghi chú công việc trong tuần, vài con số từ Excel.
• Cách làm: gom việc thành nhóm, tính tăng giảm so với tuần trước, ghi rõ chỗ còn thiếu.
• Đầu ra: một file Word theo mẫu công ty, có logo, font, bảng số liệu.

Nếu chỉ dùng chat thường, tuần nào bạn cũng phải dán lại hướng dẫn dài. Skill giải quyết đúng chỗ đó: viết quy trình một lần, gọi lại bằng một lệnh.

Skill, slash command và subagent khác nhau thế nào?

Kết luận trước: trong Claude Code, custom slash command đã gộp vào skill. File .claude/commands/bao-cao-tuan.md và thư mục .claude/skills/bao-cao-tuan/SKILL.md đều tạo ra lệnh /bao-cao-tuan. File command cũ vẫn chạy, nhưng skill có thêm nhiều tính năng.

Theo tài liệu Claude Code, skill hơn command ở ba điểm: có thư mục riêng để chứa script và file mẫu, có frontmatter để quy định ai được gọi skill, và Claude có thể tự nạp skill khi yêu cầu của bạn khớp với mô tả. Nếu skill và command trùng tên, skill được ưu tiên.

Subagent là chuyện khác. Đó là một trợ lý phụ chạy trong context window riêng (vùng nhớ làm việc riêng), có system prompt và quyền dùng tool riêng. Subagent làm xong chỉ trả về bản tóm tắt, nên log dài không làm đầy cuộc trò chuyện chính.

Với báo cáo tuần, mình chọn skill: cần thư mục chứa script và mẫu Word, chạy ngay trong phiên để bạn xem và sửa kết quả.

Thiết kế đầu vào và đầu ra

Kết luận trước: quyết định trước dữ liệu nằm ở đâu và file ra tên gì. Skill càng ít phải đoán thì càng ít sai.

Bộ mẫu dùng cấu trúc thư mục dự án như sau:

• Ghi chú tuần (ghi-chu.md): mỗi dòng một việc, ghi thứ trong tuần. Dòng đầu có “Người lập: …”.
• Số liệu (so-lieu.xlsx): sheet đầu tiên, 4 cột Chỉ số | Tuần này | Tuần trước | Mục tiêu.
• Mẫu Word (mau-bao-cao-tuan.docx): mẫu của công ty, chỉ thêm vài chỗ giữ chỗ như {{TUAN}}, {{TOM_TAT}} và một dòng {{NOI_DUNG}}.
• Tên tuần theo chuẩn ISO, ví dụ 2026-W42 là tuần từ thứ Hai 12/10 đến thứ Sáu 16/10/2026.

Viết SKILL.md từng phần

Kết luận trước: một SKILL.md tốt gồm frontmatter ngắn gọn, vài quy tắc luôn áp dụng, checklist từng bước và một file mẫu đầu ra riêng. Tài liệu của Anthropic khuyên giữ phần thân SKILL.md dưới 500 dòng, chi tiết thì tách ra file khác.

Frontmatter và description

Frontmatter là phần nằm giữa hai dòng --- ở đầu file. Nó phải bắt đầu ngay dòng đầu tiên.

File .claude/skills/bao-cao-tuan/SKILL.md, phần đầu:

---
name: bao-cao-tuan
description: Viết báo cáo tuần (weekly report) theo mẫu Word của công ty từ ghi chú tuần (ghi-chu.md) và bảng số liệu (so-lieu.xlsx) trong thư mục du-lieu/<tuần>. Dùng khi người dùng gõ /bao-cao-tuan hoặc nhờ làm báo cáo tuần, tổng hợp tuần, weekly report.
argument-hint: "[tuần ISO, ví dụ 2026-W42]"
disable-model-invocation: true
---

Ý nghĩa từng dòng:

• name: tên lệnh. Chỉ dùng chữ thường, số, dấu gạch ngang, tối đa 64 ký tự, không chứa chữ “claude” hay “anthropic”.
• description: nói skill làm gì và khi nào dùng. Viết ở ngôi thứ ba, đưa từ khoá người dùng hay gõ lên đầu. Claude Code cắt phần mô tả ở 1.536 ký tự trong danh sách skill.
• argument-hint: gợi ý hiện khi bạn gõ /bao-cao-tuan.
• disable-model-invocation: true: chỉ chạy khi bạn gõ lệnh. Skill này tạo file, nên mình không để Claude tự kích hoạt.

Checklist các bước

Phần thân chia hai khối: quy tắc luôn áp dụng (không bịa số, thiếu thì ghi “Chưa có số liệu”, không sửa file gốc) và checklist 6 bước. Anthropic gợi ý để Claude chép checklist vào câu trả lời và đánh dấu khi xong, nhờ vậy khó bỏ sót bước.

Chép checklist này vào câu trả lời và đánh dấu khi làm xong:

- [ ] 1. Kiểm tra thư mục du-lieu/<tuần>
- [ ] 2. Đọc số liệu bằng script
- [ ] 3. Đọc ghi chú tuần
- [ ] 4. Viết bao-cao/<tuần>.json theo mau-dau-ra.md
- [ ] 5. Xuất Word bằng script
- [ ] 6. Báo lại cho người dùng

Mỗi bước có hướng xử lý khi gặp sự cố. Ví dụ bước 1: thiếu file số liệu thì vẫn viết tiếp từ ghi chú, nhưng phải ghi vào mục “Cần bổ sung”.

Mẫu đầu ra

Nội dung báo cáo được viết ra một file JSON trung gian trước, rồi script mới đổ vào Word. Cấu trúc JSON nằm trong mau-dau-ra.md, SKILL.md chỉ trỏ tới file này. Cách tách file như vậy giúp Claude chỉ đọc mẫu khi cần, đúng nguyên tắc progressive disclosure (nạp dần từng lớp) trong tài liệu của Anthropic.

Lợi ích của bước JSON trung gian: bạn mở ra đọc và sửa được trước khi xuất Word. Nếu thiếu trường bắt buộc, script dừng lại và báo rõ thiếu trường nào.

Truyền tham số với $ARGUMENTS

Bạn gõ gì sau tên lệnh thì nội dung đó thay vào chỗ $ARGUMENTS trong SKILL.md:

# Báo cáo tuần theo mẫu công ty

Tuần cần làm: $ARGUMENTS

Nếu không có tuần, hỏi lại người dùng. Không tự đoán tuần.

Gõ /bao-cao-tuan 2026-W42 thì dòng trên thành “Tuần cần làm: 2026-W42”. Muốn nhiều tham số, dùng $0, $1… theo vị trí. Nếu SKILL.md không có chỗ nào nhận tham số, Claude Code tự thêm dòng ARGUMENTS: … vào cuối nội dung.

Gõ /skills trong Claude Code để thấy bao-cao-tuan trong danh sách. Cách Claude Code tìm và hiển thị skill có trong tài liệu Skills chính thức.

Script xuất Word: python-docx hay skill docx của Anthropic?

Kết luận trước: bộ mẫu dùng python-docx vì việc chỉ là đổ chữ vào mẫu có sẵn. Cần dựng tài liệu phức tạp hoặc PowerPoint thì cài thêm skill docx, pptx của Anthropic.

Hai script trong bộ mẫu:

• doc_so_lieu.py: đọc so-lieu.xlsx, tính ngày đầu và cuối tuần từ mã tuần ISO, tính % thay đổi, đánh dấu ô trống là null. Phép tính do script làm, không để Claude tự cộng trừ.
• xuat_word.py: mở mẫu Word, thay các chỗ giữ chỗ, chèn các mục, gạch đầu dòng và bảng số liệu vào đúng vị trí {{NOI_DUNG}}. Font, lề, logo, header và footer giữ nguyên theo mẫu.

Trong SKILL.md, script được gọi qua biến ${CLAUDE_SKILL_DIR} (đường dẫn tới thư mục skill), nên chạy ở máy nào cũng tìm đúng file. Cài thư viện một lần:

$ pip install python-docx openpyxl

Nếu cần tạo file Word, PowerPoint từ đầu, Anthropic có sẵn plugin document-skills gồm skill docx, pptx, xlsx, pdf. Lưu ý: kho GitHub ghi bốn skill này là source-available, không phải open source. Đọc giấy phép trước khi sửa hay chia sẻ lại. Hai lệnh cài theo README của kho, gõ ngay trong ô chat của Claude Code:

$ /plugin marketplace add anthropics/skills
$ /plugin install document-skills@anthropic-agent-skills

Kết quả thật khi chạy /bao-cao-tuan 2026-W42 trên bộ dữ liệu mẫu trong file tải về (Bỏ Túi AI chạy ngày 18/10/2026). Ảnh chụp bản xem trước của file .docx; dữ liệu là dữ liệu giả.

Về hộp xin quyền: lần đầu chạy script, Claude Code sẽ hỏi bạn có cho phép không. Muốn bỏ bước hỏi, frontmatter có trường allowed-tools để cấp quyền trước. Nhưng tài liệu cũng cảnh báo một skill có thể tự cấp quyền rộng cho chính nó, nên bộ mẫu không điền sẵn trường này. Bạn đọc script rồi mới quyết.

Đặt skill ở đâu, chia sẻ cho cả nhóm qua git

Kết luận trước: đặt trong .claude/skills/ của thư mục dự án rồi commit lên git, cả nhóm có cùng một skill.

Khi trùng tên, thứ tự ưu tiên là doanh nghiệp, rồi cá nhân, rồi dự án. Với báo cáo tuần của cả phòng, chọn dự án: mỗi người clone repo về là có lệnh /bao-cao-tuan, sửa SKILL.md thì commit để cả nhóm cùng cập nhật.

Hai điểm nên biết:

• Sửa skill trong lúc đang mở phiên thì Claude Code tự nhận bản mới. Nếu bạn vừa tạo thư mục skills mới hoàn toàn, chạy /reload-skills.
• Đừng commit dữ liệu thật trong du-lieu/. Thêm thư mục này vào .gitignore nếu repo dùng chung.

Kiểm thử 3 kịch bản

Kết luận trước: thử skill với ít nhất ba tình huống trước khi giao cho cả nhóm. Tài liệu của Anthropic cũng khuyên tạo ít nhất ba bài kiểm tra cho mỗi skill.

Bộ mẫu có sẵn ba tuần dữ liệu giả cho ba kịch bản:

Chạy xong, mở file Word kiểm từng con số với Excel gốc. Skill chạy đúng 3 lần chưa chắc đã đúng lần thứ 4, nên tuần đầu dùng thật vẫn phải đọc kỹ.

Khi Claude không làm theo skill: tài liệu Claude Code giải thích skill chỉ được nạp vào cuộc trò chuyện một lần, Claude không đọc lại file ở các lượt sau. Cuộc trò chuyện quá dài bị nén lại thì chỉ phần đầu của skill được giữ. Cách xử lý: gọi lại /bao-cao-tuan, và đặt quy tắc quan trọng nhất ở đầu SKILL.md.

Khi nào cần subagent hoặc context: fork?

Kết luận trước: báo cáo tuần không cần subagent. Chỉ dùng khi phần việc độc lập, sinh nhiều log và bạn chỉ cần bản tóm tắt.

Thêm context: fork vào frontmatter thì skill chạy trong một subagent riêng. Trường agent chọn loại subagent: Explore, Plan, general-purpose hoặc subagent tự định nghĩa trong .claude/agents/.

Lưu ý quan trọng: subagent không thấy lịch sử chat. Mọi hướng dẫn phải nằm đủ trong SKILL.md. Skill chạy kiểu fork mặc định chạy nền với bộ tool hẹp hơn; cần đủ tool thì đặt background: false.

Ví dụ hợp lý: một skill phụ đọc 20 file biên bản họp trong tuần rồi trả về 10 gạch đầu dòng. Phần đọc dài nằm trong subagent, cuộc trò chuyện chính chỉ nhận kết quả gọn.

An toàn khi dùng và chia sẻ skill

Kết luận trước: skill là quy trình chạy trên máy bạn, có thể chạy script. Đọc kỹ trước khi dùng skill của người khác, và không để dữ liệu thật lọt vào bản chia sẻ.

• Dữ liệu ví dụ phải giả. File mẫu trong zip đều là dữ liệu giả. Khi chia sẻ skill của bạn, thay số thật, tên khách hàng thật bằng dữ liệu giả.
• Đọc script trước khi chạy, nhất là skill tải từ Internet. Kiểm tra trường allowed-tools: tài liệu cảnh báo cơ chế tin cậy thư mục (workspace trust) không chặn trường này.
• Dữ liệu vẫn đi qua mô hình. Script chạy trên máy bạn, nhưng nội dung Claude đọc (ghi chú, số liệu) được gửi tới mô hình để xử lý như mọi cuộc trò chuyện khác. Dữ liệu nhạy cảm cần theo quy định của công ty.
• Làm trên bản sao khi thử skill với file quan trọng.

Skill khác slash command thế nào?

Trong Claude Code, custom slash command đã gộp vào skill: cả hai đều tạo lệnh /tên. Skill có thêm thư mục chứa script và file mẫu, có frontmatter điều khiển cách gọi, và Claude có thể tự nạp khi yêu cầu khớp mô tả. File trong .claude/commands/ cũ vẫn chạy bình thường.

SKILL.md đặt ở đâu để cả nhóm cùng dùng?

Đặt trong .claude/skills/<tên-skill>/ của thư mục dự án rồi commit lên git. Ai mở Claude Code trong repo đó đều có lệnh. Muốn dùng riêng cho mình ở mọi dự án thì đặt ở ~/.claude/skills/.

Xuất Word hoặc PowerPoint theo mẫu công ty được không?

Được. Bộ mẫu dùng python-docx để đổ nội dung vào file .docx có sẵn, giữ nguyên font, logo, header. Với PowerPoint hoặc tài liệu dựng từ đầu, có thể cài plugin document-skills của Anthropic (skill docx, pptx), nhưng nên đọc giấy phép vì đây là skill source-available.

Khi nào nên dùng subagent?

Khi phần việc độc lập, sinh nhiều kết quả trung gian và bạn chỉ cần bản tóm tắt, ví dụ đọc hàng chục file biên bản. Subagent không thấy lịch sử chat, nên hướng dẫn phải đầy đủ. Báo cáo tuần thông thường chạy trong cuộc trò chuyện chính là đủ.

Vì sao Claude không tự gọi skill của tôi?

Kiểm tra description có chứa từ bạn hay gõ không, và skill có đặt disable-model-invocation: true không (skill trong bài cố ý đặt vậy, phải gõ /bao-cao-tuan). Frontmatter lỗi YAML thì skill vẫn nạp nhưng mất mô tả. Gõ /skills để xem skill nào đang được nạp.

Skill có gửi dữ liệu ra ngoài không?

Bản thân skill chỉ là file trên máy bạn và script chạy cục bộ. Nhưng nội dung Claude đọc được gửi tới mô hình để xử lý, như mọi cuộc trò chuyện khác. Ngoài ra script trong skill của người khác có thể làm bất cứ việc gì, nên hãy đọc trước khi chạy.

Đọc tiếp: Cài Claude Code làm trợ lý Excel · Làm sạch Excel bằng AI · AI Agent là gì · Series AI cho dân văn phòng

Nguồn & ghi chú

• Claude Code Docs — Extend Claude with skills — kiểm tra 18/10/2026
• Claude Code Docs — Subagents — kiểm tra 18/10/2026
• Claude Platform Docs — Skill authoring best practices — kiểm tra 18/10/2026
• GitHub anthropics/skills — bộ skill docx, pptx, xlsx, pdf — kiểm tra 18/10/2026
• python-docx — hướng dẫn cài đặt — kiểm tra 18/10/2026