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.

Stars 1
Forks 0

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:

  1. Draft without constraint
  2. Replace vague with specific
  3. Eliminate needless words
  4. Use active voice
  5. One topic per paragraph
  6. 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.

Expand your agent's capabilities with these related and highly-rated skills.

geggo98/dotfiles

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.

1 0
Explore
geggo98/dotfiles

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.

1 0
Explore
geggo98/dotfiles

tmux

Remote control tmux sessions for interactive CLIs (python, gdb, etc.) by sending keystrokes and scraping pane output.

1 0
Explore
geggo98/dotfiles

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.

1 0
Explore
geggo98/dotfiles

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.

1 0
Explore
geggo98/dotfiles

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.

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results