# SimpleEnglish: bắt AI viết tài liệu ngắn, rõ như sách hướng dẫn máy bay — cài và dùng

> SimpleEnglish là một agent skill (MIT, viết bằng Python) bắt AI viết tiếng Anh đơn giản, câu ngắn, theo tinh thần chuẩn ASD-STE100 của ngành hàng không. Bạn dùng nó để README, runbook, thông báo lỗi hay release notes do AI viết bớt rườm rà. Cài chỉ cần một dòng lệnh npx, nên không khó.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-24 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/simpleenglish-ai-viet-tai-lieu-ngan-gon-de-hieu-ste100

SimpleEnglish là một agent skill: một thư mục hướng dẫn mà AI đọc để viết tiếng Anh đơn giản, rõ nghĩa, theo kỷ luật của ASD-STE100 Simplified Technical English. Đây là bộ tiếng Anh 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 nhầm hướng dẫn. Repo hiện có khoảng 4386 sao và 191 fork, giấy phép MIT.

Vấn đề nó giải quyết quen thuộc với ai hay nhờ AI viết tài liệu. AI thường viết kiểu bài đăng LinkedIn: nhiều chữ "mạnh mẽ", "liền mạch", gạch đầu dòng, in đậm, gạch ngang dài. Đọc xong vẫn chưa biết phải làm gì. Skill này ép AI viết câu ngắn, trả lời ngay câu đầu, bỏ lời chào đưa đẩy và bỏ từ hoa mỹ.

Ai nên dùng? Lập trình viên viết README, runbook, thông báo lỗi. Người làm văn phòng hay soạn quy trình, hướng dẫn nội bộ bằng tiếng Anh. Ai làm việc với đối tác nước ngoài mà tiếng Anh không phải thế mạnh cũng hưởng lợi, vì văn bản ngắn và phẳng thì dễ đọc và dễ dịch hơn. Đ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, thay vì chỉ hứa "viết hay hơn".

```repo
- repo | AminBlg/SimpleEnglish
- kind | Skill
- desc | Skill giúp AI viết tiếng Anh đơn giản, câu ngắn, khó hiểu nhầm theo chuẩn ASD-STE100. Dùng được với Claude Code, Cursor, Codex, Gemini CLI và nhiều agent khác.
- stars | 4.4k
- lang | Python
- license | MIT
```

## SimpleEnglish làm được gì

Skill chia thành hai kiểu viết, và biết lúc nào dùng kiểu nào.

**Kiểu trả lời chat.** Khi bạn hỏi AI một câu, skill làm cho câu trả lời gọn lại:

- Viết thành đoạn văn thường. 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 đỡ phải đọc một đống định dạng quanh một đáp án một dòng.
- Câu đầu tiên là câu trả lời. Không mào đầu.
- Không dùng gạch ngang dài (em-dash).
- Gặp thuật ngữ thì giải thích ngắn trong vài từ, bạn khỏi phải tra.
- Không viết tắt kiểu rút gọn (contractions), không câu mở đầu hay câu kết kiểu "Great question!" hoặc "Hope this helps!".

**Kiểu viết tài liệu.** Áp dụng cho docs, README, runbook, thông báo lỗi, release notes:

- 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âu dài lê thê.
- Điều kiện đặt trước lệnh. Người đọc không thực hiện lệnh trước khi biết điều kiện.
- Dùng thì đơn giản, câu chủ động.
- Bỏ should, would, may, might (những từ nói giảm nói tránh). Giữ can, will, must.
- Một từ chỉ một nghĩa trong cả tài liệu. Không lúc thì check, lúc verify, lúc confirm cho cùng một việc.
- Giữ mạo từ và "that". Văn bản ngắn nhưng không cộc lốc.
- Không in đậm ở đầu ý, không đặt tiêu đề cho đoạn chỉ có hai câu.
- Nêu sự thật, không nêu tầm quan trọng của nó. Tránh "crucial", "robust".

**Hai chế độ.** Chế độ Plain là mặc định, gồm tất cả các quy tắc trên. Chế độ Strict thêm kỷ luật từ điển STE, bật khi bạn nhắc đến STE, ASD-STE100 hoặc yêu cầu tuân thủ. Phần trả lời chat luôn ở Plain, kể cả khi bạn bật Strict.

Ví dụ trong README: câu gốc của AI là "Leveraging sqlpipe's robust architecture, users can seamlessly synchronize their Postgres tables to S3...". Sau khi nạp skill, nó thành "sqlpipe copies your Postgres tables to S3. It needs one configuration file." Ngắn hơn, và biết ngay phải làm gì.

## Cần chuẩn bị gì

Tư liệu của repo nói khá ít, nên mình chỉ nêu đúng những gì 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.
- Không cần cài thư viện phụ cho skill. README ghi "One folder, no dependencies".
- Nếu dùng cách cài bằng plugin cho Claude Code hoặc Codex và muốn có session hook thì cần Node.js. README nói hook cần Node.js và chi tiết nằm trong `src/hooks/README.md`.
- Cách `npx skills add` chạy qua npx nên bạn cần có Node.js/npm trên máy. README không nói rõ phiên bản, nên mình không đoán.
- README không nhắc đến API key riêng, GPU hay hệ điều hành cụ thể cho skill. Bạn chỉ cần tài khoản/agent mà bạn đang dùng sẵn.

```note
Skill chỉ là tệp hướng dẫn cho AI, nhưng agent của bạn vẫn tính phí theo gói hoặc API bạn đang dùng. Skill dài khoảng 1.700 token theo README, nên mỗi lần nạp sẽ tốn thêm một ít ngữ cảnh.
```

## Cài đặt từng bước

```steps
- Chọn cách cài | Chỉ cần skill, hay cần cả session hook và output style
- Cài skill cho mọi agent | Chạy một lệnh npx skills add
- Hoặc cài plugin Claude Code | Có thêm hook và output style
- Hoặc cài plugin Codex | Có thêm hook, cần tin cậy hook lần đầu
- Chọn output style (Claude Code) | Dùng /config hoặc sửa settings.json
```

### Chọn cách cài phù hợp

README đưa ra ba đường. Cách đơn giản nhất là cài skill bằng skills CLI, chạy được với mọi agent. Nếu bạn dùng Claude Code hoặc Codex và muốn thêm session hook, hãy cài bản plugin. Chưa chắc thì cứ bắt đầu với cách đầu tiên, sau này nâng lên plugin cũng được.

### Cách 1: cài skill cho mọi agent

Mở terminal (PowerShell hoặc Terminal đều được) ở bất kỳ thư mục nào, rồi chạy:

```bash
npx skills add AminBlg/SimpleEnglish
```

Lệnh này dùng skills CLI để lấy skill từ repo về cho agent của bạn. Lưu ý quan trọng: cách này chỉ cài skill. Nó không cài session hook và output style. Nếu bạn đặt `outputStyle` thành `simple-english:simple-english` mà không cài plugin thì không có tác dụng gì.

### Cách 2: plugin cho Claude Code

Cách này cài cả skill, session hook và output style:

```bash
claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-english
```

Dấ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 vào danh sách marketplace, lệnh sau cài plugin có tên `simple-english` từ marketplace đó. Nếu terminal của bạn không hiểu `&&`, chạy hai lệnh riêng từng dòng.

### Cách 3: plugin cho Codex

```bash
codex plugin marketplace add AminBlg/SimpleEnglish
codex plugin add simple-english@simple-english
```

Codex sẽ hỏi bạn có tin cậy hook không trước lần chạy đầu tiên. README nói hook cần Node.js, nên hãy chắc máy bạn đã có.

### Chọn output style trong Claude Code

Sau khi cài plugin, tên output style phải ghi đầy đủ là `simple-english:simple-english`. README nói rõ tên ngắn không hoạt động. Bạn có hai cách chọn. Cách một: gõ `/config` trong Claude Code rồi chọn mục Output style. Cách hai: thêm dòng sau vào tệp `~/.claude/settings.json`:

```json
{"outputStyle": "simple-english:simple-english"}
```

Nếu tệp đã có nội dung khác, hãy thêm khóa này vào cho đúng cú pháp JSON, đừng dán đè lên cả tệp.

### Agent không hỗ trợ skill thì sao

README có đường lui: dán khối quy tắc trong `prompts/system-prompt.md` vào system prompt, `AGENTS.md` hoặc `.cursorrules`. Trang đó có kèm bản rút gọn khoảng 60 token cho trường hợp ngân sách chặt. Mở thư mục `prompts/` trong repo để lấy.

## Kiểm tra đã chạy được chưa

README không đưa ra một lệnh kiểm tra cài đặt riêng, nên mình không bịa ra lệnh nào. Cách kiểm tra theo đúng mô tả của README là thử dùng:

1. Mở agent của bạn, đưa một đoạn văn dài dòng và gõ: "rewrite this with simple-english".
2. Nhìn kết quả. Nếu skill hoạt động, câu sẽ ngắn hơn, không còn gạch ngang dài hay chữ hoa mỹ, và câu đầu đi thẳng vào ý chính.
3. Hỏi thử một câu kỹ thuật có một thuật ngữ. Câu trả lời nên là đoạn văn thường, ít hoặc không có in đậm và gạch đầu dòng, và thuật ngữ được giải thích ngắn.
4. Với Claude Code bản plugin: vào `/config`, mục Output style, xem có `simple-english:simple-english` không.

Nếu AI vẫn viết như cũ, xem phần lỗi thường gặp bên dưới.

## Dùng vào việc thật

### Viết lại README cho dự án của bạn

Bạn là dev mới, README của dự án đầy chữ kiểu "seamlessly", "robust". Dán nội dung README vào agent đã cài skill và gõ:

```
rewrite this with simple-english
```

Kết quả: các câu dài bị cắt thành câu dưới 20 từ, câu đầu nói thẳng dự án làm gì, điều kiện (ví dụ "trước khi bắt đầu, hãy chắc rằng...") đứng trước lệnh. Repo có tệp `examples/before-after.md` với nhiều ví dụ viết lại cho README, runbook, báo cáo sự cố, thông báo lỗi và release notes để bạn so sánh.

> Hướng dẫn tốt không làm người đọc phải đoán. Câu ngắn là một lời hứa: đọc một lần là làm được.
>
> — Ông T

### Soạn runbook và quy trình cho đội vận hành

Bạn làm văn phòng hoặc vận hành, cần quy trình xử lý sự cố bằng tiếng Anh cho đối tác. Đưa ghi chú nháp cho AI và yêu cầu viết thành runbook. Skill sẽ giữ mỗi bước một hành động, đặt điều kiện trước lệnh, và dùng một từ cho một nghĩa xuyên suốt tài liệu. Nhờ đó người đọc đang căng thẳng lúc nửa đêm không phải dịch hay đoán xem "check" và "verify" có khác nhau không.

### Viết thông báo lỗi và release notes

Bạn làm sản phẩm và cần thông báo lỗi người dùng đọc là hiểu. Yêu cầu AI viết thông báo lỗi bằng Plain mode. Câu đầu nói chuyện gì xảy ra, câu sau nói người dùng phải làm gì. Với release notes, skill bỏ kiểu "making it easy to..." và chỉ nêu việc đã thay đổi.

### Viết tài liệu theo chuẩn chặt hơn

Công ty bạn muốn tài liệu bám sát STE. Hãy nêu rõ trong yêu cầu: "use ASD-STE100" hoặc nhắc đến tuân thủ. Skill chuyển sang chế độ Strict và áp dụng thêm kỷ luật từ điển trong `strict-vocabulary.md`. README nói thẳng: kết quả gần chuẩn nhưng không phải bản được chứng nhận, vì ASD không chứng nhận công cụ nào.

## Lỗi hay gặp và cách xử lý

**Đặt output style mà không thấy tác dụng.** Có hai nguyên nhân hay gặp. Một là bạn chỉ chạy `npx skills add`, cách này không cài output style. Hai là bạn dùng tên ngắn. Cách xử lý: cài plugin Claude Code, rồi dùng đúng tên đầy đủ `simple-english:simple-english`.

**Hook Codex không chạy.** Codex hỏi bạn có tin cậy hook trước lần chạy đầu. Nếu bạn từ chối hoặc bỏ qua, hook sẽ không hoạt động. Hook cũng cần Node.js, nên hãy kiểm tra máy đã có Node.js chưa. Chi tiết ở `src/hooks/README.md`.

**Lệnh `npx` không nhận ra.** Báo lỗi này thường nghĩa là máy chưa có Node.js. Cài Node.js từ trang chính thức, mở lại terminal rồi chạy lại. Đừng cài gói lạ theo hướng dẫn không rõ nguồn.

**AI vẫn viết dài dòng như cũ.** Có thể agent chưa nạp skill. Thử gọi rõ: "rewrite this with simple-english". Nếu agent của bạn không hỗ trợ skill, dùng đường lui: dán khối quy tắc trong `prompts/system-prompt.md` vào system prompt, `AGENTS.md` hoặc `.cursorrules`.

**Kết quả nghe hơi "máy móc".** Đây là chủ ý. README nói tài liệu sẽ giống sách hướng dẫn của Airbus: phẳng và không thể đọc nhầm. Nếu bạn viết blog hay bài giới thiệu có giọng riêng, đừng nạp skill cho việc đó, hoặc tự sửa lại giọng sau.

## Có nên dùng không

**Điểm mạnh.** Cài dễ, một lệnh là xong. Chạy trên rất nhiều agent. Quy tắc cụ thể, đo được ("không câu nào quá 20 từ"), thay vì lời dặn mơ hồ kiểu "viết rõ ràng". Tác giả công bố số đo và cho chạy lại bằng `python3 evals/check_numbers.py`. Ví dụ, với chat có thuật ngữ, README ghi số lỗi định dạng hiển thị (gạch ngang dài, in đậm, tiêu đề, gạch đầu dòng) giảm 95%, từ 218 xuống 11 ở bản 2.0.1 so với không dùng skill. Với tài liệu, tỷ lệ vi phạm trên 100 từ giảm 78% ở bản này.

**Giới hạn cần biết.** Các số trên đo bằng model Claude và giám khảo cũng là model Claude, nên chính README thừa nhận có thể có thiên lệch. Số liệu chat là của bản 2.0.1 còn phiên bản mới hơn chưa có lần chạy tương ứng. Bài đo tài liệu chỉ một lần chạy mỗi điều kiện và dao động khoảng 0,5, nên đọc là "ngang bằng hoặc tốt hơn" chứ đừng xem là bảng xếp hạng. Skill cũng không cho bạn văn bản đạt chứng nhận STE. Bộ công cụ trong repo không kèm nội dung từ điển STE, vì chuẩn cấm sao chép khi chưa có phép của ASD. Dự án này không chính thức và không liên kết với ASD hay STEMG.

**Khi nên chọn cách khác.** Nếu bạn viết nội dung cần giọng riêng, như blog, quảng cáo, bài chia sẻ cá nhân, thì skill này không hợp. Nếu bạn cần văn bản tiếng Việt, README chỉ nói về tiếng Anh nên chưa có thông tin về tiếng Việt. Nếu cần tài liệu tuân thủ STE chính thức, bạn phải tham khảo chuẩn gốc, bản tải miễn phí ở trang của ASD như README dẫn.

Tóm lại: nếu bạn thường nhờ AI viết tài liệu kỹ thuật bằng tiếng Anh và thấy nó dài dòng, đây là cách rẻ và nhanh để sửa. Cài thử cách một, rồi nâng lên plugin nếu thấy hợp.

## 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. Tuy nhiên agent mà bạn dùng cùng skill (Claude Code, Codex...) vẫn tính phí theo gói của chính nó, README không nói gì thêm về chi phí đó.

### Skill này có chạy trên Windows được không?

README không nêu hệ điều hành cụ thể. Skill chỉ là một thư mục hướng dẫn nên về nguyên tắc phụ thuộc vào agent của bạn. Cách cài bằng npx và phần hook cần Node.js, còn có chạy mượt trên Windows hay không thì README chưa có thông tin.

### Có cần GPU hay API key riêng không?

README không yêu cầu GPU hay API key riêng cho skill. Bạn chỉ cần agent mà mình đang dùng sẵn. Cách cài bằng plugin còn cần Node.js để chạy hook.

### SimpleEnglish khác gì việc chỉ bảo AI "hãy viết rõ ràng"?

Theo README, "rõ ràng" là ý kiến còn "không câu nào quá 20 từ" là quy định cụ thể mà agent làm theo được. Skill gồm 53 quy tắc đánh số của chuẩn STE (Issue 9) cho chế độ kiểm tra và Strict, và hai bộ quy tắc rút gọn cho chat và tài liệu.

### Văn bản AI viết ra có được chứng nhận STE không?

Không. README nói rõ không có công cụ nào được chứng nhận vì ASD không chứng nhận công cụ. Chế độ Strict chỉ giúp văn bản đến gần chuẩn hơn.

### Skill này dùng được với những agent nào?

README liệt kê các 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. Agent nào không hỗ trợ skill thì dán khối quy tắc trong prompts/system-prompt.md vào system prompt, AGENTS.md hoặc .cursorrules.

### Skill có viết được tiếng Việt không?

Chưa có thông tin. README chỉ nói về tiếng Anh theo chuẩn ASD-STE100, nên các quy tắc về độ dài câu, từ vựng và thì động từ đều dành cho tiếng Anh.
