All projects

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.

a Markdown or text file blank out what isn't prose code, URLs, tags, front matter collapse whitespace a wrapped sentence is one line match the shapes a pattern for each shape map each match to its line the line where it starts line numbers nothing found exit 0: passes places to look exit 1: fails
What happens to a file, in order. The dashed line is the line number of each character, noted as the whitespace collapses and used to place each match.

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.