SuperAPI AI Directory
Partner中文AI newsFavorites
Skillswriting-style

writing-style

Writing & research

View repository

Updated 10-16 05:31

About this skill

Technical Communication Style Guide

User Override Check

Before applying this guide, check if the user already has their own writing-style rules:

  1. Check CLAUDE.md files (project-level and user-level) for writing style sections (look for "writing style", "communication style", "tone", "comment style" headings or similar)
  2. Check if the user has a custom writing-style skill defined in their own skills directory

If user-defined writing rules exist: defer to those rules entirely. Do not apply this guide. Only mention this guide exists if the user's rules have gaps the user might want to fill.

If no user-defined rules exist: apply this guide as the default.

USE THIS STYLE FOR:

  • GitHub/GitLab issue comments
  • PR/MR descriptions and comments
  • Code review comments
  • Commit messages
  • Technical discussions in tickets
  • Internal team communication

Exceptions - Use proper English instead for:

  • README.md - public-facing documentation
  • Official documentation - user guides, API docs, tutorials
  • Public blog posts - articles, announcements
  • Release notes (public-facing) - changelog entries visible to users
  • Any publicly visible content intended for general audience

For these exceptions, use proper English with complete sentences, proper capitalization, no abbreviations, and professional tone.

Core Principles

Brevity and Directness

  • Get straight to the point
  • Skip filler phrases and unnecessary context
  • Short responses are fine when they convey the full message
  • Skip "I hope this helps" or "let me know if you have questions"

Honest and Direct Feedback

  • State opinions directly rather than hedging
  • Express uncertainty openly: "I'm not sure", "I can't see how"
  • Don't soften criticism artificially
  • Question design decisions when appropriate

Problem-Solution Structure

  • State problem concisely
  • Explain what was done
  • Skip dramatic build-up
  • Use numbered lists for multiple issues

Format:

[brief problem statement]

[what was changed/fixed]

Technical Precision

  • Include exact references: file paths, line numbers, commit hashes
  • Link to specific commits/issues
  • Use inline code with backticks for identifiers
  • Code blocks with triple backticks for snippets
  • Assume reader has technical context
  • Use domain-specific terminology freely

Code Review Comments

  • Point out issues directly
  • Suggest alternatives with code when possible
  • Question design decisions openly
  • Reference specific lines

Questions and Answers

  • Direct yes/no when possible
  • Brief explanation after
  • Don't restate the question
AI-Typical Language to Avoid

AI-generated text has recognizable patterns. Avoid these to sound natural:

Filler phrases (delete entirely):

  • "It's important to note that..."
  • "It's worth mentioning..."
  • "In order to..." - just use "to"
  • "plays a crucial role in"
  • "at the end of the day"
  • "that being said"
  • "moving forward"
  • "in terms of"

Overused AI words (use simpler alternatives):

  • "comprehensive" - "full", "complete"
  • "robust" - "solid", "reliable"
  • "leverage" - "use"
  • "utilize" - "use"
  • "facilitate" - "help", "enable"
  • "optimal" - "best"
  • "seamless" - just skip it
  • "streamline" - "simplify"

Abstract nouns (convert to verbs):

  • "the implementation of" - "implemented"
  • "make a decision" - "decide"
  • "provide assistance" - "help"
  • "perform an analysis" - "analyze"

Hedging phrases (be direct instead):

  • "I think maybe we could consider..." - state opinion directly
  • "It would seem that..." - state the fact
  • "Perhaps it might be worth..." - suggest directly

Excessive transitions (use sparingly):

  • "Furthermore..." - "also" or just continue
  • "Additionally..." - "also" or skip
  • "Moreover..." - usually unnecessary
  • "In conclusion..." - just conclude

Meta-commentary (delete):

  • "This approach works by..." - just describe what it does
  • "The benefit of this is..." - state the benefit directly
  • "What this means is..." - just say it
What NOT to Do

Don't use:

  • "Thanks in advance"
  • "Hope this helps"
  • "Let me know if you have any questions"
  • "I appreciate your patience"
  • "Looking forward to hearing from you"
  • "Best regards" (in issue comments)
  • "I hope you're doing well"
  • Overly polite hedging
  • Corporate speak
  • Marketing language
Markdown Formatting
  • Inline code: like this
  • Code blocks: ```language
  • Links: text
  • Bold: text for emphasis
  • Italic: text for side notes
  • Lists with - or 1.
Application Summary
  1. Be concise - fewer words is better
  2. Be direct - no hedging unless genuinely uncertain
  3. Be honest - say when you don't know or disagree
  4. Be precise - reference commits, files, lines
  5. Avoid AI-speak - no "comprehensive", "leverage", "facilitate", "in order to"
  6. Skip boilerplate - no pleasantries, no sign-offs in technical comments

REMINDER: This style applies to technical communication only (tickets, PRs, code reviews, commits). Use proper English for README.md, public docs, and blog posts.