writing-runbooks skill (riekelt) for Claude Code: runbooks, setup guides and migration guides

Makes Claude write runbooks and setup guides that someone can follow under time pressure: ordered steps, copy-paste commands, a rollback for each change.

Installs: 20.5K; on skills.sh
Stars: 36; on GitHub
Updated: Sep 2026; last repo commit

writing-runbooks covers any ordered procedure someone will execute. Steps are numbered, one action each, and every command is copy-pasteable with real example values. Risk is shown by a legend, a happy-path summary comes first and every state-changing procedure names its rollback. Troubleshooting entries start from the symptom, and migration guides get a mapping table and dated deprecation. SKILL.md says to write from a real run, and to label a procedure that has not been run as a draft. It lists technical-writing as required background.

Good for

On-call engineers and SREs who write procedures others will run
Teams writing setup guides, release procedures or troubleshooting entries
Maintainers publishing a migration or deprecation guide

Install writing-runbooks

Claude Code

Copy this prompt.

Install the writing-runbooks skill in Claude Code. Run this command:

/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The skills CLI route must include technical-writing, which writing-runbooks lists as REQUIRED BACKGROUND in its SKILL.md.

From the project README. Source.

What's in the skill

When it loads

Use when writing operational documentation - runbooks, setup guides, release procedures, migration guides, deprecation guides, troubleshooting entries, or any ordered procedure someone will execute under time pressure. Encodes the runbook skeleton, the risk legend, the symptom-first troubleshooting format, and the migration-guide rules (mapping table, mandatory rollback, deprecation dates, built-in expiry). Use whenever someone will execute the text, even if it is called a "guide" or "setup notes".

Sections in SKILL.md

Overview
When to invoke, and not
Structure
Troubleshooting entries
<symptom as the user sees it>
Migration and deprecation guides
Operator-facing strings

Key facts

Author: riekelt (owner of the GitHub repo)
License: MIT (LICENSE file and plugin manifest)
Installs on skills.sh: 20,511 as of 2026-11-02
GitHub stars: 36 for the whole riekelt/technical-writer repo, 2026-11-02
What is inside: 1 file: SKILL.md
Needs: The technical-writing skill (SKILL.md lists it as REQUIRED BACKGROUND)
Part of: The technical-writer plugin: 11 skills, 2 agents and 2 commands
Last repo commit: 2026-09-13
Works in: Claude Code per the README install section. The repo also ships Codex and Cursor plugin manifests.

What it includes

Scope title, risk legend, happy path first, numbered steps
The title carries the scope, the opening says what the document does not cover, a legend marks safe, operator-only and manual steps, and prerequisites come before commands with a check command each.
Write · Structure
Concrete values, variants labelled inside the code block
Every command runs as written, with example values, and a safe-mode and live-mode variant are labelled in the same block. Steps state the consequence of doing them in the wrong order.
Write · Copy-pasteable commands
Every state-changing step names its undo and an end check
A procedure names its rollback or says plainly that none exists, and ends with a verify-it-worked section holding the observable end state and the command that proves it.
Write · Rollback and verify
Symptom, cause and fix, cheapest check first
Entries start from the symptom as the user sees it, quote error strings verbatim so they can be searched, and group by failure class.
Write · Troubleshooting entries
Five extra rules, including a mapping table and dated removal
History is the content here. The core artifact is an old-to-new mapping table. Rollback is required per step, deprecation carries dates, and the guide is reclassified as historical when the migration completes.
Try: “Write a migration guide from v1 to v2 of our API client with a mapping table and rollback for each step.”
Write · Migration and deprecation guides
Error and log messages get the same treatment
Remediation text in error messages and log lines stays specific and actionable.
Write · Operator-facing strings

From the official docs

Permissions

Low risk

Claude writes procedures that may contain commands changing real systems. Try a new runbook on a test system before you rely on it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The runbooks can contain risky commands
SKILL.md has Claude write procedures with commands, some tagged operator-only (writes to production) in the risk legend. The skill writes the text; you decide what to run. Our advice: test a new runbook in a safe environment before relying on it. github.com
The plugin route adds 2 agents and 2 commands
The plugin ships agents prose-reviewer and doc-grounder (both with Read, Glob, Grep and Bash tools) and the commands /prose-review and /ground-docs. The plugin folder has no hooks or MCP config. Use the skills command in the install box if you want only this skill. github.com

Technical details

Turning on read-only	No read-only mode. The skill tells Claude to write or edit documents.
Sign-in and keys	SKILL.md names no account or API key.
Data retention	SKILL.md names no logging or telemetry.
Scopes	Claude drafts and edits runbook documents in your repo

Questions

What does writing-runbooks do?

It makes Claude write operational documents in a hurry-proof shape: ordered steps, copy-pasteable commands, a risk legend, a rollback for each change and a verify step.

How do I install writing-runbooks?

Use the install box at the top of this page. The plugin route installs the whole set. The skills command route names technical-writing as well, because this skill lists it as required background.

Will Claude invent steps it has not run?

SKILL.md says to write from a real run and to label a procedure with no real run behind it as a draft. When a value is unknown, the placeholder stays visibly bracketed.

Does it cover migration guides?

Yes. It has a section for migration and deprecation guides with a mapping table, a rollback per step and dated removal. The argument for the migration belongs in a design doc, written with writing-design-docs.

writing-runbooks vs writing-design-docs?

A runbook is executed, a design doc is argued. SKILL.md says not to use runbooks for design rationale or for reference material nobody executes.

Is writing-runbooks safe to install?

The skill folder holds only SKILL.md, so it bundles no scripts. It makes Claude write and edit runbook documents in your repo, and the runbooks can contain commands that change systems, some marked as writing to production. Review the diff, as you would any edit. Our advice: run a new runbook yourself in a safe environment before you rely on it.

Can I use writing-runbooks in the Claude app or Cursor?

The README documents Claude Code, and the repo also ships Codex and Cursor plugin manifests. It does not mention the Claude app. Our advice: this page offers no Claude app upload because the skill works on documents inside a repository, so use Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: riekelt/technical-writer
Folder: plugins/technical-writer/skills/writing-runbooks

riekelt/technical-writer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

README · github.com
marketplace.json · github.com
writing-runbooks on skills.sh · skills.sh
SKILL.md · github.com
LICENSE · github.com