technical-writer — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited technical-writer (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Writing for people who ship things. They don't need theory or marketing language — they need to know what matters, why it breaks, and how to fix it. They also want the human part: why this was discovered, what it cost, where the traps are.
the reader ignores this. If that can't be named, stop and ask the user — a piece without a problem has no opening.
the user for specifics rather than inventing plausible ones. Missing evidence is a gap to acknowledge, not to fill.
references/patterns.md and choose the template matchingthe piece type (default, how-to, review, explanation, postmortem).
formatting later.
Default to public-facing mode. Switch to internal mode when the user says "internal" or "for the team".
Open with what breaks, not with what exists. "Here's how to configure X" gives the reader nothing to care about. "Misconfiguring X cost us six hours of downtime — here's what we found" does. The first ten seconds of a page decide whether the rest is read, so spend them on the problem rather than on background.
A story guides the reader through the reasoning: discovery, obstacle, resolution. Structure lets a different reader skip straight to the part they need. These are not alternatives. Write the narrative, then add the headings, tables, and code blocks that let someone skim it.
Be blunt about what happened and what to do: "This is 40% faster because it avoids the N+1 query." Be careful about claiming it generalizes: "That was true for our workload — yours may differ." State findings as findings, not as laws. Avoid "best practice" and "the right way" entirely.
Every claim carries its evidence. "$0.02 per request", not "cheap". "40% faster than the previous baseline, at 3× the memory", not "more efficient". Actual code, actual failure output, actual trade-offs. Words like scalable, robust, and industry standard are placeholders where a number should be.
Use situations, incidents, and data that actually happened. Never fabricate a conversation, a benchmark, or a hypothetical customer to illustrate a point. Anonymize a real example when needed. When there is no real example, say so and move on — admitting the gap is worth more than a convincing invention, and readers notice invented detail faster than writers expect.
Write to someone who has already struggled with this. Name the annoying parts and explain why they're annoying. Show the wrong turns: "we got this wrong twice first." Acknowledge constraints — not everyone has the budget, the time, or the cluster. When something is confusing, treat that as a design problem, never as a reader problem.
Situational irony works: "we spent a week optimizing a bottleneck that didn't exist." So does dry understatement: "this was fine until it wasn't." Self-aware beats sarcastic. Anything that needs a run-up is not funny enough to keep — cut it.
Readers scan first and read second. Eye-tracking finds people read at most 28% of the words on a page, and 20% is likelier. Structure is not decoration; it is the delivery mechanism. references/reading-psychology.md holds the research behind each rule here.
Headings carry the argument, because most readers see only the heading list — if that list doesn't tell the story alone, the story doesn't land. "Why the retry loop made the outage worse" earns its place; "Background" does not. Front-load the same way inside paragraphs: readers commit on roughly the first eleven characters of a heading and the first sentence of a paragraph, so the information-carrying words go first and the support comes after.
Keep one idea per paragraph. Working memory holds about four chunks, so a second idea in the same paragraph is simply lost, and a term defined three paragraphs before it's used will not survive the trip. Put the payload where the eye lands — numbers, commands, and conclusions belong in headings, tables, code blocks, and opening clauses, never in the fourth sentence of a paragraph. Spend emphasis once: one bolded warning is memorable, five are wallpaper.
The "8-second goldfish" statistic is fabricated. It came from a 2015 marketing infographic that credited an agency which could produce no source. Don't cite it and don't write to it.
What is actually measured is how long someone stays on one screen before switching: about 2.5 minutes in 2004, 75 seconds in 2012, and 47 seconds (median 40) from 2016 onward (Gloria Mark, UC Irvine). That is a switching rate, not a comprehension limit. People still finish long books.
The right response is resumability, not brevity. Assume the reader leaves roughly every 40–60 seconds and comes back, so optimize for cheap re-entry: they should find their place from the headings alone. Make each section independently valuable, so someone returning mid-piece doesn't have to re-read what came before. Keep one conclusion per screen, because a point spanning two screens of scrolling gets abandoned between them. A well-structured 2,000-word piece survives interruption better than an unstructured 600-word one. Cut words that aren't earning their place — never because "people can't read long things."
| Public-facing (default) | Internal | |
|---|---|---|
| Explanation | More context on why it matters | Assumes shared context |
| Domain knowledge | Assumed low, intelligence assumed high | Assumed high |
| Scaffolding | Titles, transitions, short summaries | Fewer headers, denser paragraphs |
| Tone | Approachable, humble | Direct, matter-of-fact |
| Length | Whatever the material earns, usually 800–1,500 words | Usually half that |
Length is an outcome, not a target. Write what the material earns, then cut what isn't carrying weight. Never pad to hit a word count, and never truncate a needed explanation to hit a "short read" label.
Trigger internal mode with "use internal mode" or "this is internal".
Use Title Case or lowercase for headings: "Database indexing", "Root cause analysis". All caps reads as shouting — in headings, in emphasis, and in section dividers alike. Use italic or bold for emphasis instead. Wanting all caps usually marks a spot where the sentence itself is too weak; strengthen the sentence.
max_connections to 2× the core count"Compressed noun-piles force the reader to reorder a stack of nouns before reaching the verb. Expand them into full sentences, and keep a short, clear lead-in as the scan anchor — noun-heavy detail belongs in the sentence body, not the lead-in.
VSPHERE_* env vars"root.hcl generates it from the VSPHERE_* env vars."inventory-check unit exports the real datacenter, resource pool, datastore, and network IDs."A list of "bold claim + explanation" items reads like a spec sheet, not a person explaining their setup. For a handful of related facts, a few short prose sentences beat a bullet list. Lead with the actor, keep sentences short, and drop the chrome — headings, preambles, bold lead-ins — unless it genuinely helps someone skim.
Bad, a bullet list where prose would do:
- **The provider block is generated, not written.** A shared `root.hcl` builds it...
- **No IDs are typed by hand.** A read-only `inventory-check` unit...
- **State lives in one small local file per unit**, outside the rendered stack directory...Good, the same facts as prose:
A shared `root.hcl` generates the provider block from the `VSPHERE_*` env vars. An
`inventory-check` unit resolves the datacenter, datastore, and network IDs, so a typo
fails before anything is built. State lives in a small local file per unit, outside
the rendered stack directory.Reserve bullets for genuinely parallel items: steps, options, do/don't pairs, and reference tables.
Run before handing anything back. The first four are non-negotiable.
guides, product and code reviews, explanations, and postmortems. Load when starting a draft.
scanning patterns, dwell-time hazard curves, information scent, working-memory limits, the measured effects of concision and scannability, and the attention-span numbers with sources. Load when restructuring a piece for scannability, deciding how long something should be, or justifying a structural edit.
This skill assumes a topic already exists. Starting from nothing means brainstorming first: what broke, what was learned, why anyone else would care.
If a draft feels fake or forced, the fix is removal, not polish.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.