writing-skills

Tổng quan về skill writing-skills

writing-skills làm được gì

Skill writing-skills là một hướng dẫn Skill Authoring để tạo, chỉnh sửa và kiểm chứng agent skill theo quy trình test-driven. Ý tưởng cốt lõi rất đơn giản nhưng có chủ đích rõ ràng: xem việc viết skill giống như TDD cho tài liệu quy trình. Thay vì viết sẵn lời khuyên rồi hy vọng nó hiệu quả, bạn tạo ra các tình huống có áp lực, quan sát agent thất bại khi chưa có skill, rồi chỉ viết đúng phần hướng dẫn thực sự làm thay đổi hành vi.

Ai nên dùng writing-skills

writing-skills phù hợp nhất với những ai đang viết skill cho Claude Code, các thiết lập agent kiểu Codex, hoặc những thư mục skill cục bộ tương tự. Nó đặc biệt hữu ích nếu bạn đang xây các skill nhằm ép tính kỷ luật, thêm bước xác minh, hoặc giữ agent bám quy trình mà bình thường chúng dễ bỏ qua khi bị thúc thời gian.

Nhu cầu thực sự mà writing-skills giải quyết

Đa số người dùng không thật sự cần “được giúp viết markdown”. Thứ họ cần là một cách lặp lại được để tạo ra SKILL.md mà agent thực sự tìm thấy, thực sự làm theo, và vẫn tiếp tục tuân thủ khi tốc độ, sự tự tin hoặc tâm lý “đã lỡ làm đến đây rồi” khiến nó bỏ qua quy trình. writing-skills được thiết kế để xử lý đúng bài toán đó.

Vì sao skill này khác với một prompt chung chung

Một prompt thông thường có thể giúp bạn phác thảo một skill. writing-skills cho bạn một phương pháp để chứng minh skill đó có làm thay đổi hành vi hay không:

• xác định các tình huống có áp lực
• chạy test baseline khi chưa có skill
• viết tài liệu dựa trên các kiểu thất bại đã quan sát được
• test lại và refactor để bịt các kẽ hở

Vì vậy, với Skill Authoring, nó hữu ích hơn hẳn kiểu chỉ dẫn một lần như “hãy viết cho tôi một skill”.

Điều kiện tiên quyết quan trọng và các đánh đổi

Rào cản lớn nhất khi áp dụng writing-skills là skill này giả định bạn đã hiểu cách repo tiếp cận theo khung TDD. Tài liệu nêu rõ rằng bạn cần có nền tảng về superpowers:test-driven-development. Nếu bỏ qua phần này, các lời khuyên về viết skill có thể trông khắt khe quá mức hoặc quá nặng về test.

Đánh đổi cũng rất rõ: quy trình này chậm hơn so với viết theo trực giác, nhưng đáng giá hơn nhiều khi chi phí của thất bại cao hoặc khi agent rất dễ tự hợp lý hóa việc bỏ qua skill.

Cách dùng skill writing-skills

Bối cảnh cài đặt writing-skills

Repo này ghi rõ rằng personal skills nằm trong các thư mục theo từng agent, ví dụ ~/.claude/skills cho Claude Code và ~/.agents/skills/ cho Codex. Nếu bạn cài từ repo obra/superpowers bằng skill manager, hãy kiểm tra để chắc rằng skill sau khi cài thực sự nằm trong thư mục mà agent của bạn quét.

Nếu bạn muốn xem thủ công trước khi cài, hãy bắt đầu từ đây:

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

Đọc các file này trước tiên

Để đánh giá nhanh nhất, hãy đi theo lộ trình đọc sau:

1. SKILL.md để nắm workflow chính và định vị của skill
2. testing-skills-with-subagents.md để hiểu cách chạy RED/GREEN/REFACTOR cho skill
3. anthropic-best-practices.md để lấy hướng dẫn viết ngắn gọn, súc tích
4. examples/CLAUDE_MD_TESTING.md để xem các tình huống áp lực thực tế
5. persuasion-principles.md nếu skill của bạn cần chống lại việc agent tự hợp lý hóa
6. graphviz-conventions.dot và render-graphs.js chỉ khi bạn muốn dựng sơ đồ

Lộ trình này cho lượng thông tin hữu ích cao hơn nhiều so với việc chỉ lướt qua phần đầu của SKILL.md.

writing-skills cần đầu vào gì từ bạn

writing-skills hoạt động tốt nhất khi bạn mang đến bằng chứng cụ thể, không chỉ là một chủ đề chung chung. Đầu vào mạnh thường gồm:

• chính xác skill bạn muốn tạo hoặc chỉnh sửa
• hành vi của agent mà bạn muốn thay đổi
• ví dụ về thất bại khi chưa có skill
• các tình huống mà agent dễ bị cám dỗ bỏ qua quy trình
• thư mục đích và nền tảng nơi skill sẽ được đặt

Đầu vào yếu: “Help me write a testing skill.”

Đầu vào mạnh: “Create a skill that forces pre-deployment verification for database migrations. Agents currently skip rollback checks when fixes seem obvious.”

Biến một mục tiêu thô thành prompt dùng được

Một mẫu writing-skills usage hiệu quả là yêu cầu đủ cả bốn phần ngay từ đầu:

1. pressure scenarios
2. baseline failure expectations
3. the skill structure
4. the validation plan

Ví dụ:

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

Cách này mạnh hơn nhiều so với chỉ yêu cầu “một tài liệu skill được viết chỉn chu”, vì nó cung cấp luôn mô hình thất bại mà skill cần khắc phục.

Quy trình dùng writing-skills được khuyến nghị

Một quy trình thực tế thường như sau:

1. Xác định hành vi cần được ép tuân thủ
2. Viết 2–5 tình huống có áp lực
3. Test agent khi chưa có skill
4. Ghi lại chính xác các cách tự hợp lý hóa và lối tắt mà agent dùng
5. Chỉ soạn SKILL.md để xử lý đúng các thất bại đó
6. Test lại khi đã nạp skill
7. Siết câu chữ ở những chỗ agent vẫn còn trượt
8. Loại bỏ mọi phần giải thích không giúp tăng mức tuân thủ

Bước cuối rất quan trọng, vì tài liệu best practices đi kèm nhấn mạnh tính tiết kiệm token và chỉ dẫn ngắn gọn.

Khi nào phương pháp test-driven của writing-skills quan trọng nhất

Hãy dùng writing-skills for Skill Authoring khi skill có chi phí tuân thủ:

• thêm bước test
• xác minh chậm hơn
• kiểm tra tài liệu
• yêu cầu restart hoặc làm lại
• các quy tắc đi ngược động lực làm cho nhanh

Phương pháp này ít quan trọng hơn với các skill thuần tham khảo như cheatsheet cú pháp API, nơi agent gần như không có lý do gì để né nội dung.

Cách dùng tài liệu tham chiếu về subagent testing

testing-skills-with-subagents.md là tài liệu đồng hành mang tính thực chiến. Nó giúp bạn kiểm tra xem skill có đứng vững dưới áp lực thật hay không, thay vì chỉ “nghe có vẻ đúng” trong điều kiện lý tưởng. Hãy đọc file này khi bạn cần:

• mẫu format cho scenario
• cách ánh xạ RED/GREEN/REFACTOR
• cách ghi nhận rationalization
• ví dụ về việc không tuân thủ do áp lực

Nếu bản nháp đầu tiên trông ổn nhưng mức độ áp dụng lại thấp, đây thường là lối nhanh nhất để cải thiện.

Dùng các scenario mẫu, nhưng đừng sao chép nguyên xi trong writing-skills

examples/CLAUDE_MD_TESTING.md hữu ích vì nó cho thấy pressure scenario thật sự trông như thế nào: áp lực thời gian, sunk cost, authority và familiarity bias. Sai lầm thường gặp là bê nguyên các scenario này sang những skill không liên quan.

Thay vào đó, hãy điều chỉnh kiểu áp lực cho đúng workflow của bạn. Ví dụ:

• deployment skill → tính khẩn cấp và nỗi sợ rollback
• review skill → sự tự tin và thiên lệch ưu tiên tốc độ
• security skill → kiểu tự nhủ “chỉ lần này thôi”
• style skill → chi phí áp dụng thấp, nên có thể test nhẹ hơn

Hướng dẫn persuasion khớp vào workflow ra sao

persuasion-principles.md không phải phần cho có; nó xuất hiện ở đây vì có những skill vẫn thất bại dù quy trình đã viết rất rõ. Nếu skill của bạn phải ép một hành vi mà agent thường chống lại, cách diễn đạt mạnh hơn có thể giúp ích. File này gợi ý các mẫu cụ thể như authority, commitment và explicit announcements.

Tuy nhiên hãy dùng cẩn thận. Mục tiêu không phải làm skill “to tiếng” hơn, mà là khiến các hành động bắt buộc khó bị agent tự hợp lý hóa để bỏ qua hơn.

Các quy tắc ngắn gọn ảnh hưởng trực tiếp đến chất lượng đầu ra

Một trong những điểm giá trị nhất của repo này là lời nhắc rằng các skill phải chia sẻ cùng một ngân sách ngữ cảnh. writing-skills không bảo bạn viết nhiều hơn; nó bảo bạn chỉ viết những gì thực sự làm thay đổi hành vi.

Dấu hiệu tốt:

• trigger cụ thể
• hành động bắt buộc rõ ràng, dứt khoát
• ví dụ ngắn gắn với lỗi thực tế
• tối thiểu phần nền

Dấu hiệu xấu:

• văn xuôi dài dòng để tạo động lực
• lặp lại định nghĩa
• kể lịch sử quy trình
• “best practices” chung chung mà Claude vốn đã biết

Công cụ dựng graph tùy chọn

Thư mục skill có render-graphs.js, dùng để trích các block dot từ SKILL.md và render sơ đồ SVG nếu máy đã cài graphviz. Đây là phần tùy chọn, chủ yếu hữu ích khi workflow của bạn có nhiều nhánh trạng thái hoặc các cổng review mà con người cần xem trực quan. Nó không phải điều kiện bắt buộc để dùng writing-skills skill, nhưng có thể giúp maintainer gỡ rối độ phức tạp của quy trình.

Câu hỏi thường gặp về skill writing-skills

writing-skills có đáng cài nếu tôi đã viết prompt tốt rồi không?

Có, nếu vấn đề của bạn là độ tin cậy chứ không phải tốc độ soạn thảo. Prompt thông thường có thể tạo ra một skill nhìn khá ổn rất nhanh. writing-skills phát huy giá trị khi bạn cần tin chắc rằng skill cuối cùng thực sự thay đổi hành vi của agent dưới áp lực.

writing-skills có thân thiện với người mới không?

Một phần thôi. Bản thân việc viết khá dễ tiếp cận, nhưng phương pháp này giả định bạn đã quen với lối tư duy kiểu TDD. Người mới làm Skill Authoring có thể cần đọc trước các tài liệu liên quan đến TDD trong repo, nếu không họ dễ hiểu nhầm workflow này là rườm rà không cần thiết.

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

Hãy bỏ qua writing-skills trong các trường hợp:

• skill đơn giản chỉ để tra cứu
• ghi chú dùng một lần, không nhằm tái sử dụng
• chủ đề không có cám dỗ thực tế nào khiến agent vi phạm hướng dẫn
• tình huống mà bạn không thể chạy bất kỳ test trước/sau nào

Trong các trường hợp đó, một workflow authoring nhẹ hơn thường là đủ.

writing-skills khác gì so với best practices về skill của Anthropic?

anthropic-best-practices.md tập trung vào cách viết skill sao cho ngắn gọn, dễ được phát hiện và tiết kiệm ngữ cảnh. writing-skills bổ sung thêm một lăng kính mạnh hơn về thay đổi hành vi: quan sát thất bại trước, rồi chỉ viết những gì sửa được thất bại đó. Hai tài liệu này bổ trợ cho nhau, không cạnh tranh nhau.

writing-skills có yêu cầu thêm tooling của repo không?

Không cần công cụ lớn nào để hưởng lợi từ phương pháp này. Phần quan trọng nhất là hướng dẫn testing và các ví dụ. Render graph chỉ là tùy chọn, và không có script hỗ trợ bắt buộc nào cho workflow authoring cốt lõi.

Tôi có thể dùng writing-skills để chỉnh sửa một skill sẵn có không?

Có. Thực tế đây còn là một trong những use case tốt nhất. Nếu skill đã tồn tại nhưng agent vẫn lờ đi hoặc dùng sai, writing-skills sẽ giúp bạn xác định đúng kiểu thất bại đang xảy ra, cắt bớt nội dung vô dụng, và viết lại những chỉ dẫn quan trọng nhất.

Cách cải thiện skill writing-skills

Hãy bắt đầu từ thất bại đã quan sát được, không phải từ tài liệu lý tưởng

Cách nhanh nhất để cải thiện kết quả từ writing-skills là mang vào bằng chứng thất bại. Nếu bạn chỉ mô tả quy trình lý tưởng, đầu ra thường sẽ trở nên chung chung. Nếu bạn cung cấp những lối tắt agent thực sự đã dùng, skill tạo ra sẽ sắc hơn và ngắn hơn.

Cung cấp pressure scenario mạnh hơn cho writing-skills

Scenario tốt phải tạo ra cám dỗ thật sự để bỏ qua skill. Hãy đưa vào:

• áp lực thời gian
• sự tự tin do kinh nghiệm trước đó
• sunk cost
• áp lực thẩm quyền từ con người
• cách đóng khung kiểu “cách sửa này quá rõ rồi”

Chính các điều kiện đó sẽ làm lộ ra chỗ nào trong chỉ dẫn của bạn còn quá mềm hoặc quá mơ hồ.

Ghi lại đúng nguyên văn các cách agent tự hợp lý hóa

Đừng tóm tắt thất bại thành kiểu “ignored the skill.” Hãy ghi lại đúng điều agent đã nói hoặc ngầm thể hiện:

• “This is a small change”
• “CI will catch it”
• “I already know this pattern”
• “Reading the skill would take too long”

Chính các rationalization đó cho bạn biết prompt writing-skills usage đã chỉnh sửa và câu chữ cuối cùng trong skill cần phải phản hồi trực diện vào đâu.

Siết câu chữ ở những điểm mức tuân thủ là bắt buộc

Nếu skill được tạo ra để ép hành vi không được phép bỏ qua, ngôn ngữ mơ hồ sẽ làm giảm hiệu lực. Hãy thay các gợi ý mềm bằng trigger rõ ràng và hành động bắt buộc cụ thể. Tài liệu persuasion rất hữu ích ở đây, nhưng nguồn cải thiện chính vẫn là độ cụ thể:

• khi nào phải nạp skill
• việc đầu tiên phải làm là gì
• điều gì tuyệt đối không được bỏ qua
• thế nào mới được tính là thành công

Loại bỏ nội dung không làm thay đổi hành vi

Một kiểu lỗi phổ biến trong đầu ra của writing-skills skill là giải thích quá nhiều. Nếu một đoạn văn không giúp cải thiện khả năng được phát hiện, mức tuân thủ hoặc việc test, hãy cắt nó đi. File best practices trong repo coi đây là quy tắc trung tâm là có lý do.

Lặp lại sau kết quả pass đầu tiên

Một lần chạy “GREEN” đầu tiên là chưa đủ nếu skill chỉ hoạt động trong điều kiện dễ. Hãy test lại bằng những prompt gắt hơn và các cách diễn đạt khác nhau. Tự hỏi xem skill còn hiệu quả không khi agent đang vội, rất chắc chắn về mình, hoặc đang cố bảo toàn phần việc đã làm xong.

Kết hợp writing-skills với một ví dụ đặc thù của repo

Nếu team của bạn có một workflow lặp lại thường xuyên, hãy đưa vào một ví dụ đã làm mẫu trong đúng domain của skill đích. Điều này thường cải thiện mức độ áp dụng tốt hơn so với việc thêm nhiều quy tắc trừu tượng. Hãy giữ ví dụ ngắn, đã được pressure-test, thay vì biến nó thành tài liệu bách khoa.

Cải thiện prompt bằng cách yêu cầu cấu trúc, không phải độ bóng bẩy

Khi gọi writing-skills, hãy yêu cầu:

• danh sách scenario
• phân tích thất bại
• dàn ý skill ngắn gọn
• các chỉnh sửa để bịt lỗ hổng

Đừng mở đầu bằng “make it polished” hay “make it comprehensive.” Những yêu cầu đó thường chỉ làm nội dung dài hơn mà không tăng mức tuân thủ.

Kiểm tra xem skill có thật sự nên tồn tại hay không

Một kết quả hữu ích từ tài liệu writing-skills guide là nhận ra có những chủ đề thực ra không cần thành skill. Nếu quy trình quá hiển nhiên, rủi ro thấp hoặc hiếm khi lặp lại, skill có thể chỉ làm tăng chi phí bảo trì mà không mang lại thêm bao nhiêu thay đổi hành vi. Kết luận như vậy hoàn toàn hợp lý, và còn giúp nâng chất lượng của repo.

Dùng writing-skills để refactor, không chỉ để tạo mới

Trường hợp dùng có giá trị cao nhất của writing-skills thường là refactor một skill đang có sau khi bạn đã thấy nó thất bại ngoài thực tế. Khi đó, phương pháp này không còn chỉ là viết tài liệu, mà trở thành một cách “behavior engineering” cho agent — và đó cũng chính là nơi repo này mang lại giá trị thực tế rõ nhất.