Skip to content

ericrisco/rsc-harness / skills/technical-writing

technical-writing

Verified

Use when writing or fixing user-facing technical docs — a README, a getting-started tutorial, a how-to guide, or API/CLI/config reference — especially when a page tries to teach, explain and enumerate at once, a tutorial branches, a reference is padded with opinions, a README reads like a sales pitch, samples are stale, or weasel words have crept in. NOT an SEO blog article (that is `article-writing`), NOT the content calendar or pipeline (that is `content-engine`).

FileKindSize
SKILL.mdskill md11.7 KB
evals/README.mdmarkdown824 B
evals/cases.yamlconfig3.6 KB
references/diataxis-modes.mdmarkdown4.1 KB
references/vale-starter.mdmarkdown2.2 KB
scripts/verify.shexecutablescript2.6 KB

references/diataxis-modes.md

View on GitHub
# Diátaxis modes — templates, a worked split, and the banlist

The four modes (diataxis.fr/start-here, accessed 2026-06-02) each answer a
different reader question. Use this file when SKILL.md's classify table is not
enough — you have a real mixed page to break apart, or you need a full template.

## Per-mode templates

### Tutorial template

```md
# Build your first <thing>

By the end you will have <concrete outcome>.

## Before you start
- <tool> <exact version>
- <account/key> from <url>

## 1. <first action>
<command>
You should see: <visible result>

## 2. <next action>
...

## What you built
<one paragraph recap>. Next: <link to a how-to or explanation>.
```

Rules: linear, runnable on a clean machine, no branching, no rationale. If you
catch yourself writing "you could also", stop — that belongs in a how-to.

### How-to template

```md
# How to <achieve a specific goal>

Assumes you already <competence assumption>.

1. <step>
2. <step>
3. <step>

Done when: <observable success condition>.
```

Rules: goal in the title, competent reader, no concept teaching. Link out for
"what is X" rather than explaining inline.

### Reference template

```md
# <component / endpoint / command>

<one-line factual description>

## Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|

## Returns
| Field | Type | Description |
|---|---|---|

## Errors
| Code | Meaning |
|---|---|
```

Rules: dry, complete, consistent across entries, structured like the product,
zero opinions.

### Explanation template

```md
# About <concept> / Why <decision>

<context: what problem this addresses>
<the approach and the trade-off>
<alternatives considered and why this one>
```

Rules: prose, never numbered steps, opinion allowed *with* reasoning.

## Worked split: one mixed page into four

A page titled "Logging" tries to do everything:

> Logging helps you debug. Logging is asynchronous in Acme because blocking
> the request path would hurt latency. To set it up, run `acme init logging`,
> then set `LOG_LEVEL`. The logger accepts levels DEBUG, INFO, WARN, ERROR
> and a `sink` of `stdout|file|datadog`. We recommend `datadog` in production.

That single page mixes all four modes. Split it:

| Original sentence | Belongs in |
|---|---|
| "Logging helps you debug." | Cut — filler. |
| "Logging is asynchronous because blocking the request path would hurt latency." | **Explanation**: *Why Acme logs asynchronously* |
| "Run `acme init logging`, then set `LOG_LEVEL`." | **Tutorial** step *or* a **how-to** "How to enable logging" |
| "Levels: DEBUG…ERROR; `sink`: stdout/file/datadog." | **Reference**: the `logging` config table |
| "We recommend `datadog` in production." | **How-to** "How to ship logs to Datadog" (the opinion lives in the recipe's intro, not in reference) |

Result: four short pages, each scannable, each answering one question — instead
of one page answering none well.

## Weasel-word & AI-tell banlist

These words lie about difficulty, inflate, or signal machine-generated filler.
Delete or replace. This list is the source of truth for `scripts/verify.sh`.

| Banned | Why | Replace with |
|---|---|---|
| simply | Mocks the reader who is stuck | (delete) |
| just | Same — minimizes real effort | (delete) |
| easy / easily | Difficulty is the reader's to judge | (delete) |
| effortless / effortlessly | Marketing claim, unverifiable | (delete) |
| seamless / seamlessly | Means nothing concrete | name the actual behavior |
| robust | Vague reassurance | state the guarantee (e.g. "retries 3×") |
| powerful | Empty superlative | show what it does |
| blazing-fast / lightning-fast | Hype | give a number ("p50 12 ms") |
| supercharge | Marketing | describe the actual benefit |
| leverage | Jargon for "use" | use |
| utilize | Jargon for "use" | use |
| in order to | Always longer than needed | to |
| please (in steps) | Steps are imperatives | (delete) |
| log in / login (verb) | Style-guide preference | sign in |

When a step feels like it needs "simply", that is a signal the step is either
obvious (delete the word) or genuinely hard (add the missing detail instead).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall