prose-tells
A check for the sentence shapes that read as machine-written. It runs on plain Node, fails a build when it finds one, and ships as a skill for coding agents too.
- Role
- Design and build
- Client
- Personal project
- Year
- 2026
- Stack
-
- Tool
- Node.js
- Tests
- node:test
- Distribution
- GitHub Actions, Agent skill, AGENTS.md
A check for the shapes generated prose leans on
It reads Markdown or plain text and reports the constructions that give generated prose away: lists of negations, a claim set up against a foil it then knocks down, sentences that end on a moral, stock vocabulary, and dashes where a comma would do. Its list starts from Wikipedia’s Signs of AI writing, which its editors keep up from cleaning this out of articles.
Each finding comes with its line number, the shape, and the text around it. When it finds something, the command exits 1, the code for a failure, so it can stop a build. A finding is a prompt to reread the line rather than an order to change it. People write any of these once. What reads as generated is reaching for them all the time.
On a short draft written to trip it, the report looks like this:
$ npx github:zkousama/prose-tells draft.md
draft.md
3 not just X but Y escalation
…It's not just faster, but safer. The plan is a description of desired…
3 vocabulary that clusters in generated prose
…# Release notes The new cache is robust and seamless. It's not just faster…
3 vocabulary that clusters in generated prose
…The new cache is robust and seamless. It's not just faster, but safer…
5 X, not Y antithesis: state the thing without the foil
…The plan is a description of desired state, not a script. That's important.…
5 a stub that grades the sentence before it (That's important.): let the fact carry it
…a description of desired state, not a script. That's important.…
5 places to look
Its examples are its tests
Nothing to install. It’s plain Node with no dependencies.
Code isn’t prose. Before any matching, code blocks, inline code, URLs, link targets, HTML tags and front matter are blanked out with their positions kept, so a code sample never trips it and line numbers still point at the right place.
Wrapped lines are one sentence. Prose wrapped at 78 columns puts a line break inside most phrases, so a check that reads line by line misses nearly every instance. It collapses whitespace first and maps each match back to its line.
The examples are the tests. Every shape carries a phrase it must catch and a phrase it must leave alone, and the test suite runs both. A pattern that has been narrowed until it catches nothing fails the build instead of looking clean.
3 ways to use it. The command, for CI (the checks that run on every change
to a repository). A skill for coding agents: instructions an AI coding
assistant loads when a task calls for them. This one tells the agent to run
the check before it calls a piece of writing finished. And a short stanza for
AGENTS.md or CLAUDE.md, the files an agent reads before it starts work.
Neither of the last 2 lists the shapes: they point at the check. CI runs the
tests, then the tool against its own README, the stanza and the skill.