runbook-generator
by alirezarezvanirunbook-generator creates operational runbook drafts for services using a Python CLI and templates for deployment, health checks, rollback, incident response, maintenance, and validation. Useful for SRE, DevOps, and Technical Writing teams standardizing on-call procedures.
This skill scores 74/100, which means it is acceptable for directory listing as a practical runbook scaffolding tool, but users should treat it as a baseline generator rather than a complete SRE runbook solution. The repository gives enough evidence for agents to trigger and run it correctly, with clear quick-start commands and a real Python script, though adoption clarity is limited by generic placeholder content and missing installation guidance.
- Clear trigger cases in the description and SKILL.md: new service runbooks, standardized incident response, on-call onboarding, and pre-production documentation.
- Includes an executable CLI script that can print or write a service-specific runbook with owner and environment fields.
- Provides supporting reference templates for deployment, incident response, database maintenance, staleness detection, and quarterly validation.
- Generated output is a generic skeleton with placeholders; teams must still supply real commands, URLs, escalation contacts, and rollback criteria.
- No install command or README is provided, so users must infer setup from the repository path and run the Python script directly.
Overview of runbook-generator skill
What runbook-generator does
runbook-generator is an engineering skill for creating operational runbook drafts for services that need deployment, incident response, maintenance, health check, and rollback documentation. It includes a Python helper script, scripts/runbook_generator.py, that can generate a structured Markdown runbook from a service name, owner, and environment, plus references/runbook-templates.md for more complete deployment, incident, database maintenance, staleness, and validation patterns.
Best fit for DevOps, SRE, and technical writing
The runbook-generator skill is a strong fit for platform teams, SREs, DevOps engineers, and technical writers who need a consistent starting point for service operations docs. It is especially useful when a new service is heading toward production, on-call engineers need a baseline playbook, or multiple teams are writing runbooks in inconsistent formats.
For Technical Writing, the value is not only generating a page quickly. The skill gives writers a practical structure for asking engineers the right questions: ownership, access, deployment checks, rollback triggers, escalation paths, verification steps, and review cadence.
What makes it different from a generic prompt
A generic AI prompt may produce a polished-looking runbook with missing operational details. runbook-generator is more grounded: it provides a repeatable CLI skeleton with standard operational sections and a reference file that highlights real runbook concerns such as staging dry-runs, explicit rollback triggers, smoke tests, quarterly validation, and staleness detection when deployment configs or CI files change.
Adoption considerations
This skill does not automatically inspect your infrastructure, service graph, CI/CD system, monitoring dashboards, or secret manager. The generated output is a scaffold, not an approved production procedure. Plan to replace example commands, add actual dashboards and alerts, verify rollback steps, and test the document in staging before publishing it for on-call use.
How to Use runbook-generator skill
runbook-generator install and files to inspect first
Install the skill in your Claude skills environment with:
npx skills add alirezarezvani/claude-skills --skill runbook-generator
Then review the source files before relying on it:
SKILL.md— capability summary, quick start, and recommended workflow.scripts/runbook_generator.py— the actual CLI generator and default Markdown sections.references/runbook-templates.md— extra templates for deployment, incident response, database maintenance, staleness detection, and quarterly validation.
Because the repository does not appear to include a separate README or metadata file for this skill, those three files are the most important reading path.
Basic runbook-generator usage
The script can print a runbook to stdout or write it to a file:
python3 scripts/runbook_generator.py payments-api
python3 scripts/runbook_generator.py payments-api --owner platform --output docs/runbooks/payments-api.md
If the script supports an environment argument in your installed version, use it to avoid vague “production/staging” assumptions. If not, edit the generated Markdown immediately and set the environment manually. The generated sections typically cover overview, preconditions, start and stop procedures, health checks, deployment checklist, rollback, incident response, escalation, and verification metadata.
Prompt the skill with operational specifics
A weak request is:
Generate a runbook for payments-api.
A stronger runbook-generator usage prompt is:
Use runbook-generator to create a production runbook for
payments-api. Owner isPlatform Payments. Runtime is Kubernetes on EKS. Deployment is via GitHub Actions and Helm. Health endpoint is/healthz. Logs are in Datadog, traces in Honeycomb, alerts in PagerDuty servicepayments-api-prod. Include rollback triggers for elevated 5xx rate, p95 latency over 800 ms, failed migrations, or payment authorization errors. Add placeholders where I need to confirm exact commands.
This improves output because the skill can map the scaffold to real operating decisions instead of inventing generic commands.
Recommended workflow after generation
Generate the first draft, then edit it with the service owner. Replace every example command with tested commands, add expected outputs, link dashboards and alert names, and define escalation contacts. Next, dry-run the procedure in staging: start, stop, deploy, health check, and rollback. Finally, add a Last verified date and schedule a quarterly review using the checklist in references/runbook-templates.md.
runbook-generator skill FAQ
Is runbook-generator enough for a production runbook?
Not by itself. runbook-generator creates a structured baseline, but production readiness depends on verified service-specific details. A production runbook should include real commands, access prerequisites, known failure modes, rollback decision points, links to dashboards, alert routing, escalation owners, and tested expected outputs.
When should I not use this skill?
Do not use it as the only source for safety-critical, compliance-heavy, or high-risk database operations. It can help scaffold database maintenance notes, but migration ordering, lock risks, backup validation, and restore procedures require engineering review. Also avoid publishing generated runbooks for systems you cannot test in staging.
How does it compare with an incident template?
An incident template usually focuses on triage, mitigation, communication, and postmortem follow-up. The runbook-generator skill is broader: it covers daily operational procedures such as start, stop, health checks, deployment, rollback, and escalation. For incident-heavy services, combine the generated runbook with the incident response template in references/runbook-templates.md.
Is it beginner friendly?
Yes, if the user understands the target service or can interview someone who does. Beginners benefit from the clear structure, but they may need help filling in deployment commands, observability links, severity rules, and rollback criteria. The skill is best used as a guided checklist, not as an autonomous infrastructure expert.
How to Improve runbook-generator skill
Improve runbook-generator inputs before asking for output
The biggest quality gain comes from better source facts. Before invoking runbook-generator, gather:
- Service name, owner, Slack channel, and escalation path.
- Environment, runtime, deployment tool, and CI/CD workflow.
- Health endpoints, smoke tests, dashboards, and alert names.
- Dependency list: databases, queues, APIs, caches, and third-party services.
- Rollback method, last-known-good release source, and rollback triggers.
- Recent incidents or known failure modes.
These details prevent the draft from becoming a generic operations page.
Replace placeholders with verifiable procedures
Common failure modes include vague steps like “check logs,” “monitor metrics,” or “rollback if needed.” Convert them into executable instructions:
- Instead of “check logs,” write the exact log query or dashboard link.
- Instead of “run smoke tests,” list commands and expected responses.
- Instead of “rollback if errors occur,” define thresholds and time windows.
- Instead of “contact owner,” name the PagerDuty service, Slack channel, and backup team.
A runbook is useful when an on-call engineer can follow it under pressure without guessing.
Use templates to expand beyond the default scaffold
After the first draft, use references/runbook-templates.md to add depth where the service needs it. For a deployment-heavy service, add pre-deployment checks, artifact verification, smoke tests, and communication notes. For incident response, add first-five-minute triage, diagnosis sources, mitigation options, and postmortem actions. For database work, add backup verification, lock-risk notes, sequencing, and restore checks.
Iterate after staging and real incidents
The best runbooks improve through use. After a staging dry-run, update broken commands, missing permissions, unclear expected outputs, and timing assumptions. After an incident, add what responders actually needed: faster diagnosis links, clearer severity mapping, safer mitigation steps, or a better rollback threshold. Keep the Last verified field current, and review the runbook whenever deployment configs, CI pipelines, schemas, or runtime environment files change.