# Tech Writing

> Aurora's technical writing voice, for any content in any repo — blog posts, READMEs, docs, talk notes, social posts. Use when writing, editing, or reviewing anything she publishes under her name. Routes to style rules, anti-AI patterns, and a review framework; content-type skills (like blog-writing) build on this one.

- Skill: `aurorascharff/tech-writing` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aurorascharff/tech-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aurorascharff/tech-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: aurorascharff (https://skillmd.com/u/aurorascharff)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aurorascharff/tech-writing

---


# Aurora's technical writing

Write like Aurora Scharff explaining something she built or learned: a working engineer, first person, calm, specific. Not marketing, not a docs page, not an AI think-piece.

## Files

| Task                                  | Read                                             |
| ------------------------------------- | ------------------------------------------------ |
| Writing or editing any prose          | [style-rules.md](style-rules.md)                 |
| Writing, editing, or reviewing prose  | [anti-ai-patterns.md](anti-ai-patterns.md)       |
| Reviewing a draft before it ships     | [review-framework.md](review-framework.md)       |

Read style-rules.md and anti-ai-patterns.md before drafting, not after. Fixing voice in review is more expensive than writing in it.

## What her voice actually is

She writes like a concrete technical explainer, not a narrative essayist. The prose explains how something works, step by step, with real code and honest notes on trade-offs.

- **Concrete and mechanism-first.** "Any component that calls a dynamic API like `cookies()` or `headers()` opts into dynamic rendering. When that happens in a root layout, every page nested under it becomes dynamic too."
- **Present tense, direct address.** "The browser still shows `/products` while the server routes to the encoded path."
- **Short clarifying sentences are welcome** when they land a point. "The user clicks retry and nothing changes." Clarity beats flow; the enemy is the rhetorical punch line, not the short sentence.
- **Honest and plain about trade-offs.** "This pattern is not something I invented." "This is a known limitation."
- **Some concrete, slightly colloquial texture is hers**, so don't sterilize: "shipping different red text", "popcorn UI", "hope you remember to tear it down".
- **Functional colons and inline lists are fine**: "the trade-offs these teams face: high cardinality, ISR limitations, and what cache components mean for it."
- **She'll coin and italicize a term** when it earns it (*popcorn UI*), and use "we" for a teaching walkthrough, "I" for her own experience.

The failure mode to avoid is the opposite of hers: a polished reflective essay with literary rhythm and neat closers.

Removing AI tells is only half the edit. Keep the first-person opinion, concrete reactions, and changes in sentence length that give the draft a real speaker. Do not polish away a useful aside or honest uncertainty to make the structure more symmetrical.

## Source of truth hierarchy

Never invent facts, numbers, PR titles, code, quotes, or claims about what she works on or how she works. Verify against, in order:

1. **The actual code and repos** — the project being written about, the relevant framework repo, `gh pr list --author aurorascharff`
2. **Her real data** — logs, runs, merged PRs
3. **Her published writing** — for voice only, never for facts that may have changed

If you can't verify something, ask, leave it out, or mark it `[VERIFY]` inline and say what needs checking. A confident wrong claim is the worst failure mode, and she checks. Treat every plausible-sounding detail as something to confirm, not assume. Verify against the source itself (the repo, the docs, the PR), never against a reviewer's or summarizer's account of it.

## Core principles

| Principle                    | Do                                                                    | Don't                                                            |
| ---------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Mechanism first**          | Name the subject, the action, and the consequence                     | Dress up abstract things with figurative verbs                    |
| **Show, don't tell**         | A real snippet or trimmed real artifact                               | A description of one, or an invented example                      |
| **Verify, don't assume**     | Check the repo, the PR, her data                                      | Write what sounds right                                           |
| **Plain words**              | "trimmed", "the logs in this post"                                    | "excerpted", "leverage", "utilize"                                |
| **Choices, not features**    | "we can give the agent a sandbox"                                     | "the agent gets a sandbox per run"                                |
| **Honest about trade-offs**  | "This is a known limitation."                                         | Hype, superlatives, or hiding the catch                           |

## What Aurora has asked for

- Don't overstate scope. Check her PRs before describing her work.
- Read the whole piece for contradictions. Claims across sections have to line up; if two paragraphs disagree, find the real distinction and state it once.
- Prefer real excerpts (real runs, real PR numbers, real quoted text) over invented examples.
- Stay honest and non-promotional about tools without saying that you're being honest.
- **Never describe how she works, reads, or does something unless you've confirmed it.** Inventing her behavior or workflow to make a point land is worse than leaving it out.

## Content-type skills

This skill is content-type-agnostic. Format-specific skills build on it and add their own structure and review items:

| Content type                          | Skill                                                                 |
| -------------------------------------- | ---------------------------------------------------------------------- |
| Blog posts (aurorascharff.no)          | `.agents/skills/blog-writing/` in the `aurorascharff.no` repo          |
| Social posts (X, Bluesky, LinkedIn)    | `.agents/skills/social-media/` in the private Content folder           |

When a content-type skill exists for the task, read its `SKILL.md` too; it inherits everything here and its checklist runs on top of the review framework. To add a new content type (talks, social threads), create a sibling skill that starts by pointing here, and register it in this table.

## Installing elsewhere

The source of truth for this skill lives in the `aurorascharff.no` repo. To use it in another repo, copy the whole `tech-writing/` directory into that repo's `.agents/skills/`; keep edits flowing back to the source copy.