writing-skills

Tổng quan

Kỹ năng writing-skills dùng để làm gì

Kỹ năng writing-skills là một meta-skill dành cho những người viết, tinh chỉnh và kiểm thử các kỹ năng khác cho các agent như Claude. Nó điều chỉnh mô hình Test-Driven Development (TDD) cổ điển để áp dụng cho tài liệu quy trình, giúp kỹ năng của bạn:

• Dựa trên các kịch bản áp lực thực tế
• Được kiểm chứng dựa trên các lỗi agent thực tế
• Được tinh chỉnh để bịt lỗ hổng và chống lại sự hợp lý hóa

Bạn dùng writing-skills để thiết kế các kỹ năng mà agent có thể phát hiện, làm theo, và tiếp tục bám theo ngay cả khi chịu áp lực thời gian, thiên kiến chi phí chìm hoặc xung đột lợi ích.

writing-skills dành cho ai

Hãy dùng kỹ năng writing-skills nếu bạn là:

• Developer tạo kỹ năng cho Claude hoặc các agent tương tự
• Trưởng nhóm đang chuẩn hóa quy trình trong ~/.claude/skills hoặc ~/.agents/skills/
• Người phụ trách tài liệu chịu trách nhiệm về các kỹ năng phải được thực hiện, không chỉ đọc cho biết
• Tester xác nhận rằng kỹ năng thực sự thay đổi hành vi của agent trước khi rollout

Kỹ năng này không tập trung vào văn phong chung chung. Nó nhắm cụ thể vào việc soạn thảo kỹ năng cho agent sao cho hiệu quả và có thể kiểm thử được.

Những vấn đề kỹ năng này giúp bạn giải quyết

writing-skills được thiết kế cho các tình huống:

• Agent bỏ qua hoặc chỉ làm theo một phần kỹ năng của bạn khi bị áp lực
• Bạn không chắc kỹ năng mới có thực sự thay đổi hành vi hay không
• Bạn cần một cách lặp lại được để kiểm thử kỹ năng bằng subagent trước khi triển khai
• Bạn muốn tuân theo best practice viết kỹ năng của Anthropic mà không phải đoán mò
• Bạn cần trực quan hóa và truyền đạt các workflow kỹ năng phức tạp bằng Graphviz

Nếu bạn có các “kỹ năng” hiện tại giống như những câu chuyện đơn lẻ hoặc ghi chú rời rạc, writing-skills giúp bạn chuyển chúng thành tài liệu tham chiếu có thể tái sử dụng và kiểm thử.

Khi nào writing-skills phù hợp và không phù hợp

Phù hợp khi:

• Kỹ năng dùng để siết kỷ luật (TDD, verification, checklist review)
• Kỹ năng có chi phí tuân thủ thực sự (thời gian, làm lại, trễ giao hàng)
• Kỹ năng mà agent có thể tìm cách lách ("chỉ lần này thôi")
• Kỹ năng mà bạn muốn đo lường mức cải thiện tỷ lệ tuân thủ

Không phù hợp khi:

• Kỹ năng chỉ thuần tham khảo (ví dụ: cú pháp API, cheatsheet ngôn ngữ cơ bản)
• Kỹ năng mà cố ý không có quy tắc nào để vi phạm
• Ghi chú nhẹ nhàng nơi bạn không cần kiểm thử kiểu TDD hoặc kịch bản áp lực

Nếu bạn chỉ cần một ghi chú nhanh, không chính thức cho một cuộc hội thoại, có lẽ bạn không cần writing-skills. Nếu bạn muốn một kỹ năng vẫn “sống sót” dưới áp lực production, bạn nên dùng.

Cách sử dụng

Cài đặt và thiết lập cơ bản

Để cài đặt kỹ năng writing-skills vào một môi trường hỗ trợ skills:

npx skills add https://github.com/obra/superpowers --skill writing-skills

Lệnh này tải kỹ năng writing-skills từ repository obra/superpowers và đăng ký nó cạnh các kỹ năng khác của bạn.

Các kỹ năng cá nhân thường nằm trong thư mục riêng theo từng agent, chẳng hạn:

• ~/.claude/skills/ cho Claude Code
• ~/.agents/skills/ cho Codex hoặc các agent tương tự

Đặt (hoặc kiểm tra lại) thư mục writing-skills nằm dưới thư mục gốc chứa skills tương ứng, để agent của bạn có thể load SKILL.md và các file liên quan khi cần.

Các file và thư mục chính trong writing-skills

Sau khi cài xong, hãy mở các file này trước để hiểu và áp dụng workflow:

• SKILL.md – Định nghĩa cốt lõi và tổng quan về writing-skills, bao gồm cách ánh xạ TDD sang kỹ năng.
• anthropic-best-practices.md – Hướng dẫn “chuẩn chính thức” về cách viết kỹ năng ngắn gọn, dễ phát hiện và hiệu quả cho Claude.
• testing-skills-with-subagents.md – Hướng dẫn thực hành về xây dựng và chạy các kịch bản áp lực và chiến dịch kiểm thử.
• persuasion-principles.md – Các pattern thuyết phục dựa trên bằng chứng để tăng khả năng agent tuân thủ kỹ năng.
• graphviz-conventions.dot – Quy ước biểu diễn workflow và quy trình của kỹ năng dưới dạng sơ đồ Graphviz.
• render-graphs.js – Script trợ giúp trích xuất các khối ```dot trong SKILL.md và render thành sơ đồ SVG.
• examples/CLAUDE_MD_TESTING.md – Ví dụ hoàn chỉnh về một chiến dịch kiểm thử cho các biến thể tài liệu CLAUDE.md.

Những file này kết hợp lại thành một workflow đầy đủ gồm soạn thảo + kiểm thử + trực quan hóa cho kỹ năng.

Quy trình cốt lõi: TDD cho kỹ năng

writing-skills áp dụng trực tiếp các khái niệm TDD vào việc soạn thảo kỹ năng. Vòng lặp cấp cao như sau:

1. Viết test case (kịch bản áp lực)

   • Thiết kế các tình huống thực tế nơi agent có thể hợp lý hóa việc bỏ qua hoặc bẻ cong quy trình bạn mong muốn.
   • Dùng subagent để chạy các kịch bản này và ghi lại hành vi của chúng.

2. Chạy test baseline và quan sát chúng fail

   • Thực thi kịch bản khi chưa load kỹ năng mới hoặc đã chỉnh sửa.
   • Ghi lại chỗ agent thất bại: bỏ qua, hợp lý hóa, hoặc hiểu sai điều gì.

3. Viết hoặc tinh chỉnh kỹ năng

   • Soạn hoặc cập nhật SKILL.md và các file hỗ trợ để xử lý những lỗi cụ thể bạn quan sát được.
   • Dùng ngôn ngữ ngắn gọn, mệnh lệnh phù hợp với giới hạn context window.

4. Chạy lại test với kỹ năng đã được load

   • Chạy lại đúng các kịch bản đó, lần này với kỹ năng đang hoạt động.
   • Xác minh rằng agent giờ đã phát hiện, thông báo và tuân theo kỹ năng.

5. Refactor để bịt lỗ hổng

   • Xác định những chỗ agent vẫn còn hợp lý hóa hoặc chỉ tuân thủ một phần.
   • Áp dụng các nguyên tắc thuyết phục (authority, commitment, v.v.) để tăng độ bám.
   • Cắt bớt token không cần thiết để giữ kỹ năng ngắn gọn.

Vòng lặp này phản chiếu RED → GREEN → REFACTOR trong TDD cổ điển, nhưng áp dụng cho tài liệu và việc thực thi quy trình thay vì cho code.

Dùng anthropic-best-practices.md để viết kỹ năng tốt hơn

File anthropic-best-practices.md cung cấp hướng dẫn chuyên biệt cho hệ sinh thái Claude, bao gồm:

• Vì sao kỹ năng ngắn gọn giúp dùng context hiệu quả hơn và cải thiện hiệu năng mô hình
• Thời điểm và cách Claude load SKILL.md và các file khác vào context window
• Cách viết các phần trong kỹ năng sao cho xứng đáng với chi phí token

Bạn có thể dùng file này như một checklist khi review kỹ năng của chính mình:

• Gỡ bỏ các giải thích mà Claude vốn đã biết
• Tập trung vào pattern, rule và workflow mang tính hành động
• Cấu trúc kỹ năng sao cho các hướng dẫn quan trọng nhất xuất hiện sớm và rõ ràng

Kết hợp các thực hành này với vòng lặp TDD từ writing-skills giúp bảo đảm kỹ năng của bạn vừa dễ được phát hiện vừa tiết kiệm tài nguyên.

Kiểm thử kỹ năng với subagent

File testing-skills-with-subagents.md mở rộng cách tiếp cận TDD bằng một phương pháp kiểm thử cụ thể:

• Thiết kế kịch bản mô phỏng áp lực production thực tế (thời gian, chi phí chìm, tốc độ vs chất lượng).
• Chạy chúng bằng subagent mô phỏng cách agent chính của bạn sẽ hành xử.
• Ghi lại lỗi và các lập luận hợp lý hóa trong những định dạng có cấu trúc.

Điều này đặc biệt hữu ích cho các kỹ năng:

• Ép tuân thủ các best practice tốn thời gian (ví dụ: viết test trước)
• Cạnh tranh với mục tiêu ngắn hạn (ví dụ: ship nhanh vs kiểm chứng kỹ)
• Cần đứng vững ngay cả khi con người chủ động yêu cầu “đi đường tắt”

Bằng cách làm theo các pattern kiểm thử trong file này, bạn có thể xác minh kỹ năng dưới áp lực trước khi nó đến tay người dùng cuối.

Áp dụng các nguyên tắc thuyết phục vào thiết kế kỹ năng

persuasion-principles.md tóm tắt các nguyên tắc tâm lý cũng ảnh hưởng đến hành vi của LLM, chẳng hạn:

• Authority – Ngôn ngữ rõ ràng, không thương lượng cho các quy tắc liên quan đến an toàn
• Commitment – Yêu cầu agent thông báo khi chúng dùng một kỹ năng và bám theo đường đi đã chọn
• Scarcity và các nguyên tắc khác – Dùng cẩn trọng để ưu tiên các thực hành quan trọng

Trong thực tế, bạn có thể:

• Dùng giọng mệnh lệnh mạnh mẽ hơn cho các bước bắt buộc
• Yêu cầu agent nói rõ: "I am using [Skill Name] now" khi một kỹ năng được kích hoạt
• Thiết kế checklist theo kiểu buộc phải hoàn thành thay vì chỉ đọc lướt

Mục tiêu không phải là thao túng, mà là đảm bảo các thực hành trọng yếu được tuân thủ nhất quán.

Trực quan hóa luồng kỹ năng với Graphviz

Các kỹ năng phức tạp thường hưởng lợi từ biểu diễn trực quan. writing-skills bao gồm:

• graphviz-conventions.dot – Cấu trúc và phong cách gợi ý cho sơ đồ
• render-graphs.js – Script Node.js trích xuất các khối ```dot từ SKILL.md và chuyển thành file SVG.

Cách dùng cơ bản cho script render:

./render-graphs.js path/to/your/skill
# hoặc
./render-graphs.js path/to/your/skill --combine

Điều này giúp bạn:

• Truyền đạt luồng của một kỹ năng cho cộng sự là con người
• Phát hiện các khoảng trống hoặc vòng lặp trong thiết kế quy trình
• Giữ tài liệu và hình vẽ đồng bộ bằng cách nhúng sơ đồ dưới dạng khối code ```dot trong SKILL.md.

Tùy biến writing-skills cho môi trường của bạn

Repository mô tả các pattern mà bạn nên tùy biến, không nên sao chép nguyên xi. Khi tích hợp writing-skills vào workflow riêng:

• Giữ vòng lặp TDD, nhưng điều chỉnh format kịch bản cho phù hợp với công cụ của bạn
• Dùng cấu trúc thư mục riêng miễn là vẫn giữ ranh giới kỹ năng rõ ràng
• Tích hợp các chiến dịch kiểm thử vào quy trình CI, review hoặc release hiện tại

Mục tiêu là xây dựng một workflow soạn thảo có kiểm thử lặp lại được phù hợp với team và hạ tầng của bạn.

FAQ

Tôi nên load kỹ năng writing-skills khi nào?

Hãy dùng writing-skills bất cứ khi nào bạn đang:

• Tạo một kỹ năng mới sẽ được đặt dưới ~/.claude/skills hoặc thư mục tương tự
• Chỉnh sửa một kỹ năng hiện có đã bắt đầu bị lệch hoặc thường bị bỏ qua
• Chuẩn bị một kỹ năng để triển khai cho đồng đội hoặc dùng trong production
• Thiết kế hoặc chạy chiến dịch kiểm thử kỹ năng bằng subagent

Nếu bạn chỉ đang thử nghiệm trong một phiên tạm thời, bạn có thể không cần áp dụng đầy đủ workflow writing-skills.

Tôi có cần hiểu TDD trước khi dùng writing-skills không?

Có. Kỹ năng này yêu cầu bạn quen thuộc với superpowers:test-driven-development. writing-skills giả định bạn đã biết vòng RED → GREEN → REFACTOR và sau đó áp dụng nó cho tài liệu:

• RED: Chạy kịch bản khi chưa có kỹ năng, ghi lại lỗi
• GREEN: Thêm hoặc tinh chỉnh kỹ năng để các kịch bản đó pass
• REFACTOR: Cải thiện độ rõ ràng, bịt lỗ hổng và giảm chi phí token

Nếu TDD còn mới với bạn, hãy load và nghiên cứu skill liên quan đến TDD trước.

writing-skills giúp gì cho hành vi riêng của Claude?

writing-skills được thiết kế cho các môi trường như Claude, và repository có kèm anthropic-best-practices.md với hướng dẫn bám sát tài liệu Anthropic. Kết hợp lại, chúng giúp bạn:

• Viết kỹ năng mà Claude có thể discover một cách đáng tin cậy
• Tôn trọng context window và ngân sách token
• Cấu trúc các file SKILL sao cho Claude load và sử dụng chúng hiệu quả

Điều này khiến writing-skills đặc biệt hữu ích nếu bạn đang xây dựng một thư viện kỹ năng cho Claude.

Tôi có thể dùng writing-skills cho các kỹ năng phi kỹ thuật hoặc không liên quan code không?

Có, miễn là kỹ năng mô tả một quy trình lặp lại được có thể kiểm thử bằng kịch bản. Ví dụ:

• Checklist ứng phó sự cố
• Workflow review code
• Quy trình review hoặc phê duyệt tài liệu

Điều quan trọng là quy trình đó phải có:

• Rule rõ ràng để agent có thể tuân thủ hoặc vi phạm
• Hệ quả thực sự khi bước nào đó bị bỏ qua
• Các kịch bản mà bạn có thể kiểm thử mức độ tuân thủ một cách có ý nghĩa

Nội dung thuần mô tả hoặc kể chuyện không phải là đối tượng phù hợp.

File examples/CLAUDE_MD_TESTING.md dùng để làm gì?

examples/CLAUDE_MD_TESTING.md là một ví dụ trọn vẹn cho thấy cách:

• Thiết kế kịch bản thực tế (áp lực thời gian, chi phí chìm, authority vs tốc độ)
• Chạy chúng trên các biến thể tài liệu CLAUDE.md khác nhau
• So sánh mức độ mỗi biến thể dẫn đến việc discover và sử dụng kỹ năng tốt đến đâu

Hãy dùng nó như một template khi bạn thiết kế các chiến dịch kiểm thử kỹ năng của riêng mình.

Một kỹ năng khác gì so với câu chuyện hoặc case study?

Trong mô hình writing-skills:

• Kỹ năng là tài liệu tham chiếu có thể tái sử dụng, mã hóa các pattern, công cụ hoặc workflow đã được kiểm chứng.
• Câu chuyện hoặc case study mô tả cách bạn giải quyết một vấn đề cụ thể đúng một lần.

writing-skills giúp bạn chuyển từ những câu chuyện đơn lẻ sang các kỹ năng đã được khái quát hóa và có thể kiểm thử để các agent về sau có thể tìm và áp dụng trong tình huống mới.

Nếu kỹ năng của tôi dài thì sao — có vấn đề không?

Độ dài quan trọng vì context window có hạn. anthropic-best-practices.md giải thích vì sao kỹ năng ngắn gọn cho hiệu suất tốt hơn:

• Ban đầu chỉ metadata được load, nhưng một khi SKILL.md được đọc, mọi token đều phải “tranh chỗ” với lịch sử hội thoại.
• Bạn nên luôn tự hỏi mỗi phần có xứng đáng với vị trí của nó không.

writing-skills khuyến khích bạn:

• Cắt bớt các giải thích trùng lặp
• Chuyển ví dụ sang các file hỗ trợ nếu cần
• Tập trung SKILL.md vào quy trình cốt lõi và các rule giúp test pass

Làm sao tôi biết writing-skills đang mang lại hiệu quả?

Bạn sẽ thấy tác động khi:

• Những kỹ năng từng bị bỏ qua dưới áp lực giờ được tuân thủ
• Các kỹ năng mới đi kèm kịch bản và test rõ ràng, chứ không chỉ là text
• Bạn chỉ ra được sự khác biệt rõ ràng giữa hành vi có và không có kỹ năng trong các kịch bản cụ thể

Nếu bạn không thể chứng minh sự khác biệt giữa hành vi khi có và không có kỹ năng, hãy quay lại vòng lặp TDD, cùng với các hướng dẫn về thuyết phục và kiểm thử mà writing-skills cung cấp.