Teaching my agents to write better

What I chose, given my values, wishes and principles, and the reasoning that got me there.

Three pages in this bundle say how prose here should read: Write in a calm, quantified, settled-fact voice - not a promotional one, Name the concrete behaviour, not its abstract label and Hand the reader one idea at a time. They were convention, and read only by an agent that happened to open them. This decision is what made them arrive on their own.

What I wanted¶

Agents write in an acceptable voice everywhere, and I maintain the rules once.

Everywhere means more than this repository. It means a chat reply, a commit message, an email, and a project that has nothing to do with knowledge management. The rules had reached only the bundles, and only when something thought to read the conventions page.

What I care about¶

Plain-text, tool-agnostic formats, which is why the answer here is markdown and a script rather than a service.

Guarding invariants at commit time, because a rule a reviewer must remember is a rule that gets forgotten.

And one definitional home per concept, which is the requirement the whole problem turns on: the rules must arrive in four places without being written in four places.

What that led me to¶

The audience decides the layer. A human contributor never loads a skill, so the only things that reach them are a page and a commit hook. An agent never reads a page it was not pointed at, so the only thing that reaches it is an instruction. The same sentence about the word powerful therefore has to exist at several layers, and which copy is authoritative follows from reach rather than from content. That is the reusable half of this decision, and it is written up as Route a rule to the layer that reaches whoever must obey it.

The corollary is that a copy is acceptable when it carries imperatives and refuses to carry reasoning. The wiki argues, the skill instructs and links back, the digest instructs. A contradiction between them then shows up as a contradiction rather than passing quietly, because each layer names where its authority sits.

I considered Vale first, and its vale-ai-tells package, which is 111 rules for exactly these tells. I did not take it yet, as it's a Go binary whose rule packages are fetched over the network, and this repository already runs check_markdown_style.py as a dependency-free PEP 723 script doing the same class of work. The word list was still worth having, so it seeded mine.

What I built¶

Four layers, from the one that argues to the one that is always on.

Layer	Where	Reaches
The claim, with its reasoning	the three principle pages here	anyone who reads, whenever they read
The mechanical guard	the `prose-tells` hook in this repository	every contributor, human included
The full style, on demand	the `writing` skill in `ftschindler/agents-skills`	agents, in any harness, when loaded
The imperatives, always on	the writing section of my harness `AGENTS.md`	every reply I read

The hook is .scripts/check_prose_tells.py, a sibling of the markdown style check. It checks the hype adjectives, the throat-clearing openers, the future-promise framing, the corpus tells such as delve, the not just X, it is Y construction, and more than one exclamation mark in a page. Text inside code fences, inline code, link targets and quotation marks is exempt, with the open-quote state carried between lines, which is what lets the voice page print its own table of slop without tripping the hook that enforces it.

Backlinks¶

The following pages link to this page: