SimpleEnglish: bắt AI viết tài liệu rõ như sách hướng dẫn máy bay — cài đặt và dùng
Bài này là một góc nhìn khác về AminBlg/SimpleEnglish — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 ngắn, rõ, theo tinh thần chuẩn ASD-STE100 mà ngành hàng không dùng để viết sách hướng dẫn kỹ thuật. Bạn dùng nó khi cần AI viết README, quy trình, thông báo lỗi hay ghi chú phát hành mà người đọc không thể hiểu nhầm. Cài chỉ cần một dòng lệnh npx, không cần thư viện phụ thuộc.
SimpleEnglish là một agent skill (một thư mục hướng dẫn mà trợ lý AI đọc được) giúp AI viết tiếng Anh đơn giản, khô, rõ, theo kỷ luật của chuẩn ASD-STE100 Simplified Technical English. Đây là bộ ngôn ngữ có kiểm soát mà 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 sai một bước hướng dẫn.
Vấn đề nó giải quyết thì ai dùng AI viết tài liệu cũng gặp: câu chữ nghe như bài đăng LinkedIn. Nào là "leveraging robust architecture", nào là "seamlessly", dấu gạch dài khắp nơi, in đậm lung tung, mở bài chào hỏi, kết bài "hy vọng hữu ích". Skill này bắt AI bỏ hết những thứ đó. Mặc định nó viết dễ đọc cho người bình thường. Khi bạn nói rõ cần STE, nó chuyển sang chế độ nghiêm ngặt hơn.
Repo hiện có khoảng 4.393 sao và 192 fork, giấy phép MIT, viết chủ yếu bằng Python và vẫn được cập nhật trong 3 tháng gần đây. Điểm đáng giá nhất: một thư mục, không phụ thuộc thư viện, chạy được trong khoảng 30 agent đọc chuẩn Agent Skills, và tác giả công bố số liệu đo kèm file thô để bạn tự kiểm lại.
Lưu ý trước khi bắt đầu: skill này làm AI viết tiếng Anh. Nếu công việc của bạn là tài liệu tiếng Anh cho khách nước ngoài, đội kỹ thuật hoặc người dùng quốc tế, nó rất hợp. README không nói gì về tiếng Việt, nên mình không hứa nó hoạt động tương tự với tiếng Việt.
AminBlg/SimpleEnglish
Skill giúp AI viết tiếng Anh đơn giản, không thể hiểu sai, 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 thành hai "chế độ viết". Mỗi chế độ có bộ quy tắc riêng.
A.Quy tắc cho câu trả lời trong khung chat
Khi bạn hỏi AI một câu thường, skill ép câu trả lời gọn lại:
- Mặc định viết thành đoạn văn. Chỉ dùng danh sách hoặc bảng khi nội dung thật sự có dạng đó, và không in đậm. Bạn không còn phải đọc một bức tường định dạng quanh một đáp án một dòng.
- Câu đầu tiên trả lời thẳng câu hỏi. Không còn đoạn dạo đầu.
- Không dùng dấu gạch dài (em-dash) để ghép những nửa ý dở dang.
- Khi gặp thuật ngữ, giải thích nhanh bằng vài từ để bạn khỏi phải tra.
- Không viết tắt kiểu "don't", không mở bài, không kết bài kiểu "Great question!" hay "Hope this helps!".
B.Quy tắc cho tài liệu
Với README, quy trình vận hành, thông báo lỗi, ghi chú phát hành, skill dùng bộ quy tắc chặt hơn:
- Mỗi 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 đứng trước lệnh. Người đọc không bị "...nếu cờ này được bật" ở cuối câu khi đã lỡ chạy lệnh.
- Dùng thì đơn giản, câu chủ động.
- Bỏ should/would/may/might, những từ nói lấp lửng. 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 đảo qua lại giữa check, verify, confirm, validate.
- Giữ mạo từ và từ "that". STE là ngắn, không phải cộc lốc.
- Không in đậm đầu dòng, không đặt tiêu đề cho đoạn chỉ có hai câu.
- Nêu sự việc, không nêu mức độ quan trọng của nó. Tránh "crucial", "robust".
C.Hai chế độ: Plain và Strict
Plain là mặc định, gồm toàn bộ quy tắc ở trên. Strict thêm kỷ luật từ điển STE (file strict-vocabulary.md), và chỉ bật khi bạn nhắc tên STE, ASD-STE100 hoặc nói về tuân thủ chuẩn. Dù ở chế độ nào, câu trả lời trong chat vẫn ở dạng Plain.
D.Ví dụ trước và sau
Tác giả đưa một ví dụ thật. Câu gốc của Claude: "Leveraging sqlpipe's robust architecture, users can seamlessly synchronize their Postgres tables to S3 with minimal configuration overhead...". Sau khi nạp skill, nó thành: "sqlpipe copies your Postgres tables to S3. It needs one configuration file." Ngắn hơn, rõ hơn, không mất thông tin. Thêm nhiều ví dụ (README, runbook, báo cáo sự cố, thông báo lỗi, ghi chú phát hành) trong file examples/before-after.md của repo.
E.Số liệu đo
Tác giả công bố các con số tính lại từ file thô bằng python3 evals/check_numbers.py. Với các câu trả lời chat, phiên bản 2.0.1 giảm khoảng 95% lỗi định dạng nhìn thấy được (gạch dài, in đậm, tiêu đề, gạch đầu dòng) so với không dùng skill. Với tài liệu, mật độ vi phạm quy tắc giảm 78% (từ 4,09 xuống 0,91 trên 100 từ). Tác giả cũng tự nói thẳng: người chấm là các mô hình Claude chấm văn bản của Claude, nên có thể có thiên lệch, và các lượt đo tài liệu chỉ nên đọc là "ngang bằng hoặc tốt hơn", không phải bảng xếp hạng. Mình thấy việc tự nêu giới hạn như vậy là điểm cộng.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về yêu cầu, nên mình chỉ liệt kê những gì có ghi:
- Một agent đọc được chuẩn Agent Skills. README liệt kê Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode và khoảng 25 agent khác.
- Để dùng lệnh
npx skills add, bạn cần cónpx. Công cụ này đi kèm Node.js. README không nêu phiên bản Node cụ thể. - Nếu dùng plugin Codex hoặc hook phiên làm việc, README ghi rõ hook cần Node.js. Chi tiết nằm ở
src/hooks/README.mdtrong repo. - Muốn dùng plugin cho Claude Code, bạn cần Claude Code đã cài sẵn (lệnh
claude). - Muốn chạy bộ kiểm tra Python của tác giả (không bắt buộc): cần
python3. - README không nhắc yêu cầu về hệ điều hành, GPU, API key hay tài khoản riêng cho skill này. Bạn chỉ cần tài khoản và quyền dùng agent mà bạn đã có.
III.Cài đặt từng bước
- Mở terminalMở cửa sổ dòng lệnh trên máy có Node.js
- Cài skillChạy npx skills add AminBlg/SimpleEnglish
- (Tuỳ chọn) Cài pluginDùng plugin Claude Code hoặc Codex nếu muốn hook và output style
- Chọn output styleChỉ với Claude Code plugin: chọn simple-english:simple-english
- Thử dùngNhờ AI viết tài liệu hoặc nói rewrite this with simple-english
A.Mở terminal
Trên Windows, bạn mở PowerShell hoặc Windows Terminal. Trên macOS hoặc Linux, mở Terminal. Bạn không cần đứng trong thư mục dự án cụ thể để chạy lệnh cài bên dưới, nhưng nếu agent của bạn cài skill theo từng dự án thì nên mở terminal ngay trong thư mục dự án đó. README không nói rõ điểm này, nên bạn thử và kiểm tra ở bước sau.
B.Cách 1: cài skill cho bất kỳ agent nào
Đây là cách đơn giản nhất. Nó dùng skills CLI của vercel-labs:
npx skills add AminBlg/SimpleEnglishLệnh này tải skill về và đặt vào agent bạn đang dùng. README ghi rõ cách này chỉ cài skill, không cài hook phiên làm việc và không cài output style. Nên nếu bạn đặt outputStyle thành simple-english:simple-english mà chưa cài plugin, nó sẽ không có tác dụng gì. Đây là chỗ người mới hay vấp.
C.Cách 2: cài plugin Claude Code (có hook và output style)
Nếu bạn dùng Claude Code và muốn đủ bộ, chạy:
claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-englishDòng này gồm hai lệnh nối nhau bằng &&. Lệnh đầu thêm repo làm một "marketplace" plugin. Lệnh sau cài plugin tên simple-english từ marketplace đó. Nếu lệnh đầu lỗi thì lệnh sau sẽ không chạy.
Sau khi cài, output style có tên đầy đủ là simple-english:simple-english. README nhấn mạnh tên ngắn sẽ không nhận. Bạn chọn nó bằng lệnh /config trong Claude Code, mục Output style. Hoặc bạn thêm dòng sau vào file ~/.claude/settings.json:
{"outputStyle": "simple-english:simple-english"}Nếu file settings.json của bạn đã có nội dung khác, đừng dán đè cả file. Hãy thêm khoá outputStyle vào bên trong cặp ngoặc nhọn hiện có.
D.Cách 3: cài plugin Codex
Với OpenAI Codex, README ghi hai lệnh:
codex plugin marketplace add AminBlg/SimpleEnglish
codex plugin add simple-english@simple-englishLần chạy đầu tiên, Codex sẽ hỏi bạn có tin cậy hook không. Bạn đồng ý nếu bạn tin repo. Hook cần Node.js, chi tiết xem src/hooks/README.md.
E.Cách 4: agent không hỗ trợ skill
Nếu công cụ của bạn không có khái niệm skill, README hướng dẫn dán khối quy tắc trong file prompts/system-prompt.md vào system prompt, vào AGENTS.md hoặc .cursorrules. Cuối trang đó còn có bản rút gọn khoảng 60 token cho trường hợp giới hạn dung lượng. Để lấy file, bạn mở repo trên GitHub hoặc chạy:
git clone https://github.com/AminBlg/SimpleEnglish.gitRồi cd SimpleEnglish và mở file prompts/system-prompt.md.
Skill chỉ là chỉ một trang tin tức, không cần API key riêng. Nhưng AI của bạn vẫn tính phí theo gói hoặc token như bình thường. Hook trong plugin chạy lệnh trên máy bạn, nên hãy đọc tài liệu hook và chỉ đồng ý "tin cậy" khi bạn đã yên tâm.
IV.Kiểm tra đã chạy được chưa
README không có lệnh "kiểm tra cài đặt" riêng. Cách thử hợp lý theo đúng tư liệu là dùng thử bằng câu lệnh mà tác giả gợi ý: nhờ agent viết một tài liệu kỹ thuật bất kỳ, hoặc nói "rewrite this with simple-english".
Bạn có thể dán một đoạn văn kiểu quảng cáo rồi yêu cầu:
Rewrite this with simple-english:
Leveraging our robust platform, users can seamlessly manage their invoices with minimal configuration overhead.Nếu skill đang hoạt động, bạn sẽ thấy câu trả lời ngắn hơn, không có "leveraging", "seamlessly", không có gạch dài, và câu đầu đi thẳng vào việc. Nếu AI vẫn viết bay bướm như cũ, xem phần lỗi thường gặp bên dưới.
Với plugin Claude Code, bạn có thể mở /config, vào mục Output style và xem simple-english:simple-english có xuất hiện trong danh sách không. Nếu có, plugin đã được nhận.
Nếu bạn đã clone repo và có Python, tác giả còn cho hai lệnh kiểm tra nội bộ của chính repo (dành cho người đóng góp):
python3 evals/ste_lint.py --self-test
python3 evals/check_numbers.pyHai lệnh này kiểm tra bộ linter và các con số công bố trong repo, không phải kiểm tra việc cài skill vào agent của bạn.
V.Dùng vào việc thật
A.Viết lại README cho một dự án mã nguồn mở
Bạn là lập trình viên mới, vừa viết xong một công cụ nhỏ và muốn README tiếng Anh cho cộng đồng quốc tế. Bản nháp AI đưa ra thường dài và đầy lời quảng cáo. Bạn dán bản nháp vào và nói:
Rewrite this README with simple-english. Keep every fact. Max 20 words per instruction.Kết quả: mỗi bước cài đặt là một câu ngắn, điều kiện đứng trước lệnh, không còn từ khoa trương. Người đọc không giỏi tiếng Anh vẫn làm theo được.
Cho AI một con số cụ thể thay vì lời khuyên chung chung, nó sẽ làm theo.
Ông T
Đây cũng là lý do README của repo nêu: "viết rõ ràng" chỉ là ý kiến, còn "không câu nào quá 20 từ" là một đặc tả mà agent làm theo được.
B.Thông báo lỗi và hướng dẫn hỗ trợ khách hàng
Bạn làm cho một công ty có sản phẩm bán ra nước ngoài. Thông báo lỗi trong ứng dụng đang viết kiểu "Oops! Something went wrong". Bạn đưa danh sách thông báo cho AI đã nạp skill và yêu cầu viết lại. Mỗi thông báo sẽ nêu việc gì đã xảy ra và người dùng phải làm gì tiếp. Ví dụ trong README cho thấy cách này: thay vì nói chung chung, câu viết lại nêu rõ "nếu thông tin đăng nhập sai thì S3 từ chối tải lên bằng lỗi quyền truy cập".
C.Runbook và báo cáo sự cố cho đội kỹ thuật
Bạn là dev trực hệ thống. Lúc 2 giờ sáng, không ai muốn đọc một đoạn văn dài mà không biết phải bấm gì trước. Bạn nhờ AI viết runbook theo skill: từng bước đánh số, mỗi bước một hành động, điều kiện đặt trước lệnh, mỗi thuật ngữ dùng đúng một nghĩa. Đây chính là loại tài liệu mà chuẩn STE ra đời để phục vụ. Repo có sẵn ví dụ runbook và báo cáo sự cố trong examples/before-after.md.
D.Ghi chú phát hành và bản chuẩn STE nghiêm ngặt
Nếu bạn viết tài liệu cho một ngành quy định chặt và muốn gần chuẩn STE nhất, hãy nói rõ trong yêu cầu rằng bạn cần ASD-STE100 để bật chế độ Strict:
Write the release notes in Strict mode, ASD-STE100.Một điều cần nói thẳng: README khẳng định kết quả không phải là văn bản được chứng nhận STE, vì ASD không chứng nhận công cụ nào. Strict chỉ "gần" chuẩn hơn. Nếu bạn cần tuân thủ chính thức, hãy dùng bản chuẩn gốc miễn phí do ASD phát hành và người kiểm tra có chuyên môn.
VI.Lỗi hay gặp và cách xử lý
A.Đặt output style nhưng không thấy thay đổi gì
Nếu bạn cài bằng npx skills add rồi đặt outputStyle, nó sẽ không có tác dụng. Cách này chỉ cài skill, không cài output style. Hãy cài thêm plugin Claude Code ở cách 2. Ngoài ra phải dùng tên đầy đủ simple-english:simple-english, tên ngắn không nhận.
B.Lệnh npx hoặc claude báo "not found"
Thường là máy chưa cài Node.js hoặc chưa cài Claude Code, hoặc terminal chưa nhận lệnh sau khi cài. Hãy đóng terminal, mở lại rồi thử. Nếu vẫn lỗi, kiểm tra xem công cụ đã cài đúng chưa trước khi chạy lại lệnh của repo.
C.AI vẫn viết dài dòng như cũ
Có thể skill chưa được agent nạp. Hãy nói thẳng trong yêu cầu: "rewrite this with simple-english", như README gợi ý. Nếu agent của bạn không hỗ trợ skill, dùng cách 4: dán khối quy tắc từ prompts/system-prompt.md vào system prompt hoặc file cấu hình của agent.
D.Codex hỏi tin cậy hook và hook không chạy
Codex yêu cầu bạn xác nhận tin cậy hook trước lần chạy đầu. Nếu bạn từ chối, hook sẽ không chạy. Hook còn cần Node.js, nên hãy kiểm tra máy đã có Node. Xem thêm src/hooks/README.md.
E.Kết quả nghe "máy móc" hoặc quá cụt
Đây là hành vi có chủ đích. Văn bản STE phẳng và khó đọc sai, giống sách hướng dẫn Airbus. Với tài liệu kỹ thuật thì đó là mục tiêu, nhưng với bài blog hay thư gửi khách thì bạn nên tắt skill hoặc chỉ dùng nó ở bước sửa cuối. README tự nói: giữ giọng riêng cho blog của bạn.
VII.Có nên dùng không
Điểm mạnh. Cài một dòng, không phụ thuộc thư viện, giấy phép MIT. Chạy trên rất nhiều agent. Quy tắc cụ thể, kiểm đo được, không chỉ là lời khuyên "viết rõ ràng". Tác giả công bố số liệu kèm file thô và nói rõ giới hạn của phép đo. Repo vẫn được cập nhật gần đây và có hơn 4.000 sao.
Giới hạn. Nó dành cho tiếng Anh. Kết quả không phải chuẩn STE được chứng nhận. Bộ số liệu chủ yếu đo trên mô hình Claude với người chấm cũng là Claude, nên có thể lệch. Với tài liệu, phép đo chỉ một lượt mỗi ô và tác giả nói độ dao động khoảng 0,5, nên đừng coi nó là bảng xếp hạng. Repo cũng không kèm nội dung từ điển STE, vì chuẩn cấm tái tạo khi chưa có phép của ASD. Muốn kiểm từ vựng, bạn phải tự tải bản PDF miễn phí và dùng công cụ trích xuất trong tools/ste-dictionary/.
Khi nào chọn cách khác. Nếu bạn viết nội dung marketing, bài blog, thư cá nhân, nơi giọng văn quan trọng hơn độ chính xác, thì skill này sẽ làm văn bản khô đi. Nếu bạn cần chứng nhận STE chính thức, hãy dùng công cụ và người chuyên về STE. Nếu bạn viết tài liệu tiếng Việt, README chưa nói skill có hiệu quả thế nào, nên hãy thử với đoạn nhỏ trước.
Với README, runbook, thông báo lỗi và ghi chú phát hành bằng tiếng Anh, mình thấy đây là một công cụ đáng thử: cài nhanh, thử ngay trong vài phút, và gỡ cũng dễ.
Câu hỏi thường gặp
SimpleEnglish có miễn phí không?
Có. Repo dùng giấy phép MIT cho toàn bộ nội dung. Skill không yêu cầu API key riêng theo README. Bạn vẫn trả chi phí cho agent hoặc mô hình AI mà bạn đang dùng, nếu có.
Cần GPU hay máy mạnh không?
Tư liệu không nhắc yêu cầu phần cứng. Skill chỉ là thư mục chỉ dẫn mà agent đọc, README ghi rõ là một thư mục và không có thư viện phụ thuộc. Phần tính toán do agent hoặc mô hình AI của bạn đảm nhiệm.
Chạy được trên Windows không?
README không ghi rõ theo hệ điều hành. Các lệnh cài đặt dùng npx, claude và codex, nên cần có Node.js và agent tương ứng trên máy. Hook cần Node.js. Chi tiết nằm ở src/hooks/README.md trong repo.
Dùng được với những agent nào?
README liệt kê Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode và khoảng 25 agent khác đọc chuẩn Agent Skills. Với agent không hỗ trợ skill, bạn dán khối quy tắc từ prompts/system-prompt.md vào system prompt, AGENTS.md hoặc .cursorrules.
Văn bản tạo ra có phải chuẩn ASD-STE100 chính thức không?
Không. README khẳng định không có công cụ nào được ASD chứng nhận. Chế độ Strict chỉ tiến gần chuẩn hơn. Repo cũng không kèm nội dung từ điển STE và nói rõ đây là dự án không chính thức, không liên kết với ASD.
Khác gì việc chỉ nhắc AI "viết cho rõ ràng"?
Theo tác giả, "rõ ràng" là ý kiến còn "không câu nào quá 20 từ" là đặc tả mà agent làm theo được. Skill gói sẵn các quy tắc đo đếm được, như giới hạn độ dài câu, điều kiện đứng trước lệnh, không dùng từ lấp lửng. Nhờ vậy kết quả ổn định hơn một lời nhắc chung chung.
Skill có làm AI viết tiếng Việt được không?
README chỉ nói về tiếng Anh, dựa trên chuẩn Simplified Technical English. Chưa có thông tin về hiệu quả với tiếng Việt, nên bạn nên thử với một đoạn nhỏ trước khi dùng cho tài liệu quan trọng.


