mcpField
R
runbook

runbook

github.com/julianobarbosaDocuments1456 installsUpdated 3d ago
Repository

About runbook

runbook is a skill for finding an existing operational runbook or creating one from a template. It emphasizes validating steps, prerequisites, rollback procedures, and freshness before an incident.

Key features

  1. 01Search runbooks by topic
  2. 02Display matching runbooks
  3. 03Create runbooks from a template
  4. 04Save with kebab-case filenames
  5. 05Highlight validation and staleness risks

Use cases

  1. 01Find procedures during incident response
  2. 02Draft a runbook for an operational topic
  3. 03Review prerequisites and rollback steps

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill runbook

After installing, type/runbookin Claude Code to confirm it loaded.

Details

From the project README

Runbook — Create or load an operational runbook

When invoked with a topic (e.g., /runbook ARI management group):

  1. Search runbooks/ for existing runbooks matching the topic
  2. If found, load and display the runbook
  3. If not found, create a new one using this template:
# Runbook: {{title}}

## Purpose
[One sentence — when and why to use this]

## Prerequisites
-

## Steps
1.

## Verification
- [ ]

## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|

## Last Tested
{{date}}

Save to runbooks/ with a kebab-case filename.

Gotchas

  • Stale runbooks are worse than no runbook: A runbook last tested 18 months ago lies confidently about command flags, dashboard URLs, and rollback paths. Treat anything past Last Tested of 90 days as suspect and re-validate before trusting it under incident pressure.
  • Untested rollback steps are decorative: "Run terraform destroy" without ever having executed it from this state means you don't know if it works. Rollback steps must have been rehearsed at least once on a non-prod replica, not just written down.
  • Missing prerequisites cause runbooks to fail at 2am: "Just run the script" assumes kubectl context, VPN, sudo on the bastion, and an active token. List every prerequisite with the exact verification command — the on-call engineer is not you with your terminal open.
  • Copy-pasted steps that worked once are not procedure: A kubectl patch command captured from a working session may hardcode a pod name, timestamp, or specific resource version. Parameterize anything that varies between executions or it will fail the second time.
  • Verification checkboxes without commands are aspirational: "Verify the service is healthy" is not a step — curl -fsS https://x/healthz | jq .status is. Every verification line should be a copy-pasteable command with the expected output noted.
  • Runbooks rot silently when systems change: Renaming a deployment, rotating a key vault name, or changing an ingress host invalidates the runbook with no signal. Link each runbook from the system's IaC repo so changes to infrastructure trigger a runbook review.

Comments

Markdown supported