Skip to content
Back to search

myst-plain-english

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/artgins--myst-plain-english/badge.svg)](/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-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 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
  1. {
  2. "name": "myst-plain-english",
  3. "owner": {
  4. "name": "ArtGins",
  5. "url": "https://github.com/artgins"
  6. },
  7. "description": "Plain English (ASD-STE100) for Markdown and MyST documentation: a skill and a linter.",
  8. "plugins": [
  9. {
  10. "name": "myst-plain-english",
  11. "source": "./",
  12. "displayName": "MyST Plain English",
  13. "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.",
  14. "version": "1.0.0",
  15. "author": {
  16. "name": "ArtGins"
  17. },
  18. "homepage": "https://github.com/artgins/myst-plain-english",
  19. "repository": "https://github.com/artgins/myst-plain-english",
  20. "license": "MIT",
  21. "keywords": ["technical-writing", "documentation", "myst", "jupyter-book", "markdown", "ste", "asd-ste100", "linter"]
  22. }
  23. ]
  24. }
README.md · README · 135 lines
  1. # myst-plain-english
  2. `myst-plain-english` helps you write documentation in plain English, with the rules of
  3. [ASD-STE100](https://www.asd-ste100.org/) Simplified Technical English (STE).
  4. It has two parts:
  5. - A skill for Claude: the writing rules, the rules that keep a MyST site intact, and a
  6. structure with the commands first and the explanation below.
  7. - A linter, `myst-plain-lint`: it reports the violations that a program can find in
  8. Markdown and MyST files. It is one Python 3 file with no dependencies.
  9. ## Install and run
  10. Install the plugin in Claude Code:
  11. ```bash
  12. claude plugin marketplace add artgins/myst-plain-english
  13. claude plugin install myst-plain-english@myst-plain-english
  14. ```
  15. Then ask Claude to write or rewrite documentation. Claude loads the skill when the task
  16. matches. You can also name it: "use myst-plain-english on docs/install.md".
  17. Install the linter and run it:
  18. ```bash
  19. pipx install git+https://github.com/artgins/myst-plain-english
  20. myst-plain-lint docs/*.md # every hit, with its rule
  21. myst-plain-lint --summary docs/**/*.md # one line for each file
  22. myst-plain-lint --rule semicolon FILE # one category
  23. myst-plain-lint --strict FILE # add the judgement calls
  24. ```
  25. To run the linter in [pre-commit](https://pre-commit.com/), add this to
  26. `.pre-commit-config.yaml`:
  27. ```yaml
  28. repos:
  29. - repo: https://github.com/artgins/myst-plain-english
  30. rev: 1.0.0
  31. hooks:
  32. - id: myst-plain-lint
  33. ```
  34. To use the skill on claude.ai, make a zip of the folder `skills/myst-plain-english` and
  35. upload it in Settings, Capabilities, Skills. The linter is in that folder too
  36. (`scripts/myst_plain_lint.py`).
  37. ## What the skill does
  38. The skill is a fork of the `simple-english` skill of
  39. [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), release 2.1.2. Its
  40. rules are the same: short sentences (20 words for an instruction, 25 for a description),
  41. simple tenses, active voice, one word for one meaning, condition before command, and every
  42. technical term defined at its first use. It also has these additions:
  43. | Addition | What it says |
  44. |---|---|
  45. | 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. |
  46. | 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. |
  47. | 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. |
  48. | The linter | Run it on each file that you changed, and fix each hit outside a heading. |
  49. The "would" rule is the result of experience. When an AI agent removes the banned modals, it
  50. often turns a hypothesis into a fact. For example, "a serial run does not start: it would do
  51. the steps before it and stop there" became "a serial run does not start, because it does
  52. the steps before it and stops there". That sentence says the opposite of the original. An explicit rule prevents it.
  53. ## What the linter reports
  54. The linter reports only the rules that need no judgement:
  55. | Rule id | What it finds | STE rule |
  56. |---|---|---|
  57. | `contraction` | `don't`, `it's`, `we'll` | 4.2 |
  58. | `perfect` | `has been`, `had been` | 3.4 |
  59. | `modal` | `should`, `would`, `may`, `might`, `could` | 3.2 |
  60. | `semicolon` | `;` in prose | 8.1 |
  61. | `latin` | `e.g.`, `i.e.`, `etc.` | GR-6 |
  62. | `progressive` | `is being`, `were being` | 3.4 |
  63. | `ing_clause` | `, making ...`, `, allowing ...` | 3.5 |
  64. | `british` | `behaviour`, `initialise`, `licence` | 1.14 |
  65. | `phrasal` | `set up`, `comes back`, `shut down` | 9.3 |
  66. | `slop` | `leverage`, `robust`, `seamlessly`, `in order to` | |
  67. | `filler_hard` | `simply`, `actually`, `of course` | |
  68. | `slash` | `and/or` | |
  69. With `--strict`, it also reports possible present perfects, possessives and `just`. These
  70. need a person to decide, so they are off by default.
  71. The exit code is 1 when the linter reports anything, and 0 when it reports nothing. A clean
  72. run does not mean that the text is good STE. It never means compliance with ASD-STE100. Read
  73. the prose.
  74. ## What the linter reads and skips
  75. The linter reads the parts of a document that a reader reads, and skips the parts that are
  76. code or quotations:
  77. | Part of the document | Read | Note |
  78. |---|---|---|
  79. | 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. |
  80. | Table cells | yes | A table row is one line. A code span or a quotation does not continue into the next row. |
  81. | 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. |
  82. | Headings | yes | The linter reports a heading. Do not rename it if other pages link to it. |
  83. | Fenced and indented code blocks | no | |
  84. | Other directives | no | `code-block`, `include`, `mermaid`, `math`, `list-table` and every directive that is not in `PROSE_DIRECTIVES`. |
  85. | Inline code and roles | no | `` `code` ``, ``` `` a`b `` ```, a span that continues on the next line, and `` {ref}`target` ``. |
  86. | 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. |
  87. | Link targets and URLs | no | |
  88. | Labels, comments, math, front matter | no | `(name)=`, `% comment`, `<!-- comment -->`, `$$` blocks, and the YAML front matter. |
  89. The month "May" next to a number ("May 1", "22-May-2025", "the 5th of May") is not the modal
  90. "may".
  91. ## Origin
  92. The linter started as `scripts/check_ste.py` in [Yuneta](https://github.com/artgins/yunetas),
  93. an open source framework of ArtGins. Its documentation, [doc.yuneta.io](https://doc.yuneta.io),
  94. is a MyST site. In November 2026, the skill and the linter brought about 300 pages of that site
  95. and of the Yuneta READMEs from about 6,400 hits to 14. The 14 are in headings, in link texts that
  96. quote a heading, and in a normative "MAY" of RFC 6749. Each blind spot of the linter that this
  97. work found is a test in `tests/test_lint.py`.
  98. Run the tests with:
  99. ```bash
  100. python3 -m unittest discover -s tests
  101. ```
  102. ## License
  103. MIT. The skill text and its `references/` derive from
  104. [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), MIT, Copyright (c) 2026
  105. AminBlg. The additions and the linter are Copyright (c) 2026 ArtGins. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.