SimpleEnglish: AI viết tài liệu rõ ràng như sách hướng dẫn kỹ thuật — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
SimpleEnglish là một agent skill bắt các mô hình AI viết tiếng Anh đơn giản, câu ngắn, dễ hiểu, theo chuẩn ASD-STE100 mà ngành hàng không dùng cho sách hướng dẫn. Bạn dùng nó để viết README, quy trình, thông báo lỗi, ghi chú phát hành mà không bị giọng văn quảng cáo của AI. Cài chỉ cần một dòng lệnh npx, rất nhẹ và không phụ thuộc thư viện nào.
SimpleEnglish là một agent skill: một thư mục chỉ dẫn để AI (Claude Code, Cursor, Codex, Gemini CLI…) viết tiếng Anh đơn giản, ngắn, chính xác. Nó dựa trên ASD-STE100 Simplified Technical English, bộ quy tắc ngành hàng không dùng từ năm 1983 để một thợ máy đang mệt cũng không thể đọc nhầm hướng dẫn.
Vấn đề nó giải quyết rất quen. AI hay viết như một bài đăng LinkedIn: “leveraging robust architecture”, “seamlessly”, “crucial”, gạch đầu dòng và chữ đậm khắp nơi, câu mở đầu “Great question!”. Đọc xong vẫn không biết phải làm gì. Skill này ép AI viết kiểu sách hướng dẫn máy bay: câu trả lời nằm ngay câu đầu, mỗi câu một ý, từ nào dùng nghĩa đó.
Bạn nên dùng nếu làm việc với tài liệu tiếng Anh: lập trình viên viết README, nhân viên văn phòng soạn quy trình gửi đối tác nước ngoài, chủ shop viết hướng dẫn sử dụng sản phẩm. Điểm đáng giá nhất: tác giả công bố số liệu đo được và cho chạy lại bằng script trong repo. Repo hiện có khoảng 4.393 sao và 192 fork, giấy phép MIT, vẫn được cập nhật trong 3 tháng gần đây.
AminBlg/SimpleEnglish
Skill giúp AI viết tiếng Anh đơn giản, câu ngắn, không sáo rỗng, theo chuẩn ASD-STE100 của ngành hàng không. Chạy trên Claude Code, Cursor, Codex, Gemini CLI.
I.SimpleEnglish làm được gì
Skill chia làm hai “chế độ viết”. Phần chung là các quy tắc cho câu trả lời trong khung chat, phần riêng là quy tắc cho tài liệu.
A.Quy tắc cho câu trả lời trong chat
Mặc định AI sẽ viết văn xuôi, không in đậm, không bọc câu trả lời một dòng trong cả đống định dạng. Danh sách hoặc bảng chỉ xuất hiện khi nội dung thật sự có dạng đó. Câu đầu tiên trả lời thẳng câu hỏi, không có đoạn dạo đầu. Không dùng dấu gạch dài (em-dash), không viết tắt kiểu “don't”, không có câu mở đầu hay kết thúc xã giao. Gặp thuật ngữ, AI giải thích ngắn trong vài từ để bạn khỏi phải tra.
Lợi ích thực tế: bạn đọc được nhanh hơn, ít phải cuộn màn hình, và ít bị “nhiễu” bởi định dạng thừa.
B.Quy tắc cho tài liệu
Áp dụng cho README, runbook, thông báo lỗi, ghi chú phát hành. Một số quy tắc đáng chú ý:
- Câu hướng dẫn tối đa 20 từ, câu mô tả tối đa 25 từ. Hết cảnh câu dài lê thê.
- Điều kiện đặt trước lệnh. Viết “Nếu cờ này bật, hãy làm X” thay vì “Làm X… nếu cờ này bật”, vì người đọc có thể đã chạy lệnh trước khi đọc tới điều kiện.
- Dùng thì đơn giản, câu chủ động. Tránh “has been updated”.
- Bỏ các từ nước đôi như should, would, may, might. Các từ can, will, must vẫn được dùng.
- Một từ chỉ một nghĩa trong cả tài liệu. Không lúc thì check, lúc thì verify, lúc thì confirm cho cùng một việc.
- Giữ mạo từ và từ “that”. STE là ngắn gọn chứ không phải cộc lốc.
- Nêu sự thật, đừng nêu tầm quan trọng của nó. Nói “S3 từ chối tải lên nếu thông tin đăng nhập sai” thay vì “điều này rất quan trọng”.
C.Hai chế độ: Plain và Strict
Chế độ Plain là mặc định, áp dụng tất cả quy tắc trên. Chế độ Strict thêm kỷ luật về từ điển STE, bật khi bạn nhắc tên STE, ASD-STE100 hoặc yêu cầu tuân thủ chuẩn. Câu trả lời trong chat luôn ở chế độ Plain, kể cả khi bạn bật Strict.
D.Có sẵn ví dụ, kiểm thử và công cụ đo
Repo có thư mục examples/ với nhiều bản viết lại (README, runbook, báo cáo sự cố, thông báo lỗi, ghi chú phát hành), thư mục evals/ chứa số liệu đo và công cụ kiểm tra, và tools/ chứa công cụ tạo danh sách từ từ chính bản PDF chuẩn của bạn.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về yêu cầu, và đó là điểm tốt: skill là một thư mục, không có thư viện phụ thuộc.
- Một agent đọc được chuẩn Agent Skills: Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode và khoảng 25 agent khác.
- Lệnh cài bằng
npx, nên máy bạn cần có Node.js. README không ghi phiên bản cụ thể. - Node.js cũng cần cho các hook (phần chạy tự động khi mở phiên làm việc) của bản plugin. Chi tiết nằm ở
src/hooks/README.md. - Nếu dùng Claude Code hoặc Codex, bạn cần cài sẵn hai công cụ đó.
- README không nhắc tới API key, GPU hay hệ điều hành cụ thể. Python chỉ xuất hiện ở các script kiểm tra trong
evals/, bạn không cần nó để dùng skill.
III.Cài đặt từng bước
- Mở terminalMở terminal ở bất kỳ thư mục nào bạn muốn
- Chọn cách càiCài skill bằng npx, hoặc cài plugin cho Claude Code / Codex
- Bật output styleChỉ với plugin Claude Code: chọn simple-english:simple-english
- Tin cậy hookChỉ với Codex: đồng ý tin cậy hook ở lần chạy đầu
- Thử một yêu cầuNhờ AI viết tài liệu hoặc nói “rewrite this with simple-english”
Có ba cách cài. Chọn một cách hợp với công cụ bạn đang dùng.
A.Cách 1: cài skill cho bất kỳ agent nào
Mở terminal (trên Windows là PowerShell hoặc Terminal, trên macOS là Terminal) rồi chạy:
npx skills add AminBlg/SimpleEnglishLệnh này dùng công cụ skills CLI để thêm skill vào agent của bạn. Chỉ có skill được cài. Hook của phiên làm việc và output style thì không. Vì vậy nếu bạn đặt outputStyle thành simple-english:simple-english mà chưa cài plugin thì sẽ không có tác dụng gì. Đây là chỗ người mới dễ vấp nhất.
B.Cách 2: cài plugin cho Claude Code
Cách này có thêm hook và output style. Chạy một dòng:
claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-englishDấu && nghĩa là lệnh thứ hai chỉ chạy khi lệnh thứ nhất thành công. Lệnh đầu thêm repo làm nguồn plugin, lệnh sau cài plugin tên simple-english.
Output style tên đầy đủ là simple-english:simple-english. Tên ngắn không hoạt động. Bạn chọn nó trong Claude Code bằng /config, mục Output style. Hoặc ghi vào file ~/.claude/settings.json:
{"outputStyle": "simple-english:simple-english"}Nếu file đã có nội dung khác, hãy thêm dòng này vào đúng chỗ trong JSON hiện có, đừng dán đè cả file.
C.Cách 3: cài plugin cho Codex
codex plugin marketplace add AminBlg/SimpleEnglish
codex plugin add simple-english@simple-englishCodex sẽ hỏi bạn có tin cậy hook không trước lần chạy đầu tiên. Hook cần Node.js, xem thêm ở src/hooks/README.md trong repo.
D.Nếu agent của bạn chưa hỗ trợ skill
README hướng dẫn: dán khối quy tắc trong prompts/system-prompt.md vào system prompt, vào file AGENTS.md hoặc .cursorrules. Cuối trang đó có bản rút gọn 60 token cho trường hợp bạn bị giới hạn độ dài. README không ghi thêm bước nào khác, nên hãy mở file này trong repo để lấy đúng nội dung.
Skill này chỉ là bộ chỉ một trang tin tức, README không nói nó cần API key riêng. Tuy vậy agent bạn dùng (Claude Code, Codex…) vẫn tính phí hoặc hạn mức theo gói của chính nó. Skill chỉ làm câu trả lời ngắn hơn, nên thường không làm tốn thêm.
IV.Kiểm tra đã chạy được chưa
README không có lệnh kiểm tra riêng cho phần cài đặt. Cách kiểm tra đơn giản nhất theo đúng hướng dẫn của tác giả là dùng thử: sau khi cài, hãy nhờ AI viết một đoạn tài liệu kỹ thuật bất kỳ, hoặc gõ “rewrite this with simple-english” kèm đoạn văn của bạn.
Bạn sẽ thấy khác biệt rõ ở ba điểm. Câu đầu trả lời thẳng vấn đề. Câu ngắn, ít từ hoa mỹ như “seamlessly” hay “robust”. Gần như không có chữ đậm, tiêu đề hay gạch đầu dòng thừa. Ví dụ trong README: câu gốc “Leveraging sqlpipe's robust architecture, users can seamlessly synchronize…” được viết lại thành “sqlpipe copies your Postgres tables to S3. It needs one configuration file.”
Nếu cài plugin Claude Code và muốn kiểm tra output style, vào /config và xem mục Output style có tên `simple-english:simple-english hay không. Nếu AI vẫn viết bay bổng như cũ, xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
A.Lập trình viên viết README cho dự án
Bạn vừa viết xong một công cụ và cần README tiếng Anh. Sau khi cài skill, bạn nhờ agent:
Write a README for this project. Use simple-english.Kết quả: README ngắn, mỗi bước một câu dưới 20 từ, điều kiện đặt trước lệnh, không có từ như “crucial” hay “seamless”. Người đọc nước ngoài, kể cả người không giỏi tiếng Anh, dễ làm theo hơn nhiều.
B.Nhân viên văn phòng soạn quy trình gửi đối tác nước ngoài
Bạn có một bản quy trình đóng gói hàng viết lủng củng và cần gửi đối tác. Dán bản nháp vào agent rồi nói:
Rewrite this with simple-english.Skill giữ nguyên ý, nhưng cắt câu dài, đổi bị động thành chủ động, và dùng một từ duy nhất cho một việc. Kết quả là bản quy trình mà người đọc khó hiểu nhầm, đúng tinh thần sách hướng dẫn hàng không.
Hướng dẫn tốt là hướng dẫn mà người đọc đang mệt cũng không thể hiểu sai.
Ông T
C.Chủ shop viết hướng dẫn sử dụng và thông báo lỗi
Bạn bán sản phẩm ra nước ngoài, cần phần hướng dẫn dùng và thông báo lỗi trong ứng dụng. Bạn nhờ agent viết thông báo lỗi theo kiểu chế độ tài liệu. Repo có ví dụ về thông báo lỗi và ghi chú phát hành trong examples/before-after.md để bạn tham khảo giọng văn. Kết quả: thông báo nói rõ chuyện gì xảy ra và cần làm gì, không dùng câu mơ hồ kiểu “something may have gone wrong”.
D.Đội kỹ thuật cần tài liệu theo chuẩn STE
Nếu công ty bạn làm tài liệu kỹ thuật nghiêm túc, hãy nói rõ với agent rằng bạn cần ASD-STE100 hoặc Strict mode. Skill sẽ thêm kỷ luật từ vựng theo strict-vocabulary.md. README nói rõ: không công cụ nào được ASD chứng nhận, nên Strict mode chỉ là “gần chuẩn”. Với các phán quyết ở mức từng từ, bạn cần xem chính bản chuẩn chính thức (tải miễn phí). Repo cũng có công cụ trong tools/ste-dictionary/ để tạo danh sách từ từ bản PDF Issue 9 của chính bạn.
VI.Lỗi hay gặp và cách xử lý
A.Đặt output style nhưng không thấy tác dụng
Nguyên nhân thường là bạn chỉ cài skill bằng npx skills add. Cách đó không cài output style. Hãy cài plugin Claude Code bằng hai lệnh claude plugin... ở trên. Cũng kiểm tra bạn gõ đúng tên đầy đủ simple-english:simple-english, vì tên ngắn không hoạt động.
B.Lệnh npx báo không tìm thấy
Máy chưa có Node.js, hoặc terminal chưa nhận đường dẫn. Cài Node.js từ trang chính thức, đóng rồi mở lại terminal và chạy lại. README không ghi phiên bản Node cụ thể, nên bạn dùng bản ổn định mới.
C.Codex hỏi tin cậy hook, hook không chạy
Codex yêu cầu bạn tin cậy hook trước lần chạy đầu. Nếu bạn từ chối, hook không chạy. Hook cần Node.js, nên cũng kiểm tra Node đã cài chưa. Chi tiết ở src/hooks/README.md.
D.Agent không hỗ trợ skill
Nếu công cụ của bạn không đọc được skill, đừng cố cài. Dán khối quy tắc trong prompts/system-prompt.md vào system prompt, AGENTS.md hoặc .cursorrules.
E.Văn bản nghe hơi “máy móc”
Đây là cố ý. README nói tài liệu sẽ nghe phẳng như sách hướng dẫn Airbus, và với tài liệu thì đó chính là mục tiêu. Nếu bạn muốn giữ giọng riêng cho bài blog hay bài quảng cáo, đừng bật skill cho các việc đó, hoặc chỉ dùng cho phần tài liệu kỹ thuật.
VII.Có nên dùng không
Điểm mạnh lớn nhất là cách tiếp cận có thể kiểm chứng. Thay vì bảo AI “viết rõ ràng” (một ý kiến chủ quan), skill đưa ra quy tắc cụ thể như “không câu nào quá 20 từ”, và agent làm theo quy tắc tốt hơn làm theo cảm tính. Tác giả công bố số đo và cho chạy lại bằng python3 evals/check_numbers.py. Với câu trả lời trong chat, bản 2.0.1 giảm khoảng 95% lỗi định dạng hiển thị (từ 218 xuống 11) so với không dùng skill. Với tài liệu, số lỗi trên mỗi 100 từ giảm khoảng 78%.
Nhưng bạn nên đọc kỹ các giới hạn mà chính tác giả nêu. Các phép đo chủ yếu chạy trên Claude, và người chấm cũng là mô hình Claude, nên có thể có thiên lệch. Số liệu về câu trả lời chat đến từ bản 2.0.1; README nói chưa có lượt đo cho các bản mới hơn. Một lần chạy cho tài liệu dao động khoảng 0,5, nên các số đó nên đọc là “tương đương hoặc tốt hơn” chứ không phải bảng xếp hạng chính xác. Ngoài ra bộ kiểm tra tự động chỉ đo các quy tắc cơ học, không thấy được việc chọn từ.
Nó cũng không biến văn bản của bạn thành văn bản được chứng nhận STE. Và nó viết cho tiếng Anh. Tài liệu README không nói gì về tiếng Việt, nên đừng kỳ vọng nó áp dụng cho tiếng Việt.
Nên chọn nó khi bạn cần tài liệu, hướng dẫn, thông báo lỗi bằng tiếng Anh mà người đọc quốc tế hiểu ngay. Nên chọn cách khác khi bạn cần giọng văn cá tính (blog, quảng cáo, kể chuyện), hoặc cần tài liệu được chứng nhận chính thức. Vì cài đặt chỉ một dòng, MIT, không phụ thuộc thư viện, bạn thử mất vài phút là biết có hợp hay không.
Câu hỏi thường gặp
SimpleEnglish có miễn phí không?
Có. Repo dùng giấy phép MIT, nên bạn dùng, sửa và chia sẻ tự do. Tư liệu không nói skill cần API key riêng; chi phí chỉ phát sinh từ agent mà bạn đang dùng (như Claude Code hay Codex) theo gói của chính nó.
SimpleEnglish chạy được trên những công cụ nào?
Skill chạy trên mọi agent đọc chuẩn Agent Skills: Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode và khoảng 25 agent khác. Plugin có hook và output style dành riêng cho Claude Code và Codex. Với agent không hỗ trợ skill, bạn dán khối quy tắc trong prompts/system-prompt.md vào system prompt, AGENTS.md hoặc .cursorrules.
Có cần GPU hay cài thêm thư viện không?
Không. README ghi rõ đây là một thư mục, không có thư viện phụ thuộc. Bạn chỉ cần Node.js để chạy lệnh npx và các hook của plugin. Python chỉ dùng cho các script đo kiểm trong thư mục evals.
Dùng skill này thì tài liệu có được chứng nhận STE không?
Không. README nói rõ không công cụ nào được chứng nhận, vì ASD không chứng nhận công cụ. Chế độ Strict giúp văn bản gần chuẩn hơn, còn các phán quyết ở mức từng từ nằm trong bản chuẩn chính thức mà bạn có thể tải miễn phí.
Vì sao không chỉ bảo AI “viết rõ ràng” cho nhanh?
Theo tác giả, “rõ ràng” là một ý kiến, còn “không câu nào quá 20 từ” là một đặc tả mà agent làm theo được. Skill biến cảm tính thành quy tắc cụ thể, có thể kiểm tra được. Nhờ đó kết quả ổn định hơn giữa các lần viết.
Skill này có làm văn bản nghe máy móc không?
Có thể, và README thừa nhận điều đó: tài liệu sẽ nghe phẳng như sách hướng dẫn Airbus, không thể đọc nhầm. Với tài liệu kỹ thuật thì đó là mục tiêu. Nếu muốn giữ giọng văn riêng như viết blog, bạn không nên bật skill cho việc đó.
Skill có dùng được cho tiếng Việt không?
Chưa có thông tin. Tư liệu của repo chỉ nói về tiếng Anh đơn giản theo chuẩn ASD-STE100, không nhắc tới tiếng Việt hay ngôn ngữ khác.


