postmortem skill
✓ VerifiedWrite blameless postmortem documents to analyze production incidents and identify systemic contributing factors.
- GitHub stars
- 26
- Files
- 1
- Last commit
- Oct 19, 2026
- License
- MIT
- Allowed tools
- —
What does the postmortem skill do?
postmortem writes blameless postmortem documents to analyze production incidents and identify systemic contributing factors.
Summary generated from the skill's SKILL.md.
About the postmortem skill
Analyzing production incidents to find systemic improvements is what this skill enables for engineering teams. When an agent receives a request for a post-incident review, a PIR, or a 5 whys analysis, it applies methodologies from the Google SRE Book and Sidney Dekker to generate a structured document. It moves beyond identifying human error to uncovering the technical, process, knowledge, or capacity factors that allowed a failure to occur.
An agent uses this skill to transform raw incident data into a formal report containing a precise timeline, a summary of impact, and a detailed analysis of contributing factors. It produces actionable items that include specific owners, due dates, and priority levels. The output is designed to be shared across an organization to prevent similar failures in other teams. By focusing on prevention, detection, and mitigation, the tool ensures that every incident results in concrete system changes rather than just storytelling.
What an agent can do with it
- 1Generate a SEV1 incident reportCreate a formal postmortem document for a high-severity incident within 48 hours of resolution.
- 2Define actionable engineering tasksConvert incident findings into specific tasks with assigned owners and priority levels.
- 3Reconstruct incident timelinesBuild a chronological sequence of system events, alerts, and human actions during a service outage.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the postmortem skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the postmortem skill in Claude Code
~/.claude/skills/postmortem/SKILL.md
$ npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem ~/.claude/skills/postmortemInstall the postmortem skill in Claude Code (project)
.claude/skills/postmortem/SKILL.md
$ npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem .claude/skills/postmortemInstall the postmortem skill in Codex
~/.agents/skills/postmortem/SKILL.md
$ npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem ~/.agents/skills/postmortemInstall the postmortem skill in Gemini CLI
~/.gemini/skills/postmortem/SKILL.md
$ npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem ~/.gemini/skills/postmortemInstall the postmortem skill in Claude.ai
npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem postmortem && zip -r postmortem.zip postmortem # claude.ai → Customize → Skills → + → Create skill → Upload a skill → postmortem.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableqa-aman/claude-skills/skills/by-role/devops/postmortem is public and reachablegithub.com/qa-aman/claude-skills/tree/HEAD/skills/by-role/de ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-19github.com/qa-aman/claude-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/qa-aman/claude-skills/blob/HEAD/skills/by-role/de ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/qa-aman/claude-skills/blob/HEAD/skills/by-role/de ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 147 linesgithub.com/qa-aman/claude-skills/blob/HEAD/skills/by-role/de ↗Pass
SKILL.md
View on GitHubOverview
Based on "The Field Guide to Understanding Human Error" by Sidney Dekker and the Google SRE Book. Dekker's fundamental insight: human error is never the cause of an incident - it is a symptom of a system that put people in a position where mistakes were likely. A blameless postmortem asks not "who made the mistake?" but "what conditions made this mistake likely, and how do we change those conditions?"
Google SRE's postmortem culture: incidents are opportunities to improve systems, not to assign blame. Engineers who feel safe reporting mistakes surface problems before they become incidents.
Workflow
Step 1: Schedule within 48 hours (SEV1) or 1 week (SEV2)
Postmortems decay in value quickly. Memories fade, context is lost. Set the meeting within 48 hours of a SEV1 resolution.
Attendees: IC, Operations Lead, on-call engineer(s), and anyone who can contribute to understanding what happened. No executives in the room - their presence changes behavior.
Step 2: Build the timeline
Reconstruct what happened in chronological order. Be precise about times.
Timeline:
[HH:MM] - [what happened - system event, human action, or observation]
[HH:MM] - [alert fired: name]
[HH:MM] - [on-call engineer paged]
[HH:MM] - [first action taken]
[HH:MM] - [mitigation applied]
[HH:MM] - [service restored]
Include: system events, alerts, human decisions, and the reasoning people had at the time.
Step 3: Identify contributing factors (not root cause)
Dekker's principle: complex systems rarely have a single root cause. They have contributing factors that aligned to create conditions for failure.
For each contributing factor, ask: "If this had been different, would the incident have been less likely or less severe?"
Common contributing factor categories:
- Technical: insufficient alerting, missing circuit breakers, inadequate testing
- Process: no deployment checklist, unclear escalation path, missing runbook
- Knowledge: alert with no runbook, undocumented dependency, new team member
- Capacity: system at limits, team understaffed, alert fatigue
Step 4: Apply the 5 Whys
For the primary contributing factor, drill down:
- Why did X happen? - Because Y
- Why did Y happen? - Because Z
- Why did Z happen? - Because...
Stop when you reach a level where an action item can change the system. "Because the engineer made a mistake" is never the stopping point - that's where the analysis begins.
Step 5: Write action items
Every postmortem must produce action items. Without them, it's just storytelling.
Each action item:
Action: [specific thing to do]
Owner: [named person, not "the team"]
Due: [specific date]
Priority: [P1 - fix before next deploy / P2 - this sprint / P3 - this quarter]
Type: [Prevention / Detection / Mitigation / Process]
Action types:
- Prevention - stops this failure mode from occurring
- Detection - makes the problem visible sooner
- Mitigation - reduces impact when it does occur
- Process - changes how the team responds
Step 6: Write the postmortem document
Postmortem: [Incident title]
Date: [incident date]
Authors: [IC + contributors]
Severity: [SEV1/SEV2]
Duration: [start to resolution]
Impact: [users affected, features degraded]
Summary
[2-3 sentences: what happened, why it mattered, how it was resolved]
Timeline
[full timeline from Step 2]
Contributing Factors
[bullet list from Step 3 - no blame language]
5 Whys Analysis
[drill-down from Step 4]
What Went Well
[what helped contain or resolve the incident faster]
Action Items
[table from Step 5]
Lessons Learned
[2-3 insights that are generalizably useful beyond this specific incident]
Step 7: Share broadly
Postmortems are most valuable when shared. Publish to an internal wiki, engineering all-hands, or team newsletter. Other teams often have the same latent failure modes.
Anti-Patterns
1. Blame language Bad: "The engineer deployed without testing." Good: "The deployment process did not have a required staging environment check, making it possible to deploy untested code." Dekker: blame stops investigation. "Human error" as a cause explains nothing and changes nothing.
2. No action items Bad: Postmortem documents what happened but ends without concrete next steps. Good: Every postmortem produces at least 2 action items with owners and dates. Track them to completion.
3. Postmortem after the deadline Bad: "We'll get to it when things calm down." (more than 1 week for SEV1) Good: Timebox it. A 60-minute postmortem within 48 hours is worth more than a 2-hour postmortem 3 weeks later.
4. Only focusing on what went wrong Bad: Pure failure analysis, nothing about what was done right. Good: Include "What went well." The practices that helped contain the incident should be reinforced, not just the failures fixed.
Quality Checklist
- Scheduled within 48h (SEV1) or 1 week (SEV2)
- Timeline is precise (specific times, not "around noon")
- Contributing factors identified with no blame language
- 5 Whys drilled to a system-level cause, not a person
- Every action item has: owner (named), due date, priority, type
- "What went well" section included
- Document shared with broader engineering team
- Action items tracked to completion in next retrospective
Files in this skill
1postmortem skill questions
How do I install the postmortem skill in Claude Code?
Run npx degit qa-aman/claude-skills/skills/by-role/devops/postmortem ~/.claude/skills/postmortem. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the postmortem skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How should contributing factors be identified?
Instead of looking for a single root cause, identify contributing factors across technical, process, knowledge, and capacity categories, asking if the incident would have been less likely if the factor were different.
What information must every action item include?
Each action item must specify a task, a named owner, a due date, a priority level, and a type such as prevention, detection, mitigation, or process.