From skillry-documentation-and-tech-writing
Use when you need to write or classify learning-oriented and task-oriented documentation using the Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, and producing runnable, verified step-by-step instructions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skillry-documentation-and-tech-writing:304-tutorial-and-how-to-writingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Apply the Diátaxis framework to put each document in the right mode and write it well. Diátaxis splits docs into four kinds with different jobs: tutorials (learning-oriented, hold the reader's hand to a guaranteed success), how-to guides (task-oriented, get an experienced user through one real goal), reference (information-oriented, dry and complete), and explanation (understanding-oriented, th...
Apply the Diátaxis framework to put each document in the right mode and write it well. Diátaxis splits docs into four kinds with different jobs: tutorials (learning-oriented, hold the reader's hand to a guaranteed success), how-to guides (task-oriented, get an experienced user through one real goal), reference (information-oriented, dry and complete), and explanation (understanding-oriented, the why). The most common documentation failure is mixing these modes in one page. This skill keeps them separate and makes every instructional step runnable and verified.
Ask the reader's situation: are they learning (tutorial), trying to get a specific job done (how-to), looking something up (reference), or trying to understand (explanation)? Pick exactly one. If a draft serves two, split it.
A tutorial is a lesson, not a menu. Choose one concrete outcome, remove all optional branches, and ensure every learner who follows it lands in the same working state. State prerequisites and the end result up front.
A how-to assumes the reader knows the fundamentals and wants results. State the goal, list prerequisites, give the minimal ordered steps, and stop. Offer realistic variations ("if you use X instead of Y") but do not teach the basics.
Each step is one action with a copy-pasteable command and an observable result the reader can check.
# Pattern for every step: action + expected, checkable result
mkdir demo && cd demo
python3 -m venv .venv && . .venv/bin/activate
pip install example-package
example-cli --version
# Expected: example-cli 2.3.0
# Run the entire tutorial/how-to in a throwaway environment, unmodified
( set -e; cd "$(mktemp -d)"; \
echo "step 1..."; <command-1>; \
echo "step 2..."; <command-2> )
echo "exit: $?" # must be 0; any non-zero means a step is wrong
End with a "you should now see…" success check and a short troubleshooting list for the two or three most common failure points.
# Tutorial: Build your first widget pipeline
By the end you will have a running pipeline that processes one sample file.
**Prerequisites:** Python 3.11+, a terminal, ~10 minutes.
## 1. Create and enter a clean workspace
mkdir widget-tutorial && cd widget-tutorial
You should see an empty directory.
## 2. Install the toolkit
python3 -m venv .venv && . .venv/bin/activate
pip install widget-toolkit
Check: `widget --version` prints `widget 1.x`.
## 3. Run the pipeline on the sample
widget run --input sample.csv --out result.json
Check: `result.json` exists and contains a `count` field.
## You did it
You now have a working pipeline. Next, see the [how-to: process your own data](../how-to/custom-input.md).
## Troubleshooting
- `command not found: widget` → the venv is not active; re-run `. .venv/bin/activate`.
- Empty `result.json` → confirm `sample.csv` is non-empty.
# How-to: Rotate the service API key
**Goal:** replace the active API key with zero downtime.
**Prerequisites:** admin access, the `service-cli` installed.
1. Create a new key: `service-cli keys create --name rotated`
2. Deploy it as `SERVICE_API_KEY` (placeholder; never commit the value).
3. Verify traffic uses it: `service-cli keys usage --name rotated` shows > 0.
4. Revoke the old key: `service-cli keys revoke --name old`
Produce: (1) the Diátaxis classification and why; (2) the structured document with prerequisites, ordered runnable steps, and per-step expected results; (3) evidence the full path was run clean (exit 0); (4) a success check and troubleshooting section; (5) links out to reference/explanation rather than inlined theory.
$HOME-based paths, never real secrets or absolute machine paths.npx claudepluginhub fluxonlab/skillry --plugin skillry-documentation-and-tech-writingProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.