technical-writing-style
Use this skill when authoring, reviewing, or editing technical documents, including bug reports, known issues, friction logs, PR descriptions, and the structural content and tone of commit messages. Use to ensure engineering content maintains a clear, factual, and constructive tone. Triggers: technical writing, bug report, known issue, friction log, PR description, pull request, commit message tone, review document.
Best use case
technical-writing-style is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use this skill when authoring, reviewing, or editing technical documents, including bug reports, known issues, friction logs, PR descriptions, and the structural content and tone of commit messages. Use to ensure engineering content maintains a clear, factual, and constructive tone. Triggers: technical writing, bug report, known issue, friction log, PR description, pull request, commit message tone, review document.
Teams using technical-writing-style should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/technical-writing-style/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How technical-writing-style Compares
| Feature / Agent | technical-writing-style | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use this skill when authoring, reviewing, or editing technical documents, including bug reports, known issues, friction logs, PR descriptions, and the structural content and tone of commit messages. Use to ensure engineering content maintains a clear, factual, and constructive tone. Triggers: technical writing, bug report, known issue, friction log, PR description, pull request, commit message tone, review document.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Technical Writing Style Guidelines This skill provides guidelines and formatting standards for authoring various types of technical and engineering documents. ## Core Principles When writing or editing technical content, adhere to the following tonal and structural principles: - **Plain English:** Be direct, clear, and factual. Avoid corporate speak, overly formal detachment, and excessive jargon. - **Constructive & Collegial:** Position yourself as an enthusiastic peer who wants the tool to succeed. Be supportive of the tool/library authors while remaining objective about the facts. Frame friction as opportunities for clarity, not as failures. - **Avoid Exaggeration:** Do not use colloquial "cheerleading", subjective, or exclamatory language (e.g., avoid phrases like "massive quality-of-life improvement," "this tool shines," or "absolute powerhouse"). State the benefit factually instead (e.g., "This significantly simplifies parsing"). - **Focus on the "Why" & Context:** Assume the reader knows the codebase but not the specific problem you are solving. Provide enough background that the document makes sense in isolation. The code/log explains _what_ changed and _how_; your writing must explain _why_. - **Defend Your Decisions:** Proactively explain controversial choices, trade-offs, or omissions (e.g., why tests weren't added, why a specific library was chosen). - **Prohibition on Speculation:** Maintain objectivity. Do not interpret intent or attach qualitative judgment to behavior. Describe observable symptoms and factual outcomes. Save technical reasoning, hypotheses, and root cause analysis for dedicated "Analysis" or "Rationale" sections. ## Document Types Depending on the specific document you are asked to write or review, consult the relevant reference guide below: ### 1. Friction Logs Use when documenting a first-time user experience or walkthrough of a new tool, CLI, or API. **See:** [references/friction-logs.md](references/friction-logs.md) ### 2. Bug Reports Use when documenting a defect, crash, or unexpected behavior that requires a fix from library/tool maintainers. **See:** [references/bug-reports.md](references/bug-reports.md) ### 3. Known Issues Use when translating a "working as intended" bug or unfixable limitation into documentation intended to help end-users navigate the current state of a library. **See:** [references/known-issues.md](references/known-issues.md) ### 4. Commit Messages Use when authoring or reviewing git commit messages. Ensures the immediate technical "why" and factual record are clearly communicated for the permanent history. **See:** [references/commit-messages.md](references/commit-messages.md) ### 5. Pull Request Descriptions Use when authoring or reviewing pull request descriptions. Ensures the change is persuasively justified and broad context is provided for reviewers. **See:** [references/pr-descriptions.md](references/pr-descriptions.md)
Related Skills
wear-testing
Provides a guide and ADB commands for testing Wear OS applications. Focuses on triggering system state changes, simulating edge cases, and interacting with Wear-specific surfaces (tiles, complications, watchfaces). Triggers: wear os, testing, wear os testing, test wear os app, adb, pixel watch, galaxy watch.
jetpack
Resolves AndroidX/Jetpack library information including version lookup, package-to-Maven-coordinate conversion, and source code downloading. Provides tools for inspecting Jetpack library implementations. Use when working with androidx libraries, resolving Maven coordinates, downloading Jetpack source code, checking library versions (alpha/beta/stable/snapshot), or inspecting AndroidX class implementations. Triggers: androidx, jetpack, maven coordinate, jetpack source, library version, snapshot, alpha, beta.
emumanager
Manages Android SDK, emulators, and AVDs. Use when bootstrapping Android SDK, creating/starting/stopping AVDs, downloading system images, or troubleshooting emulator issues. Supports mobile, Wear OS, TV, and Automotive devices. Covers sdkmanager, avdmanager, emulator CLI. Triggers: android emulator, android virtual device, avd, system image, wear os emulator, tv emulator, automotive emulator, bootstrap android sdk.
coding-standards
Use this skill when writing, reviewing, or validating code (shell scripts, Python, Markdown) or CLI tools to ensure they follow repository coding standards and conventions. Also use when formatting git commit messages (Conventional Commits syntax, line wrapping) or checking code for style compliance. Triggers: coding standards, style guide, validate change, review conventions, shellcheck, shfmt, markdown format, python, ruff, uvx, lint, commit message format, CLI design, code review, formatting.
ai-tools
Command-line tools that delegate analysis tasks to AI models. Includes image description, screenshot comparison, smart cropping around people, token counting, essay generation from text, boolean condition evaluation, context gathering, and Android UI interaction via popper. Use for describing images, comparing UI states, cropping photos around faces, counting tokens, generating reports, evaluating conditions, gathering context for analysis, automating Android apps, testing Wear OS, or any task requiring AI inference. Triggers: ai analysis, describe image, compare screenshots, smart crop, crop around people, face crop, count tokens, token count, generate essay, evaluate condition, alt text, image description, UI comparison, visual diff, satisfies condition, boolean evaluation, gemini, context, gather context, research topic, android ui, adb, uiautomator2, popper, automate app, test wear os.
adb
Manipulates Android devices via ADB with emphasis on Wear OS. Provides scripts for screenshots, screen recording, tile management, WearableService inspection, package operations, and device configuration. Use when working with adb, Android devices, Wear OS watches, tiles, wearable data layer, dumpsys, or device debugging. Triggers: adb, android device, wear os, wearable, tile, screenshot, screen recording, dumpsys, logcat.
article-writing
Write articles, guides, blog posts, tutorials, newsletter issues, and other long-form content in a distinctive voice derived from supplied examples or brand guidance. Use when the user wants polished written content longer than a paragraph, especially when voice consistency, structure, and credibility matter.
copywriting
Write rigorous, conversion-focused marketing copy for landing pages and emails. Enforces brief confirmation and strict no-fabrication rules.
blog-writing-guide
This skill enforces Sentry's blog writing standards across every post — whether you're helping an engineer write their first blog post or a marketer draft a product announcement.
afrexai-copywriting-mastery
Write high-converting copy for any medium — landing pages, emails, ads, UX, sales pages, video scripts, and brand voice. Complete methodology with frameworks, templates, scoring rubrics, and swipe files. Use when writing or reviewing any user-facing text.
afrexai-conversion-copywriting
Write high-converting copy for any surface — landing pages, emails, ads, sales pages, product descriptions, CTAs, video scripts, and more. Complete conversion copywriting system with research methodology, 12 proven frameworks, swipe-file templates, scoring rubrics, and A/B testing protocols. Use when you need to write or review any copy meant to drive action.
human-writing
Guidelines and standards for professional, human-like writing and documentation. Use this skill when generating READMEs, technical documentation, code comments, or any formal written output to avoid common AI 'tells', buzzwords, and stylistic tropes. Ensure content follows the 'Professional Human in the Field' standard: high precision, zero fluff, and no emojis in technical contexts.