# Writing Style

> Write commit messages, PR and issue text, docs (README), code comments, and user-facing strings (notifications, UI labels, toasts, error messages) in the project owner's voice: concise, human, UK English, no em-dashes, no robotic or marketing tone. Use when authoring or editing any of these. Defer to a repo's established house style when it has one; otherwise this sets the default voice.

- Skill: `timmo001/writing-style` (Agent Skill)
- Install (CLI): `npx skillmds@latest add timmo001/writing-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timmo001/writing-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- License: Apache-2.0
- Author: timmo001 (https://skillmd.com/u/timmo001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/timmo001/writing-style

---


# Writing Style

Write prose the agent authors on the user's behalf in the project owner's established voice: commit messages, pull request and issue text, READMEs and docs, code comments, and user-facing strings.

This is not LLM house style. Write like the person whose repo this is, judged against their existing work, not like a polished assistant.

## Permission: writing is not doing

Drafting the text is never permission to perform the action.

- Never create, amend, or push a commit unless the user explicitly asks.
- Never open, edit, comment on, or close a pull request or issue unless the user explicitly asks.
- Producing a commit message, PR description, or issue body on request does not authorise committing, pushing, or submitting it. Hand back the text and stop.
- Any action the user must explicitly request, never assume it. When unsure, ask first.

## Always (every artifact in scope)

These rules cover the artifacts this skill governs (commits, PR and issue text, docs, comments, user-facing strings). They are not the agent's whole obligation: chat replies and any other output are governed by AGENTS.md, which carries the same no-em-dash and no-robotic-tone rules and applies everywhere.

- Never use an em-dash (—) or a spaced en-dash (–) as a substitute. Use a hyphen, comma, colon, parentheses, or split the sentence.
- No robotic or marketing tone. Drop filler such as "seamlessly", "robust", "powerful", "effortless", "leverage", "delve", and throat-clearing such as "In order to", "It is worth noting", "Furthermore".
- Spelling: UK English by default (centralise, behaviour, colour, optimise, cancelled, licence as a noun); follow the repo's locale where it sets a different one. See "Defer to house style".
- Be concrete and specific over vague summary.
- Mirror the surrounding corpus before writing: skim recent commits, nearby docs, and existing UI strings, and match their tone, casing, and structure.

## Commit messages (default personal style)

- Imperative and verb-first: "Add", "Fix", "Remove", "Centralise", "Clarify", "Limit", "Drop".
- Sentence case, capitalised first word, no trailing full stop.
- Concise but informative: say what changed and, where it helps, the effect. Describe the change, do not restate the filename.
- Avoid bare single-word subjects ("Upd", "Note", "Fix" alone) when the change deserves a few words. Prefer "Notify on resume if clean" over "Note".
- No Conventional Commit prefixes (feat:, fix:) in personal repos. Follow the repo's convention where one exists.
- Always a single line. No body, no bullet lists, no multi-line messages. Multi-line bodies read as LLM-generated; keep the whole message to one concise subject line. Follow the repo's convention where one requires a body.

## PR and issue text

- Lead with what and why in a sentence or two. Skip template padding unless the repo requires it.

## Docs and READMEs

- Direct and friendly, first person where it fits. Emoji is fine where the existing doc already uses it; keep it out of commit messages and serious error copy.

## User-facing strings (notifications, UI, errors)

- Short, plain, and human. Say the thing. No robotic scaffolding, no em-dash.
- Match the app's existing string register; calibrate against nearby strings rather than inventing a new tone.

## Defer to house style

- When a repo has its own conventions (a CONTRIBUTING or docs style guide, or an established commit and docs style), follow it for structure, format, and spelling/locale, including a different default language. Keep only the universal rules: no em-dash, no robotic tone.

## Examples

- Robotic, with em-dash: "Enhance the notification system to seamlessly keep users informed — improving clarity." Prefer: "Notify on resume if clean".
- Vague single word: "Upd". Prefer: "Keep origin/HEAD fresh for default-branch detection".
- Marketing tagline: "A powerful, robust utility that effortlessly runs your tasks." Prefer: "A utility to run common tasks".