🧩 Claude Skill Designer — Build Progressive-Disclosure Skills That Actually Ship

Skill Blueprint: Incident Post-Mortem Skill

A Claude Skill blueprint is the complete architectural plan — SKILL.md front-matter, progressive-disclosure structure, reference files, scripts, and invocation test plan — producing a production-ready skill that ships in hours rather than days. Based on analysis of official Anthropic skills (SDK examples, document-creation skills) and 80+ community skills, the #1 failure mode is invocation mismatch (Claude doesn't reach for the skill when it should), which comes from vague invocation descriptions. Your use case — incident post-mortems for an 80-engineer B2B SaaS — is a classic WORKFLOW-ORCHESTRATOR skill with clear trigger phrases, existing tooling, and measurable success criteria. This blueprint produces the complete skill architecture with invocation design tested against 12 trigger scenarios.

Pattern Selection

Pattern: Workflow-Orchestrator (with tool-wrapper elements).

Why this pattern:

• Multi-step process (gather → timeline → root cause → action items → publish)
• Decision points (is this a P0? is root cause technical vs. process? who owns action items?)
• Checkpointable state (can pause mid-workflow, resume next day)
• Wraps existing tools (Google Docs template, Notion API, Slack webhook)

Not tool-wrapper only: your use case has meaningful reasoning steps between tool calls.

Not knowledge-reference: domain knowledge is small; process is large.

Not agent-sub-behavior: not modifying how Claude operates generally — specific workflow.

Is This Actually A Skill?

Honest check:

Could this be a prompt? No. Too multi-step, needs persistent state across interactions, and invokes tools.

Could this be a tool? Partially — pieces of it (generate_post_mortem_doc, create_notion_page) should be tools. But the orchestration layer (asking the right questions, guiding the engineer through the process, adapting to their answers) needs reasoning — that's skill territory.

Could this be an agent instruction? No. Too specialized to put in every system prompt. Skill is correct pattern.

Verdict: Yes, this is a skill. Specifically, workflow-orchestrator that wraps your existing tools.

SKILL.md Structure

---
name: incident-post-mortem
description: >
  Guides engineers through conducting a blameless post-mortem after an
  incident. Use this when a user mentions writing a post-mortem, RCA,
  incident documentation, or describes a recent production incident they
  need to document. Walks through timeline construction, root cause
  analysis, action items, and publishing to the team's Google Doc +
  Notion + Slack channels using the standard internal format.
version: 1.0.0
triggers:
  - "write a post-mortem"
  - "incident documentation"
  - "RCA" / "root cause analysis"
  - "blameless post-mortem"
  - "our service went down"
  - "we had an incident"
  - "document yesterday's outage"
works_in:
  - Claude Code
  - Claude.ai web app
requires:
  - Internal Notion API access token (env: NOTION_TOKEN)
  - Google Docs template ID: [template_id]
  - Slack webhook for #engineering
---

# Incident Post-Mortem Skill

## When to use this skill

Trigger phrases (non-exhaustive):
- "help me write a post-mortem"
- "we had an incident — need to document"
- "our [service] went down yesterday, now what"
- "I need to do an RCA"
- "blameless post-mortem for [date/event]"

If user mentions ANY of: post-mortem, RCA, incident retrospective, or describes a recent production incident and the need to document it — use this skill.

Do NOT use this skill for: active incident response (use incident-response skill instead), general engineering retrospectives (different template), or minor bugs that don't warrant post-mortem.

## The 5-phase workflow

This skill guides the engineer through 5 phases. Skill maintains state across phases so engineer can pause + resume.

### Phase 1: Incident scope (5 min)
- What happened (1-2 sentences)
- When (UTC timestamps start + end)
- Severity (P0 / P1 / P2 — see references/SEVERITY.md)
- Who was on-call + who was paged

### Phase 2: Timeline (15-30 min)
- Chronological events from detection to resolution
- Focus on detection lag, decision points, recovery steps
- Claude asks follow-up questions for gaps
- See references/TIMELINE.md for format

### Phase 3: Root cause analysis (20-40 min)
- Use 5-whys methodology (see references/ROOT_CAUSE.md)
- Distinguish technical root cause vs. process root cause
- Identify blast radius + why detection was delayed (if it was)

### Phase 4: Action items (15-20 min)
- Preventive items (stop this class of incident)
- Detection items (catch earlier next time)
- Response items (respond faster)
- Each with owner + priority + target date
- See references/ACTION_ITEMS.md for format

### Phase 5: Publish (5 min)
- Generate Google Doc from template (scripts/generate_doc.py)
- Create Notion page for action items (scripts/create_notion.py)
- Post summary to Slack #engineering (scripts/post_slack.py)

## Skill state

The skill maintains state in a local file `.post-mortem-state.json` that tracks current phase + collected data + decisions. Engineer can pause at any phase and resume by saying 'continue the post-mortem.'

## Constraints

- All incident details stay local (no external APIs except Notion/Slack which are internal routing)
- Engineer controls what goes into the doc — skill guides, doesn't decide
- Blameless framing enforced: see references/BLAMELESS.md for language patterns

## Common patterns

- If engineer is frustrated or tired, acknowledge and reduce scope
- If incident was caused by recent change, focus root cause on process (how did change get through), not person
- If similar incident recurring, reference previous post-mortem + highlight repeat pattern

SKILL.md size: ~120 lines. Appropriate for workflow-orchestrator complexity.

Invocation Design

The description field is the key trigger. It must tell Claude WHEN to use this skill, not WHAT the skill does.

Good description (used above):

'Guides engineers through conducting a blameless post-mortem after an incident. Use this when a user mentions writing a post-mortem, RCA, incident documentation, or describes a recent production incident they need to document.'

Why this works:

• Starts with action verb ('Guides')
• Names the domain ('blameless post-mortem')
• Critical: 'Use this when a user mentions...' — gives Claude explicit trigger logic
• Lists 3-4 specific trigger scenarios
• Scoped ('after an incident they need to document') prevents over-triggering

Bad description (avoid):

'A skill for incident management and retrospectives.' — Too vague. Doesn't tell Claude when to trigger.

Progressive Disclosure Architecture

What lives where:

SKILL.md (entry point, ~120 lines):

• The 5-phase workflow overview
• When to use / when NOT to use
• State management mention
• High-level constraints
• Links to references for depth

references/ (loaded on-demand):

• SEVERITY.md — severity rubric (P0/P1/P2 criteria)
• TIMELINE.md — timeline format + examples
• ROOT_CAUSE.md — 5-whys methodology + templates
• ACTION_ITEMS.md — action-item format + priority guidance
• BLAMELESS.md — blameless language patterns + antipatterns
• EXAMPLES.md — 2-3 anonymized past post-mortems for reference

scripts/ (called by skill):

• generate_doc.py — produces Google Doc from template
• create_notion.py — creates Notion action-items page
• post_slack.py — posts summary to Slack
• save_state.py — saves phase state
• load_state.py — loads phase state for resume

Reference Files Organization

references/SEVERITY.md (~50 lines)

# Incident Severity Rubric

## P0 (Critical)
- User-facing outage affecting >10% of users
- Data loss or corruption
- Security breach
- Revenue-impacting billing failure

## P1 (High)
- User-facing degradation
- Critical feature broken
- <10% users affected

## P2 (Medium)
- Minor feature broken
- Internal-only issue
- Performance degradation without outage

## What NOT to post-mortem
- P3 issues (minor bugs) — use regular bug process
- User error / third-party outages (unless we failed to handle gracefully)

references/TIMELINE.md (~80 lines)

Timeline format, UTC timestamp convention, detection-vs-impact timing, examples.

references/ROOT_CAUSE.md (~100 lines)

5-whys methodology, technical-vs-process root cause distinction, contributing factors template.

references/ACTION_ITEMS.md (~60 lines)

Owner assignment, priority rubric (P0-actions within 30 days, P1 within 90), target date format.

references/BLAMELESS.md (~80 lines)

Blameless language: 'the system allowed X' (not 'Bob did X'). Examples of blameful vs. blameless phrasing.

references/EXAMPLES.md (~150 lines)

2-3 anonymized past post-mortems. Powerful for Claude to pattern-match quality.

Total references: ~500 lines across 6 files. Progressive disclosure intact.

Scripts Organization

scripts/generate_doc.py

#!/usr/bin/env python3
"""Generate post-mortem Google Doc from template."""
import sys, json, argparse
from google_docs_api import create_doc_from_template

TEMPLATE_ID = "[your_template_id]"

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--state-file', required=True)
    args = parser.parse_args()
    
    state = json.load(open(args.state_file))
    doc_url = create_doc_from_template(
        template_id=TEMPLATE_ID,
        variables={
            'incident_title': state['title'],
            'incident_date': state['date'],
            'severity': state['severity'],
            'timeline_items': state['timeline'],
            'root_cause': state['root_cause'],
            'action_items': state['action_items'],
        }
    )
    print(json.dumps({'doc_url': doc_url, 'status': 'success'}))

if __name__ == '__main__':
    main()

Script interface pattern:

• Input: JSON state file path (via --state-file)
• Output: JSON to stdout with clear success/error format
• Errors: raise with clear message, non-zero exit

Repeat pattern for create_notion.py and post_slack.py.

Invocation Test Plan

Before shipping, test with these 12 prompts. Skill should trigger on prompts 1-9, NOT on 10-12:

Should trigger:

1. 'I need help writing a post-mortem for our auth service going down yesterday'

2. 'Can you walk me through an RCA for this morning's deployment issue'

3. 'We had a big incident last night — need to document it'

4. 'Help me do a blameless post-mortem'

5. 'Our payment system was down for 2 hours, what do I do now'

6. 'I need to write an incident retrospective'

7. 'Documentation for yesterday's outage'

8. 'Post-mortem time — customer-facing outage 10am-11:30am'

9. 'Resume my post-mortem from yesterday' (tests resume flow)

Should NOT trigger:

10. 'How do I prevent incidents?' (general advice question, not documentation)

11. 'Our service is down right now' (active incident — different skill)

12. 'Write me a story about an incident' (creative, not real)

Test procedure:

• In Claude Code or Claude app with skill installed
• Use each prompt
• Verify: did skill invoke? (should for 1-9, should not for 10-12)
• If mismatch, adjust description in SKILL.md
• Re-run test

Common Failure Modes + Fixes

Failure 1: Skill triggers on 'prevent incidents' type questions.

• Fix: add to description: 'NOT for general incident prevention advice — only for documenting a specific recent incident'

Failure 2: Skill doesn't trigger on 'our service went down' without 'post-mortem' word.

• Fix: add more trigger phrases including recovery-mode language

Failure 3: Engineer pauses mid-workflow, loses state.

• Fix: state file must be robust. Script save_state.py should save every phase. load_state.py should handle missing/malformed files.

Failure 4: Generated Google Doc is malformed.

• Fix: template variables must be exhaustively tested. Handle missing data gracefully.

Failure 5: Notion page created but action items missing owners.

• Fix: Phase 4 must require owners before allowing progression.

Failure 6: Skill feels verbose — too many questions.

• Fix: skill should adapt. If engineer provides rich info upfront, skip questions. If terse, ask more.

Shipping + Versioning

Front-matter versioning:

version: 1.0.0

Distribution:

• Internal: push to your Anthropic workspace skills dir. Engineers opt-in.
• Versioning: semver. 1.0.0 → 1.1.0 for non-breaking enhancements. 2.0.0 for breaking changes (e.g., new phases added, state format change).
• Release notes in CHANGELOG.md at skill root.

Open-source path (future):

• Sanitize: remove internal URLs, Notion template IDs, Slack webhook.
• Replace with env-var configuration so users set their own.
• Add EXAMPLES.md with generic examples.
• License: Apache 2.0 or MIT.

Key Takeaways

• Pattern: Workflow-orchestrator with tool-wrapper elements. 5-phase workflow with state. Not a prompt, not a tool — skill is correct.
• Invocation description is 80% of success. Start with verb, name domain, use 'Use this when user mentions...' + specific trigger scenarios. Test with 12 prompts before shipping.
• Progressive disclosure: SKILL.md (120 lines) + 6 reference files + 5 scripts. Not everything in SKILL.md.
• State file + resume flow is essential for multi-session use. Don't force engineer to complete in one sitting.
• Test invocation against 12 scenarios (9 should-trigger, 3 should-NOT-trigger). Fix description before building more.