postmortem-writer — Claude Code skill: what it does, how to install
postmortem-writer turns an incident into a written postmortem: timeline, root cause, contributing factors, action items with owners. Runs as a skill inside your coding agent.
MIT 265 installs ★ 64 updated 2026-01-12
npx skills add patricio0312rev/skills --skill postmortem-writer -a claude-codeWhat postmortem-writer does
The skill drafts a postmortem document in Markdown. Sections cover the summary, measured impact, a timestamped timeline, the root cause with the offending code diff, contributing factors, what went well and what did not, plus a table of follow-up work with an owner and a due date on every row.
A worked example ships with it: an API outage caused by an exhausted database connection pool. A separate block spells out blameless rules — examine systems and processes, keep individuals out of the write-up. The appendix entries for monitoring graphs, the customer communication log and the fix PR stay as bracketed placeholders. The skill writes the document; telemetry it does not read.
So the numbers come from you. Hand over timestamps and counts of affected users, or the impact section and the timeline stay vague. A closing checklist reminds you to hold the review meeting, share the file and book the follow-up.
What it helps with
- build a minute-by-minute incident timeline
- trace the root cause without pinning it on the on-call engineer
- assign every follow-up task an owner and a due date
- record what held up during the outage
- audit a postmortem draft against a checklist
Example prompts for the agent
- Write the postmortem for yesterday's API outage. Timeline runs 14:15 to 14:57 UTC, root cause is a connection leak in
v2.3.4. - Draft a blameless incident review: what went well, what didn't, and action items with owners and due dates.
- Check this postmortem draft against the output checklist and list what's still open after the review meeting.
How to install postmortem-writer
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill postmortem-writer -a claude-code2Manually: put the files in place
~/.claude/skills/postmortem-writer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/postmortem-writer/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill postmortem-writer -a codex2Manually: put the files in place
.agents/skills/postmortem-writer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill postmortem-writer -a cursor2Manually: put the files in place
.cursor/skills/postmortem-writer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills performance/postmortem-writer/SKILL.md2Manually: put the files in place
.github/skills/postmortem-writer/SKILL.md1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill postmortem-writer -a gemini-cli2Platform CLI
gemini skills install https://github.com/patricio0312rev/skills --path performance/postmortem-writerManually: put the files in place
.devin/skills/postmortem-writer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill postmortem-writer -a opencodeClaude.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 postmortem-writer
How do I install postmortem-writer in Claude Code?
Run npx skills add patricio0312rev/skills --skill postmortem-writer -a claude-code. The skill file lands at ~/.claude/skills/postmortem-writer/SKILL.md.
What does postmortem-writer do?
It produces a post-incident document: summary, impact, timeline, root cause, contributing factors and action items with named owners.
Is the postmortem blameless?
Yes. A guidelines block tells the agent to look at systems and processes rather than people, and to avoid turning the review into a blame session.
Source text
SKILL.md · MIT
---
name: postmortem-writer
description: Creates comprehensive post-incident documents with timeline, root cause analysis, contributing factors, action items, and ownership. Follows SRE best practices for blameless postmortems. Use for "postmortem", "incident review", "RCA", or "post-incident".
---
# Postmortem Writer
Document incidents for learning and improvement.
## Postmortem Template
```markdown
# Postmortem: API Outage - Database Connection Pool Exhausted
**Date:** 2024-01-15
**Authors:** Jane Doe (On-call), John Smith (DBA)
**Status:** Complete
**Severity:** P1 (Critical)
## Summary
On January 15, 2024, our API experienced a complete outage for 25 minutes (14:32 - 14:57 UTC) affecting 100% of users. The root cause was database connection pool exhaustion triggered by a connection leak introduced in deployment v2.3.4.
**Impact:**
- Duration: 25 minutes
- Users affected: ~50,000
- Requests failed: ~125,000
- Revenue impact: ~$15,000
## Timeline (All times UTC)
| Time | Event |
| ----- | ------------------------------------------------ |
| 14:15 | v2.3.4 deployed to production |
| 14:32 | First CloudWatch alarm: HighErrorRate |
| 14:33 | PagerDuty alert sent to on-call (Jane) |
| 14:35 | Jane acknowledges, begins investigation |
| 14:38 | Identified: Database connection pool at 100% |
| 14:40 | Attempted: Kill long-running queries (no effect) |
| 14:43 | Decision: Rollback to v2.3.3 |
| 14:45 | Rollback initiated |
| 14:47 | Rollback complete, connections dropping |
| 14:50 | Error rate returning to normal |
| 14:57 | All systems recovered, incident closed |
| 15:30 | Postmortem meeting scheduled |
## Root Cause
A code change in v2.3.4 introduced a connection leak in the user profile endpoint. The new caching layer was not properly releasing database connections after queries completed.
**Code diff:**
\`\`\`diff
- await prisma.user.findUnique({ where: { id } });
* const client = await pool.connect();
* const user = await client.query('SELECT \* FROM users WHERE id = $1', [id]);
* // Missing: client.release() ❌
\`\`\`
## Contributing Factors
1. **Insufficient testing:** Load tests didn't catch the leak
- Tests only ran for 5 minutes
- Not enough concurrent connections to exhaust pool
2. **Missing monitoring:** No alerts on connection pool metrics
- Had alarms for query latency
- No alarms for active connections count
3. **Inadequate code review:** Reviewer didn't spot missing release()
- PR approved without running locally
- No checklist for connection management
4. **Deployment process:** No gradual rollout
- Deployed to 100% of production immediately
- No canary deployment
## What Went Well
1. ✅ **Fast detection:** Alert fired within 3 minutes
2. ✅ **Clear runbook:** DBA runbook had exact steps to follow
3. ✅ **Quick decision:** Made rollback decision in 8 minutes
4. ✅ **Communication:** Status page updated every 5 minutes
5. ✅ **Rollback capability:** Automated rollback took <2 minutes
## What Went Wrong
1. ❌ **Code review missed bug:** Connection leak not caught
2. ❌ **Testing gaps:** Load tests insufficient duration
3. ❌ **No canary:** Deployed to all instances at once
4. ❌ **Late detection:** 17 minutes between deploy and alert
## Action Items
| Action | Owner | Due Date | Priority | Status |
| --------------------------------------------- | ------- | ---------- | -------- | -------------- |
| Add connection pool metrics to dashboards | Jane | 2024-01-20 | P0 | ✅ Done |
| Create PR checklist for connection management | John | 2024-01-22 | P0 | ✅ Done |
| Extend load tests to 30 minutes minimum | QA Team | 2024-01-25 | P1 | 🔄 In Progress |
| Implement canary deployment (10% → 100%) | DevOps | 2024-02-01 | P1 | 📋 Planned |
| Add connection leak detection to tests | Jane | 2024-01-27 | P1 | 🔄 In Progress |
| Review all DB connection usage patterns | John | 2024-02-05 | P2 | 📋 Planned |
| Improve alert routing (faster escalation) | DevOps | 2024-02-10 | P2 | 📋 Planned |
## Lessons Learned
1. **Code review checklists work:** Need specific items for common issues
2. **Load tests need realistic duration:** 5min insufficient for leaks
3. **Gradual rollouts catch issues:** 10% canary would have limited impact
4. **Monitoring gaps are dangerous:** Add metrics before you need them
5. **Runbooks save time:** Clear procedures enabled fast response
## Related Incidents
- [2023-11-20] Database CPU spike (similar connection pool issue)
- [2023-08-15] Memory leak in cache layer
## Prevention
To prevent similar incidents:
1. ✅ Add connection management to code review checklist
2. ✅ Monitor connection pool utilization
3. ✅ Extend load test duration
4. ✅ Implement canary deployments
5. ✅ Add automated connection leak detection
## Appendix
### Monitoring Graphs
[Insert graphs of connection pool, error rates, latency during incident]
### Communication Log
[Insert status page updates and customer communication]
### Code Fix
PR #1235: Fix connection leak in user profile endpoint
\`\`\`typescript
const client = await pool.connect();
try {
const user = await client.query('SELECT \* FROM users WHERE id = $1', [id]);
return user;
} finally {
client.release(); // ✅ Always release
}
\`\`\`
```
## Postmortem Best Practices
```markdown
# Blameless Postmortem Guidelines
## Do ✅
- Focus on systems and processes, not people
- Use timeline with exact timestamps
- Identify contributing factors, not just root cause
- Create actionable items with owners and dates
- Document what went well (positive reinforcement)
- Share widely for organizational learning
## Don't ❌
- Blame individuals or teams
- Hide or minimize the incident
- Skip the postmortem (even for small incidents)
- Create action items without owners
- Forget to follow up on action items
- Make it a blame session
## Template Sections
1. **Summary** (2-3 sentences)
2. **Impact** (numbers: users, revenue, duration)
3. **Timeline** (chronological events)
4. **Root Cause** (technical explanation)
5. **Contributing Factors** (broader context)
6. **What Went Well** (positive reinforcement)
7. **What Went Wrong** (improvement areas)
8. **Action Items** (concrete, owned, dated)
9. **Lessons Learned** (key takeaways)
```
## Output Checklist
- [ ] Timeline created
- [ ] Root cause identified
- [ ] Contributing factors documented
- [ ] Action items with owners
- [ ] Lessons learned captured
- [ ] Postmortem meeting held
- [ ] Document shared widely
- [ ] Follow-up scheduled
ENDFILE
© patricio0312rev · MIT · patricio0312rev/skills