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 |
| Writing, editing, or reviewing prose |
anti-ai-patterns.md |
| Reviewing a draft before it ships |
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:
- The actual code and repos — the project being written about, the relevant framework repo,
gh pr list --author aurorascharff
- Her real data — logs, runs, merged PRs
- 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.
1---2name: tech-writing3description: 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.4---56# Aurora's technical writing78Write 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.910## Files1112| Task | Read |13| ------------------------------------- | ------------------------------------------------ |14| Writing or editing any prose | [style-rules.md](style-rules.md) |15| Writing, editing, or reviewing prose | [anti-ai-patterns.md](anti-ai-patterns.md) |16| Reviewing a draft before it ships | [review-framework.md](review-framework.md) |1718Read style-rules.md and anti-ai-patterns.md before drafting, not after. Fixing voice in review is more expensive than writing in it.1920## What her voice actually is2122She 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.2324- **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."25- **Present tense, direct address.** "The browser still shows `/products` while the server routes to the encoded path."26- **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.27- **Honest and plain about trade-offs.** "This pattern is not something I invented." "This is a known limitation."28- **Some concrete, slightly colloquial texture is hers**, so don't sterilize: "shipping different red text", "popcorn UI", "hope you remember to tear it down".29- **Functional colons and inline lists are fine**: "the trade-offs these teams face: high cardinality, ISR limitations, and what cache components mean for it."30- **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.3132The failure mode to avoid is the opposite of hers: a polished reflective essay with literary rhythm and neat closers.3334Removing 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.3536## Source of truth hierarchy3738Never invent facts, numbers, PR titles, code, quotes, or claims about what she works on or how she works. Verify against, in order:39401. **The actual code and repos** — the project being written about, the relevant framework repo, `gh pr list --author aurorascharff`412. **Her real data** — logs, runs, merged PRs423. **Her published writing** — for voice only, never for facts that may have changed4344If 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.4546## Core principles4748| Principle | Do | Don't |49| ---------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |50| **Mechanism first** | Name the subject, the action, and the consequence | Dress up abstract things with figurative verbs |51| **Show, don't tell** | A real snippet or trimmed real artifact | A description of one, or an invented example |52| **Verify, don't assume** | Check the repo, the PR, her data | Write what sounds right |53| **Plain words** | "trimmed", "the logs in this post" | "excerpted", "leverage", "utilize" |54| **Choices, not features** | "we can give the agent a sandbox" | "the agent gets a sandbox per run" |55| **Honest about trade-offs** | "This is a known limitation." | Hype, superlatives, or hiding the catch |5657## What Aurora has asked for5859- Don't overstate scope. Check her PRs before describing her work.60- 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.61- Prefer real excerpts (real runs, real PR numbers, real quoted text) over invented examples.62- Stay honest and non-promotional about tools without saying that you're being honest.63- **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.6465## Content-type skills6667This skill is content-type-agnostic. Format-specific skills build on it and add their own structure and review items:6869| Content type | Skill |70| -------------------------------------- | ---------------------------------------------------------------------- |71| Blog posts (aurorascharff.no) | `.agents/skills/blog-writing/` in the `aurorascharff.no` repo |72| Social posts (X, Bluesky, LinkedIn) | `.agents/skills/social-media/` in the private Content folder |7374When 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.7576## Installing elsewhere7778The 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.
aurorascharff