// Write planned maintenance announcements for each phase (scheduled, in-progress, completed). Use when the user mentions "maintenance announcement," "scheduled maintenance," "maintenance window," "planned downtime," "maintenance notification," or needs to communicate upcoming planned work to users.
| name | maintenance |
| version | 0.1.0 |
| description | Write planned maintenance announcements for each phase (scheduled, in-progress, completed). Use when the user mentions "maintenance announcement," "scheduled maintenance," "maintenance window," "planned downtime," "maintenance notification," or needs to communicate upcoming planned work to users. |
Write maintenance announcements that give users everything they need to prepare, stay informed, and confirm completion.
Read .agents/status-page-context.md if it exists. Use it for:
If the file doesn't exist, suggest running the status-page-context skill first. Proceed without it if the user wants to skip.
Ask the user which phase if not obvious:
| Phase | When | Purpose |
|---|---|---|
| Scheduled | Before the maintenance | Give users time to prepare |
| In-progress | Maintenance has started | Confirm it's happening, set expectations |
| Completed | Maintenance is done | Confirm everything is back to normal |
| Cancelled | Maintenance won't happen | Inform users the planned work is called off |
| Extended | Maintenance is running longer than planned | Update the expected end time |
For scheduled announcements:
For in-progress updates:
For completed announcements:
Follow these principles:
The first sentence should tell users whether they need to take action.
Do: "Save any uncommitted work in Codespaces before Tuesday 16:00 UTC — we're performing scheduled maintenance that may interrupt active sessions." Don't: "We will be performing scheduled maintenance on our infrastructure."
"May experience issues" is not helpful. Tell users exactly what will and won't work.
Do: "During this window, new deployments will be paused. Existing deployments and live traffic will not be affected." Don't: "Some services may be temporarily unavailable."
Include start time, end time, and expected duration. If the maintenance rolls out regionally, explain the order.
Do: "Maintenance window: Tuesday March 31, 02:00–04:00 UTC (approximately 2 hours). European regions will be maintained first, followed by US regions." Don't: "Maintenance will happen Tuesday night."
Users need time to prepare. The lead time should match the severity of the impact:
| Impact | Minimum lead time |
|---|---|
| Full downtime | 72 hours (3 days) |
| Degraded performance | 48 hours (2 days) |
| Minimal/no user impact | 24 hours |
Most companies post "Scheduled maintenance is currently in progress" and "The scheduled maintenance has been completed" — identical boilerplate every time. Do better.
In-progress — do: "Maintenance is underway. Database migration is running as expected. We're approximately 30 minutes in, targeting completion by 04:00 UTC." In-progress — don't: "Scheduled maintenance is currently in progress."
Completed — do: "Maintenance completed at 03:45 UTC, 15 minutes ahead of schedule. All services are operational. No action needed from your side." Completed — don't: "The scheduled maintenance has been completed."
If maintenance takes longer than planned, post an update before the original end time.
Do: "Update: maintenance is taking longer than expected. New estimated completion: 05:30 UTC (originally 04:00 UTC). The delay is due to [reason]. [Impact during the extension]." Don't: (silence past the original end time)
**Scheduled Maintenance: [Component]**
[Action users should take, if any, before the maintenance starts.]
**When:** [Day, Date], [start time] – [end time] UTC (approximately [duration])
**What's affected:** [Component(s)] — [specific user impact]
**What's NOT affected:** [Unaffected services]
**What to expect:** [Describe exactly what users will experience]
[Preparation instructions or workarounds, if applicable.]
We'll post an update when maintenance begins and when it's complete.
**Maintenance In Progress: [Component]**
Scheduled maintenance on [Component] started at [start time] UTC.
[Current status: what's happening right now, progress if known.]
Expected completion: [end time] UTC.
[Any unexpected impact or changes from the plan. If everything is on track: "Everything is proceeding as planned."]
**Maintenance Completed: [Component]**
Scheduled maintenance on [Component] was completed at [actual end time] UTC.
[Did it finish on time, early, or late?]
All services are operating normally.
[Any follow-up actions users need to take, e.g., "You may need to refresh your dashboard" or "No action needed."]
[If there were unexpected issues during maintenance, briefly note them and link to an incident if one was opened.]
**Maintenance Extended: [Component]**
Scheduled maintenance on [Component] is taking longer than expected.
**Original end time:** [time] UTC
**New estimated end time:** [time] UTC
**Reason:** [Brief explanation]
[Updated user impact during the extension.]
We'll post another update at [time] UTC or when maintenance is complete.
**Maintenance Cancelled: [Component]**
The scheduled maintenance for [Component] on [date, time window] UTC has been cancelled.
**Reason:** [Brief explanation]
No action is needed. All services continue to operate normally.
[If rescheduled: "This maintenance will be rescheduled to [new date]. We'll send a new announcement with details."]
| Anti-pattern | Why it's bad | Instead |
|---|---|---|
| "We will be performing scheduled maintenance" as the opener | Buries the user action and impact | Lead with what users need to do or what they'll experience |
| Same boilerplate for every maintenance | Users stop reading maintenance notices | Include specific impact and preparation steps |
| "Some services may be temporarily unavailable" | Vague — users don't know if they're affected | Name the specific components and describe the impact |
| No update after the original end time passes | Users don't know if it's still going or if you forgot | Always post an extension notice before the end time |
| "The scheduled maintenance has been completed" (with no detail) | Missed opportunity to confirm normalcy and note any issues | State actual end time, whether everything is normal, and any user follow-up |
| Announcing maintenance 1 hour before downtime | Users can't prepare | Follow the lead time guidelines based on impact severity |
| "Thank you for your patience" | Empty filler | Replace with useful info: "No action needed" or "You may need to re-authenticate" |
status-page-context — Set up the context document this skill reads (components, maintenance windows, tone)incident-communication — Write updates for unplanned incidents (not scheduled maintenance)status-report — Write periodic health reportspostmortem — Write postmortems (only needed if maintenance caused an unplanned incident)Design, scaffold, and contribute a community theme to openstatus (the open-source status page). Use whenever the user wants to create a new theme, customize status-page colors, build a palette for their brand, fork and contribute to openstatus's `@openstatus/theme-store`, or mentions OKLCH colors, CSS variables, or themes.openstatus.dev. Also use when the user pastes a theme export from the live explorer and wants it wired into the repo.
Build a custom status page UI using OpenStatus components or SDK. Use when someone wants to "create a status page," "build a status page," "integrate OpenStatus UI," "embed a status widget," "add status page components," or render monitors, incidents, and maintenance in their own app.
Write clear, empathetic incident status updates for any phase of an incident (investigating, identified, monitoring, resolved). Use when the user mentions "incident update," "status update," "outage communication," "write an incident," "investigating update," "post-incident update," or needs to communicate a service disruption to users.
Write blameless postmortems after incidents with timeline, root cause analysis, impact assessment, and action items. Use when the user mentions "postmortem," "post-mortem," "incident review," "root cause analysis," "RCA," "incident retrospective," "what went wrong," or wants to document lessons from a resolved incident.
Create or update the status page context document that all other status page skills reference. Use when setting up status page skills for the first time, or when the user mentions "status page context," "configure status page," "set up incident tone," or wants to define their service components, SLAs, or communication style.
Write periodic status reports summarizing overall system health, uptime, incidents, and maintenance. Use when the user mentions "status report," "health report," "uptime report," "weekly status," "monthly report," "system health summary," "reliability report," or wants to publish a regular update on how their services are performing.