Writing style
My personal skills for agentic GitHub development workflows
npx -y skills add chieaid24/skills --skill writing-styleAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
House writing style for published prose - anything a reader outside the work will see. Use when writing or editing a README, a blog post, release notes, an announcement, a docs page, landing or marketing copy, a changelog entry, or a PR body.
SKILL.md
5.1 KB, as published. Nobody here has run it
Writing Style
Terse, imperative, engineer-facing prose, after the Google developer documentation style. Second person, present tense, active voice.
The rules below fight the defaults a language model brings to prose. They are the whole guide; per-artifact structure lives behind the pointers in Artifacts.
Scope: the reader is a stranger
This skill governs published prose - anything read by someone outside the work: a README, a post, release notes, an announcement, a docs page, landing copy, a PR body. The test is whether a reader who was not in the room will see it.
That reader has none of your context. They do not know the ticket number, the internal codename, the teammate you argued with, or the acronym your team coined last month. Published prose carries its own context or it fails.
The internal technical record - commit messages, code comments - is written for someone inside the work, reading with the diff open. It follows the repo's own convention, and this skill stays out of it.
Agent-facing instructions are not published prose either. A SKILL.md, an AGENTS.md, or a CLAUDE.md is read by a machine executing it, not by a stranger deciding whether to care. Those are governed by writing-great-skills, whose structure and voice rules deliberately differ from these. This skill stays out of them too - and its voice overlay especially so, since a personal register has no business in instructions an agent must follow.
The reader's next action
One test governs inclusion: does this line change what the reader does next? A line that survives is load-bearing. A line that merely proves you did the work is filler, and filler is the tax every reader pays on every read.
Lead with the outcome
The first sentence carries the payload: what changed, what this is, what broke. Context, motivation, and history come after, for the reader who wants them.
A reader who stops after sentence one should still have the answer.
Cut the throat-clearing
Throat-clearing is the run-up before the point: This PR aims to..., In this section we will explore..., It is worth noting that..., As you can see.... Open on the substance instead.
The same applies at the end. Once the point is made, stop. A closing paragraph that restates the body is restatement, and it earns nothing.
Claims are checkable
State what you can show. Cuts p99 from 400ms to 120ms is a claim; blazing fast is hype.
Hype words to convert into evidence or delete: robust, seamless, powerful, comprehensive, elegant, flexible, simply, easily, just, best-in-class, production-grade.
When there is no evidence, the honest move is to describe the mechanism and let the reader judge.
Name the actor
The scheduler retries the job beats the job is retried. Passive voice hides who acts, and in engineering prose the actor is usually the fact the reader needs.
Earn every structure element
Headers, bullets, tables, and bold are for material that is genuinely parallel or genuinely scannable. Three sentences of connected reasoning are a paragraph. Bulleting them fragments an argument into a list of nouns and drops the connective tissue that made it an argument.
Bold marks a term being defined, not a phrase you want the reader to feel strongly about.
Be specific
improve, enhance, update, handle, support, and refactor describe a category of change, not a change. Say the change: retry on 429 instead of failing, not improve error handling.
Printable ASCII only
No em dashes, en dashes, curly quotes, ellipsis characters, arrows, or emoji. Hyphen, straight quote, three periods. A hyphen with spaces around it - like this - does the job of an em dash.
This one is mechanical, and it is the rule models break most.
Voice
The rules above set the floor. Voice is the layer on top: cadence, diction, how a sentence opens, how dry the humor runs.
Check for a voice overlay at ~/.agents/writing/voice/VOICE.md. If it exists, read it and match it. It carries samples of the author's own writing, and imitating a sample beats following an adjective. Where the overlay and this file disagree on tone, the overlay wins.
The overlay never overrides structure. A README keeps its shape no matter whose voice it speaks in - register travels, form does not.
If no overlay exists, the default voice is the one described at the top of this file.
Artifacts
Each artifact adds structure on top of the rules above. Read the one you are about to write:
- READMEs - and docs pages, which share its shape
- Posts - blog posts, announcements, release notes, changelogs, landing copy
- PR bodies
An artifact with no reference file of its own still takes the rules above, and borrows the shape of whichever of the three it most resembles.
Gives 0 of the 12 instructions most readme changelog skills give
Counted across 471 of the 478 authors here whose files we hold, read 2026-08-06
- follow the Keep a Changelog formatin 31 of 471, across 26 files
- omit empty sectionsin 21 of 471
- Run from the git repository rootin 20 of 471, across 7 files
- save output directly to CHANGELOG.mdin 20 of 471, across 7 files
- Group commits into logical categoriesin 19 of 471, across 6 files
- Review the generated changelog before publishingin 19 of 471, across 6 files
- Apply changelog guidelines and brand voicein 18 of 471, across 5 files
- Exclude internal commits like refactoring and testsin 18 of 471, across 5 files
- Specify date ranges for focused changelogsin 17 of 471, across 4 files
- Convert technical commits into customer languagein 17 of 471, across 4 files
- group commits by conventional commit typein 14 of 471
- insert new entry below unreleased sectionin 14 of 471
Said here and by no other author read
- Write terse, imperative, engineer-facing prose.
- Include only lines that change the reader's next action.
- Lead the first sentence with the outcome or payload.
- Cut introductory run-up and closing restatements.
- Replace hype words with checkable evidence or delete them.
- Name the actor instead of using passive voice.
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.