Conversation
Copy the Simple English skill into .agents/skills/simple-english. Cursor and Codex load project skills from .agents/skills. The files come from commit 79b590fc8596523d92c26b1ea7e33236606ef069 with no changes. The project uses the MIT license, and LICENSE holds the license text. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
The upstream strip_code function replaced each code block and some table rows with one space. It removed their newlines, so each line number after a code block or a table was too small. In this repository, 34 hits went to the wrong line. strip_code now keeps the newlines that it removes. The violation counts do not change. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
Add hooks that load the Simple English rules at session start and lint the Markdown files that an agent writes. The hooks are advisory, so they never block an action. One script, scripts/hook.py, serves the three tools. The lint reports only the lines that differ from the last commit, so an agent does not rewrite old text. Cursor also runs the hooks in .claude/settings.json. The script finds this case and runs only the Cursor hooks. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
Add a Writing Style section to AGENTS.md. CLAUDE.md is a link to this file. The section gives the rules that agents break most often, the text that the rules cover, and the hooks for each tool. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
The upstream file ends with a blank line. The end-of-file-fixer pre-commit hook requires one newline at the end of each file, so the build failed. UPSTREAM.md now records this change. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requirements
Related issues
None. The rules come from the Simple English skill, which uses the MIT license.
Describe the solution you've provided
Summary
This PR tells AI agents to write in Simple English in this repository. Simple English is plain English that follows the rules of ASD-STE100 Simplified Technical English. The rules give short sentences, active voice, one word for one meaning, and no filler words.
The PR has three parts:
.agents/skills/simple-english/AGENTS.mdthat tells agents to use the skillThe guidance
The new "Writing Style: Simple English" section in
AGENTS.mdapplies to replies, Markdown files, pull request descriptions, commit messages, and new code comments. It lists the rules that agents break most often. It also tells agents not to change code, generated files, or text that their task does not touch.CLAUDE.mdis a link toAGENTS.md, so Claude Code gets the same section.The hooks
A hook is a command that an agent tool runs at a fixed point, for example at the start of a session. All the hooks run one script,
.agents/skills/simple-english/scripts/hook.py. The hooks are advisory, so they never block an action..cursor/hooks.json.claude/settings.json.codex/hooks.jsonThe lint reports only the lines that differ from the last commit. For example,
README.mdhas 20 old violations today. If an agent adds one bad line, the hook reports that line only. A new file gets a full lint.Cursor also runs the hooks in
.claude/settings.json. For this case, the script finds the Cursor input and runs only the Cursor hooks. Cursor Cloud Agents do not run session start hooks, so they get the rules fromAGENTS.md.To turn off the hooks, set
SIMPLE_ENGLISH_HOOKS=off.A fix in the linter
The skill includes a linter,
scripts/ste_lint.py. In the upstream version, each line number after a code block or a table is too small. In this repository, the upstream linter put 34 hits on the wrong line, in 26 of the 33 Markdown files. The copy in this PR keeps the newlines, so all hits go to the correct line. The violation counts do not change.UPSTREAM.mdrecords this change and the steps to update the copy.Tests
scripts/test_hook.pyhas 15 tests. The tests cover these areas:CHANGELOG.mdTo run the tests, run
python3 .agents/skills/simple-english/scripts/test_hook.py. I also ran the hook on real files in this repository. I did not run the hooks in a live Cursor, Claude Code, or Codex session, because this environment has no credentials for those tools.Describe alternatives you've considered
We did not use the upstream hook scripts. The upstream scripts need the layout of a Claude Code or Codex plugin, and they do not support Cursor.
We did not add a Cursor stop hook for the reply report. A Cursor stop hook can only start a new agent turn, and that can cause a loop.
We did not lint the full file after each edit. The full lint told agents to correct old text that their task did not touch.
Additional context
The hooks need
python3. Codex runs project hooks only in a trusted project, and Codex asks you to approve each hook. Open/hooksin Codex to approve it.