myst-plain-english
Plain English (ASD-STE100) for Markdown and MyST documentation: a skill and a linter.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/artgins--myst-plain-english)HTML
<a href="/listings/artgins--myst-plain-english"><img src="/api/listings/artgins--myst-plain-english/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install the plugin in Claude Code:
claude plugin marketplace add artgins/myst-plain-english claude plugin install myst-plain-english@myst-plain-english
Then ask Claude to write or rewrite documentation. Claude loads the skill when the task matches. You can also name it: "use myst-plain-english on docs/install.md".
Install the linter and run it:
pipx install git+https://github.com/artgins/myst-plain-english myst-plain-lint docs/*.md # every hit, with its rule myst-plain-lint --summary docs/**/*.md # one line for each file myst-plain-lint --rule semicolon FILE # one category myst-plain-lint --strict FILE # add the judgement calls
To run the linter in [pre-commit](https://pre-commit.com/), add this to `.pre-commit-config.yaml`:
repos:
- repo: https://github.com/artgins/myst-plain-english
rev: 1.0.0
hooks:
- id: myst-plain-lintTo use the skill on claude.ai, make a zip of the folder `skills/myst-plain-english` and upload it in Settings, Capabilities, Skills. The linter is in that folder too (`scripts/myst_plain_lint.py`).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 24 lines
- {
- "name": "myst-plain-english",
- "owner": {
- "name": "ArtGins",
- "url": "https://github.com/artgins"
- },
- "description": "Plain English (ASD-STE100) for Markdown and MyST documentation: a skill and a linter.",
- "plugins": [
- {
- "name": "myst-plain-english",
- "source": "./",
- "displayName": "MyST Plain English",
- "description": "Plain, layman-readable English with the discipline of ASD-STE100 Simplified Technical English, for Markdown and MyST documentation, with a linter that reads admonitions and skips code.",
- "version": "1.0.0",
- "author": {
- "name": "ArtGins"
- },
- "homepage": "https://github.com/artgins/myst-plain-english",
- "repository": "https://github.com/artgins/myst-plain-english",
- "license": "MIT",
- "keywords": ["technical-writing", "documentation", "myst", "jupyter-book", "markdown", "ste", "asd-ste100", "linter"]
- }
- ]
- }
README.md · README · 135 lines
- # myst-plain-english
- `myst-plain-english` helps you write documentation in plain English, with the rules of
- [ASD-STE100](https://www.asd-ste100.org/) Simplified Technical English (STE).
- It has two parts:
- - A skill for Claude: the writing rules, the rules that keep a MyST site intact, and a
- structure with the commands first and the explanation below.
- - A linter, `myst-plain-lint`: it reports the violations that a program can find in
- Markdown and MyST files. It is one Python 3 file with no dependencies.
- ## Install and run
- Install the plugin in Claude Code:
- ```bash
- claude plugin marketplace add artgins/myst-plain-english
- claude plugin install myst-plain-english@myst-plain-english
- ```
- Then ask Claude to write or rewrite documentation. Claude loads the skill when the task
- matches. You can also name it: "use myst-plain-english on docs/install.md".
- Install the linter and run it:
- ```bash
- pipx install git+https://github.com/artgins/myst-plain-english
- myst-plain-lint docs/*.md # every hit, with its rule
- myst-plain-lint --summary docs/**/*.md # one line for each file
- myst-plain-lint --rule semicolon FILE # one category
- myst-plain-lint --strict FILE # add the judgement calls
- ```
- To run the linter in [pre-commit](https://pre-commit.com/), add this to
- `.pre-commit-config.yaml`:
- ```yaml
- repos:
- - repo: https://github.com/artgins/myst-plain-english
- rev: 1.0.0
- hooks:
- - id: myst-plain-lint
- ```
- To use the skill on claude.ai, make a zip of the folder `skills/myst-plain-english` and
- upload it in Settings, Capabilities, Skills. The linter is in that folder too
- (`scripts/myst_plain_lint.py`).
- ## What the skill does
- The skill is a fork of the `simple-english` skill of
- [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), release 2.1.2. Its
- rules are the same: short sentences (20 words for an instruction, 25 for a description),
- simple tenses, active voice, one word for one meaning, condition before command, and every
- technical term defined at its first use. It also has these additions:
- | Addition | What it says |
- |---|---|
- | Layer the document | The word limits apply to each sentence, not to the document. Put a summary with the commands first, and the explanation below it. Do not delete a fact to meet a limit. Move it to the explanation. |
- | The "would" rule | A "would" that names a rejected alternative or a past bug stays hypothetical: "Otherwise, X", "If X, Y", "Before the fix, X". It never becomes a fact or a promise. |
- | MyST documents | Do not rename a heading, because other pages link to its anchor. Do not touch labels, roles, directive lines or their options. The text of an admonition is prose. Do not indent a paragraph 4 spaces outside a list. |
- | The linter | Run it on each file that you changed, and fix each hit outside a heading. |
- The "would" rule is the result of experience. When an AI agent removes the banned modals, it
- often turns a hypothesis into a fact. For example, "a serial run does not start: it would do
- the steps before it and stop there" became "a serial run does not start, because it does
- the steps before it and stops there". That sentence says the opposite of the original. An explicit rule prevents it.
- ## What the linter reports
- The linter reports only the rules that need no judgement:
- | Rule id | What it finds | STE rule |
- |---|---|---|
- | `contraction` | `don't`, `it's`, `we'll` | 4.2 |
- | `perfect` | `has been`, `had been` | 3.4 |
- | `modal` | `should`, `would`, `may`, `might`, `could` | 3.2 |
- | `semicolon` | `;` in prose | 8.1 |
- | `latin` | `e.g.`, `i.e.`, `etc.` | GR-6 |
- | `progressive` | `is being`, `were being` | 3.4 |
- | `ing_clause` | `, making ...`, `, allowing ...` | 3.5 |
- | `british` | `behaviour`, `initialise`, `licence` | 1.14 |
- | `phrasal` | `set up`, `comes back`, `shut down` | 9.3 |
- | `slop` | `leverage`, `robust`, `seamlessly`, `in order to` | |
- | `filler_hard` | `simply`, `actually`, `of course` | |
- | `slash` | `and/or` | |
- With `--strict`, it also reports possible present perfects, possessives and `just`. These
- need a person to decide, so they are off by default.
- The exit code is 1 when the linter reports anything, and 0 when it reports nothing. A clean
- run does not mean that the text is good STE. It never means compliance with ASD-STE100. Read
- the prose.
- ## What the linter reads and skips
- The linter reads the parts of a document that a reader reads, and skips the parts that are
- code or quotations:
- | Part of the document | Read | Note |
- |---|---|---|
- | Paragraphs, lists, list continuations | yes | A line indented 4 spaces is code only where CommonMark makes it code: after a blank line, 4 columns past the content of the list around it. |
- | Table cells | yes | A table row is one line. A code span or a quotation does not continue into the next row. |
- | Admonitions and other prose directives | yes | `note`, `warning`, `tip`, `important`, `dropdown`, `tab-item`, `card`, `sidebar`, `margin` and the others in `PROSE_DIRECTIVES`, with backtick or colon fences, nested too. Their `:option:` lines are skipped. |
- | Headings | yes | The linter reports a heading. Do not rename it if other pages link to it. |
- | Fenced and indented code blocks | no | |
- | Other directives | no | `code-block`, `include`, `mermaid`, `math`, `list-table` and every directive that is not in `PROSE_DIRECTIVES`. |
- | Inline code and roles | no | `` `code` ``, ``` `` a`b `` ```, a span that continues on the next line, and `` {ref}`target` ``. |
- | Double-quoted text | no | A quotation repeats a log line or an error message, and it must stay exact (STE rule 8.6). The linter finds each opening and closing mark from the characters next to it. Thus, a closing mark inside a code span does not hide the rest of the paragraph. |
- | Link targets and URLs | no | |
- | Labels, comments, math, front matter | no | `(name)=`, `% comment`, `<!-- comment -->`, `$$` blocks, and the YAML front matter. |
- The month "May" next to a number ("May 1", "22-May-2025", "the 5th of May") is not the modal
- "may".
- ## Origin
- The linter started as `scripts/check_ste.py` in [Yuneta](https://github.com/artgins/yunetas),
- an open source framework of ArtGins. Its documentation, [doc.yuneta.io](https://doc.yuneta.io),
- is a MyST site. In November 2026, the skill and the linter brought about 300 pages of that site
- and of the Yuneta READMEs from about 6,400 hits to 14. The 14 are in headings, in link texts that
- quote a heading, and in a normative "MAY" of RFC 6749. Each blind spot of the linter that this
- work found is a test in `tests/test_lint.py`.
- Run the tests with:
- ```bash
- python3 -m unittest discover -s tests
- ```
- ## License
- MIT. The skill text and its `references/` derive from
- [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), MIT, Copyright (c) 2026
- AminBlg. The additions and the linter are Copyright (c) 2026 ArtGins. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.