---
name: technical-writing
description: |
  Guide for writing effective technical documentation, specs, and markdown files. Use when creating or editing specs, documentation, READMEs, AGENTS.md files, or any markdown content in the codebase.
---

# Technical Writing

## Audience

Assume readers are at least as smart as you, so do not over-explain. State information once and move on.

## Style

Write concise, complete sentences using active voice and present tense. Each paragraph or bullet should express a single idea.

## Formatting

- Do not use emojis.
- Do not use bold or italics.
- Use headings, lists, and code blocks only when they add clarity.
- Use fenced code blocks with language identifiers.

## Paths

Always use relative file paths: `docs/testing.md`, not `/Users/name/project/docs/testing.md`.

## Do Not Repeat

Link to existing resources instead of duplicating content. Reference other docs, web pages, or files rather than restating their information.