sre-postmortem — Claude Code skill: what it does, how to install
sre-postmortem is a Claude Code skill that guides engineers through writing and reviewing blameless incident reviews based on Google SRE practices. It strips out blame and structures remediation tasks.
Apache-2.0 ★ 67 updated 2026-10-22
npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a claude-codeWhat sre-postmortem does
The skill enforces a clear postmortem workflow: establishing a UTC timeline, calculating quantitative impact, and isolating the trigger event from underlying root causes. It actively flags blameful wording or emotional phrasing, redirecting the text to system-level flaws such as missing validation, absent rate limits, or monitoring gaps.
Every remediation item must satisfy strict rules: a single owner, a linked issue tracker, a clear priority, and an objective success condition. The skill balances tasks across prevention, mitigation, and detection categories instead of relying purely on operational patches.
No API keys or background services are required. The skill relies entirely on prompts and the included references/postmortem-template.md template file.
What it helps with
- Draft structured blameless postmortems following Google SRE guidelines
- Remove finger-pointing and emotionally charged language from incident reports
- Separate the triggering action from systemic latent root causes
- Write verifiable engineering action items with explicit owners and priorities
- Audit existing incident reviews against a standardized review checklist
Example prompts for the agent
- Review this draft in incident-report.md and eliminate blame-oriented phrasing
- Generate action items with verifiable end states based on these outage notes
- Structure this raw incident timeline into a blameless postmortem using UTC times
How to install sre-postmortem
1Skills CLI (Vercel)
npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a claude-code2Manually: put the files in place
~/.claude/skills/sre-postmortem/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/sre-postmortem/
1Skills CLI (Vercel)
npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a codex2Manually: put the files in place
.agents/skills/sre-postmortem/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a cursor2Manually: put the files in place
.cursor/skills/sre-postmortem/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install paulip114/sre-practice-skills sre-postmortem2Manually: put the files in place
.github/skills/sre-postmortem/SKILL.md1Skills CLI (Vercel)
npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a gemini-cli2Platform CLI
gemini skills install https://github.com/paulip114/sre-practice-skills --path sre-postmortemManually: put the files in place
.devin/skills/sre-postmortem/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about sre-postmortem
How to install sre-postmortem in Claude Code?
Run npx skills add paulip114/sre-practice-skills --skill sre-postmortem -a claude-code or place the definition file directly at ~/.claude/skills/sre-postmortem/SKILL.md.
What does sre-postmortem do?
It instructs the AI to assist with writing, editing, and checking incident postmortems, emphasizing system conditions over individual human error and enforcing actionable follow-ups.
What are the action item requirements in sre-postmortem?
Every item requires one owner, a tracking ticket, an explicit priority, and a measurable outcome. Items must also balance prevention, mitigation, and detection.
Source text
SKILL.md · Apache-2.0
---
name: sre-postmortem
description: Use when writing, reviewing or improving a blameless postmortem — structuring the document, quantifying impact, separating trigger from root causes, writing concrete action items, removing blameful language, or building postmortem culture and follow-up tracking. Based on Google SRE practice.
---
# Blameless Postmortems
A postmortem is a written record of an incident: its impact, what was done, its root causes and contributing factors, and the follow-up that prevents recurrence. Its value is proportional to what people learn from it and what changes because of it.
## When one is required
Agree triggers in advance. Typical:
- User-visible downtime or degradation beyond a threshold.
- Data loss of any kind.
- On-call intervention such as a rollback or traffic reroute.
- Resolution time above a threshold.
- Monitoring failure (humans found it, not alerts).
- A single incident consuming a large share of error budget (per `sre-slos-and-error-budgets`).
- Anyone may request one for any event.
## Blamelessness
Assume everyone acted reasonably with the information and tools they had. Focus on **what** in the system allowed the failure, not **who**.
- Don't name individuals as the cause; describe the action and the conditions that made it possible ("the workflow was rerun manually; the tool had no guard against repeat execution").
- No loaded or emotional language ("careless", "ridiculous", "can't believe we survived"). Replace adjectives with data.
- Action items fix systems and processes, not people. "Train people to be more careful" is not a fix; a guard rail is.
- If leadership slips into blame, redirect to "what warning signs existed and why were they missed?"
## Procedure
1. **Assign one owner** (plus collaborators) as soon as the incident closes. Include everyone who participated in writing it.
2. **Pull the facts** from the incident state doc, chat logs, graphs, deploy history. Build the timeline in UTC.
3. **Quantify impact** with numbers: duration, affected users/requests/% of traffic, latency, revenue/budget impact, team cost. An estimate with its method stated beats no number.
4. **Analyse causes.** Separate the **trigger** (what set it off) from **root causes and contributing factors** (latent conditions that let the trigger cause damage — missing validation, no rate limit, unsafe default, monitoring gap). Keep asking why until you reach things you can change. Expect several contributing causes.
5. **Lessons learned**: what went well, what went poorly, where we got lucky (luck marks a hidden risk).
6. **Action items** — see criteria below. Group them by theme for large incidents.
7. **Review** with the checklist below; senior engineers review high-impact postmortems.
8. **Publish within about a week**, widely by default (whole engineering org; customers when appropriate). Delay lets memory fade and lets others fill the silence.
9. **Track action items to closure** in the normal bug tracker and review completion rates.
Template: `references/postmortem-template.md`.
## Action item criteria
Each action item must have:
- **One owner** and a **tracking ticket**.
- A **priority** — not all the same. At least one top-priority item for any user-affecting outage.
- A **verifiable end state**: "Alert when > X% of machines leave the pool within 10 min", not "improve alerting".
- A **type**, with a balance across types — not only mitigations:
- *Prevent* — stop this class from happening (input validation, safety checks, idempotency).
- *Mitigate* — reduce blast radius or duration (rate limits, kill switch, smaller rollouts).
- *Detect* — find it sooner (new alert, probe).
- *Repair / Investigate / Process* as needed.
## Review checklist
- [ ] Readable by someone outside the team (background + glossary for jargon)?
- [ ] Impact quantified, with sources linked?
- [ ] Trigger and root causes both identified, at sufficient depth?
- [ ] Timeline complete, with detection and mitigation times?
- [ ] Action items meet the criteria above, vetted by the service's tech lead?
- [ ] Blameless language throughout?
- [ ] Single owner, status, dates, sharing list filled in?
- [ ] Shared beyond the team?
## Building the culture
- Reward closing action items, not just writing documents.
- Celebrate good postmortems (reading clubs, weekly outage summaries, cross-team reviews).
- Use past postmortems for training (re-enact them as role-play drills).
- Add machine-readable metadata (services, trigger type, detection method, durations) so trends can be analysed across postmortems.
- Warning signs: people avoid being "involved", postmortems are late or shallow, the same incident recurs (are action items closing? is velocity trumping fixes?).
## Sources
- SRE book ch. 15 Postmortem Culture — https://sre.google/sre-book/postmortem-culture/
- SRE book Appendix D Example Postmortem — https://sre.google/sre-book/example-postmortem/
- SRE book ch. 16 Tracking Outages — https://sre.google/sre-book/tracking-outages/
- Workbook ch. 10 Postmortem Culture — https://sre.google/workbook/postmortem-culture/
- Workbook Appendix C Results of Postmortem Analysis — https://sre.google/workbook/postmortem-analysis/
© paulip114 · Apache-2.0 · paulip114/sre-practice-skills