Agent skill
writing-clearly-and-concisely
Use when writing documentation, commit messages, error text, explanations, reports, or summaries. Applies Strunk's principles for clear, vigorous prose. Triggers: writing human-readable content, verbose text, unclear explanations.
Install this agent skill to your Project
npx add-skill https://github.com/geggo98/dotfiles/tree/main/modules/ai/_files/skills/technical-writing
SKILL.md
Writing Clearly and Concisely
Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.
Core Principles
Make paragraph the unit of composition: One paragraph per topic. Does each paragraph develop a single idea?
Use active voice: "The committee approved" not "The committee gave approval." Default to active unless actor is unknown or unimportant.
Put statements in positive form: Say what is, not what isn't. "He thought Latin useless" not "He did not think Latin was useful."
Use definite, specific, concrete language: "It rained every day for a week" not "A period of unfavorable weather." "He grinned" not "He showed satisfaction."
Keep related words together: Don't separate subject from verb or verb from object unnecessarily. "In 1865 he published his work" not "He published, in 1865, his work."
Place emphatic words at sentence end: "Although improvements occurred, crime increased" not "Crime increased, although improvements occurred."
Omit Needless Words
Eliminate verbose constructions:
- "the question as to whether" -> "whether"
- "there is no doubt but that" -> "no doubt"
- "used for fuel purposes" -> "used for fuel"
- "he is a man who" -> "he"
- "in a hasty manner" -> "hastily"
- "this is a subject that" -> "this subject"
- "the reason why is that" -> "because"
- "owing to the fact that" -> "since" or "because"
- "in spite of the fact that" -> "though" or "although"
- "call your attention to the fact that" -> "remind you"
- "the fact that" -> (delete or rephrase)
- "as to whether" -> "whether"
Don't bury the main point: "My arrival caused consternation" not "The fact that I had arrived was enough to cause consternation."
Needless Words
case: "In many cases, tests fail" -> "Tests often fail"
character, nature: "Acts of hostile character" -> "hostile acts" "Technical nature" -> "technical"
factor: "Training was a factor" -> "Training contributed" or "They won through training"
feature: Hackneyed word. Avoid as verb.
interesting: Don't announce content is interesting. Make it interesting.
very: Use sparingly. "Very tired" -> "exhausted"
respective, respectively: Usually omissible.
Technical Writing Usage
data: Plural. "These data show" not "This data shows"
fewer vs less: "fewer bugs" (countable), "less memory" (quantity)
while: Means "during the time that." Don't substitute for "and," "but," or "although."
etc.: Don't use after "such as" or "for example." Avoid if reader uncertain what's included.
Edit Ruthlessly
When writing:
- Draft without constraint
- Replace vague with specific
- Eliminate needless words
- Use active voice
- One topic per paragraph
- Emphatic words at end
Every word must justify its presence.
References
See anti-tropes-instruction for specific writing patterns to avoid -- word choice, sentence structure, tone, and formatting tropes that signal AI-generated or formulaic prose.
See signs of AI writing for a field guide to detecting AI-generated content -- vocabulary tells, structural patterns, markup artifacts, and citation problems common in LLM output.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
eval-notebook
Execute .ipynb notebooks (Python, Kotlin, or any Jupyter kernel) without overwriting; return LLM-friendly JSON with outputs and errors. Use when you need to run or validate a Jupyter notebook.
nix-shell
Search Nix packages and run commands with packages from nixpkgs that are not installed locally. Use when you need a package not available locally or want to search nixpkgs.
tmux
Remote control tmux sessions for interactive CLIs (python, gdb, etc.) by sending keystrokes and scraping pane output.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks. Also trigger when the user mentions Slidev, sli.dev, slide decks with code, or wants to create developer-facing presentations.
diagram-render
Render PlantUML (@startuml…@enduml) and Mermaid fenced blocks to a self-contained HTML preview; if rendering fails, the error text must be embedded in the output image. Use when the user asks to render, preview, or export diagrams.
adr-writing
Use when documenting significant architectural decisions. Creates focused ADRs explaining context, decision, and alternatives. Prevents vague documentation and implementation detail bloat. Triggers: 'create ADR', 'document decision', making technology/framework/persistence/auth choices, cross-cutting concerns.
Didn't find tool you were looking for?