From 9a7b602deb2bf9090f26189dc4884f66be697285 Mon Sep 17 00:00:00 2001 From: debidong <1953531014@qq.com> Date: Mon, 20 Apr 2026 18:15:42 +0800 Subject: [PATCH] feat: add flashduty-statuspage agent skill Adds the tenth agent skill, covering the statuspage command family (4 existing operations + 4 migration subcommands) for AI coding agents. - skills/flashduty-statuspage/SKILL.md: inline command docs for list/changes/create-incident/create-timeline plus migrate structure/email-subscribers/status/cancel. Three workflows: publish and manage an incident, full Atlassian-to-Flashduty migration (structure then subscribers), cancel a runaway migration. Description narrowly scoped to page management + migration to avoid triggering overlap with flashduty-shared. - README.md / README_zh.md: bump "9 agent skills" to "10", add row. Structural pattern matches flashduty-channel and flashduty-insight (inline command sections, no references/ subdirectory). Flag tables and component-status enumerations verified against live CLI help. --- README.md | 3 +- README_zh.md | 3 +- skills/flashduty-statuspage/SKILL.md | 264 +++++++++++++++++++++++++++ 3 files changed, 268 insertions(+), 2 deletions(-) create mode 100644 skills/flashduty-statuspage/SKILL.md diff --git a/README.md b/README.md index f0762d6..d0f3b18 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Download the latest release for your platform from [GitHub Releases](https://git ## Agent Skills -Flashduty CLI ships with 9 agent skills that teach AI coding agents how to operate Flashduty from your terminal. Compatible with 41+ agents including Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, and more. +Flashduty CLI ships with 10 agent skills that teach AI coding agents how to operate Flashduty from your terminal. Compatible with 41+ agents including Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, and more. ```bash npx skills add flashcatcloud/flashduty-cli -y -g @@ -60,6 +60,7 @@ The installer auto-detects which agents you have and installs skills to all of t | `flashduty-change` | Change event tracking and deployment frequency trends | | `flashduty-oncall` | On-call schedule queries: who is on call, shift details | | `flashduty-channel` | Channel and escalation rule lookups | +| `flashduty-statuspage` | Status page management and Atlassian → Flashduty migration | | `flashduty-insight` | Analytics: MTTA/MTTR, noise reduction, notification trends | | `flashduty-admin` | Team/member lookups and audit log search | | `flashduty-template` | Notification template validation and preview | diff --git a/README_zh.md b/README_zh.md index 69cb331..828a925 100644 --- a/README_zh.md +++ b/README_zh.md @@ -42,7 +42,7 @@ go install github.com/flashcatcloud/flashduty-cli/cmd/flashduty@latest ## Agent Skills（AI 代理技能） -Flashduty CLI 内置 9 个代理技能，让 AI 编程代理能够通过 CLI 操作 Flashduty 平台。兼容 41+ 编程代理，包括 Claude Code、Cursor、GitHub Copilot、Codex、Gemini CLI、Windsurf 等。 +Flashduty CLI 内置 10 个代理技能，让 AI 编程代理能够通过 CLI 操作 Flashduty 平台。兼容 41+ 编程代理，包括 Claude Code、Cursor、GitHub Copilot、Codex、Gemini CLI、Windsurf 等。 ```bash npx skills add flashcatcloud/flashduty-cli -y -g @@ -60,6 +60,7 @@ npx skills add flashcatcloud/flashduty-cli -y -g | `flashduty-change` | 变更事件追踪与部署频率趋势 | | `flashduty-oncall` | 值班查询：当前值班人、排班详情 | | `flashduty-channel` | 协作空间与升级规则查询 | +| `flashduty-statuspage` | 状态页管理以及从 Atlassian 迁移到 Flashduty | | `flashduty-insight` | 分析：MTTA/MTTR、降噪率、通知趋势 | | `flashduty-admin` | 团队/成员查询与审计日志搜索 | | `flashduty-template` | 通知模板验证与预览 | diff --git a/skills/flashduty-statuspage/SKILL.md b/skills/flashduty-statuspage/SKILL.md new file mode 100644 index 0000000..2c16e8f --- /dev/null +++ b/skills/flashduty-statuspage/SKILL.md @@ -0,0 +1,264 @@ +--- +name: flashduty-statuspage +version: 1.0.0 +description: "Flashduty status page management and one-time migration from external providers. Commands: statuspage list, changes, create-incident, create-timeline; statuspage migrate structure, email-subscribers, status, cancel. Use when publishing an incident or maintenance to a public status page, posting a timeline update, importing an existing Atlassian Statuspage (structure, history, or email subscribers) into Flashduty, or polling a migration job. Does not cover incident response workflows inside Flashduty — see flashduty-incident for that." +metadata: + requires: + bins: ["flashduty"] + cliHelp: "flashduty statuspage --help" +--- + +# flashduty-statuspage + +**CRITICAL** -- Before using this skill, read [`../flashduty-shared/SKILL.md`](../flashduty-shared/SKILL.md) for authentication, the 3-layer noise reduction model, global flags, and safety rules. + +## Overview + +Status pages are the public-facing communication layer: they let customers and internal stakeholders see current service health, ongoing incidents, and scheduled maintenance. This skill covers two distinct use cases: + +1. **Day-to-day operations** on existing Flashduty status pages: listing pages, posting incidents and maintenance windows, updating timelines. +2. **One-time migration** from an external provider (currently Atlassian Statuspage) into Flashduty: structure + history in one job, email subscribers in a separate job to control when verification emails go out. + +Migration jobs are **asynchronous**. Start a job, poll its status, cancel if needed. The CLI never blocks waiting on a long-running migration. + +## Quick Decision + +| User wants to... | Command | +|---|---| +| See existing status pages | `statuspage list` | +| See open incidents or maintenance on a page | `statuspage changes --page-id --type incident` | +| Publish a new incident | `statuspage create-incident --page-id --title "..."` | +| Update an ongoing incident | `statuspage create-timeline --page-id --change --message "..."` | +| Migrate a page from Atlassian (contents first) | `statuspage migrate structure --from atlassian ...` | +| Migrate subscribers (after structure) | `statuspage migrate email-subscribers --from atlassian ...` | +| Check migration progress | `statuspage migrate status --job-id ` | +| Stop a runaway migration | `statuspage migrate cancel --job-id ` | + +## Commands + +### statuspage list + +List all status pages visible to the account. + +```bash +flashduty statuspage list [flags] +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--id` | string | Filter by page IDs (comma-separated) | + +Output columns: ID, NAME, SLUG, STATUS, COMPONENTS. + +Use this to look up page IDs for the other commands in this skill. + +### statuspage changes + +List active incidents or maintenance windows on a page. + +```bash +flashduty statuspage changes --page-id --type +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--page-id` | int | Page ID (**required**) | +| `--type` | string | `incident` or `maintenance` (**required**) | + +Output columns: ID, TITLE, TYPE, STATUS, CREATED, UPDATED. + +"Active" means not yet resolved / not yet completed. Returns both incident and maintenance changes depending on `--type`. + +### statuspage create-incident + +Publish a new incident on a status page. The incident appears to subscribers and on the public page immediately. + +```bash +flashduty statuspage create-incident --page-id --title [flags] +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--page-id` | int | Page ID (**required**) | +| `--title` | string | Incident title, max 255 chars (**required**) | +| `--message` | string | Initial update message | +| `--components` | string | `id1:status,id2:status` — statuses: `operational`, `degraded`, `partial_outage`, `full_outage` | +| `--notify` | bool | Notify page subscribers (default: false) | + +Use `--notify` deliberately — it sends email + push to every subscriber on the page. + +### statuspage create-timeline + +Add a timeline update to an existing incident or maintenance. Use this to move a change through its lifecycle (`investigating` → `identified` → `monitoring` → `resolved`). + +```bash +flashduty statuspage create-timeline --page-id <id> --change <id> --message <msg> [flags] +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--page-id` | int | Page ID (**required**) | +| `--change` | int | Change ID (**required**) — get it from `statuspage changes` | +| `--message` | string | Timeline message (**required**) | +| `--status` | string | Incident: `investigating`, `identified`, `monitoring`, `resolved`; maintenance: `scheduled`, `ongoing`, `completed` | + +The `--status` transition determines when a change is considered resolved / completed and stops appearing in `statuspage changes`. + +### statuspage migrate structure + +Start an asynchronous migration of status page **structure and history** from an external provider into a new Flashduty status page. Components, sections, past incidents, past maintenance windows, and notification templates are imported. **No emails are sent to subscribers.** + +```bash +flashduty statuspage migrate structure --from atlassian --source-page-id <id> --api-key <key> +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--from` | string | Source provider, currently only `atlassian` (**required**) | +| `--source-page-id` | string | Page ID in the source provider (**required**) | +| `--api-key` | string | Source provider API key (**required**) | + +Returns a job ID plus the command to poll its status. Human output shows the new Flashduty `target_page_id` once the job reaches the `completed` phase — capture that for the subscriber migration. + +### statuspage migrate email-subscribers + +Start a **separate** migration of email subscribers from the external provider into an existing Flashduty status page. Split from `migrate structure` so that operators can verify imported content before waking up the subscriber list. + +```bash +flashduty statuspage migrate email-subscribers --from atlassian --source-page-id <id> --target-page-id <id> --api-key <key> +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--from` | string | Source provider, currently only `atlassian` (**required**) | +| `--source-page-id` | string | Page ID in the source provider (**required**) | +| `--target-page-id` | int | Flashduty page ID from `migrate structure` (**required**) | +| `--api-key` | string | Source provider API key (**required**) | + +### statuspage migrate status + +Poll the progress of an async migration job. + +```bash +flashduty statuspage migrate status --job-id <id> +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--job-id` | string | Migration job ID (**required**) | + +Human output prints the current phase, status, progress counters (components, sections, incidents, maintenances, subscribers, templates), and any accumulated warnings or a fatal error. Poll until `Status: completed`, `failed`, or `cancelled`. + +### statuspage migrate cancel + +Request cancellation of an in-flight migration job. Best-effort: jobs in their final phase may still complete. + +```bash +flashduty statuspage migrate cancel --job-id <id> +``` + +| Flag | Type | Description | +|------|------|-------------| +| `--job-id` | string | Migration job ID (**required**) | + +Returns a confirmation and the command to poll the final state. + +## Workflows + +### Workflow 1: Publish and Manage an Incident + +Post a new incident, move it through investigation, resolve it. + +```bash +# 1. Find the page ID +flashduty statuspage list + +# 2. Create the incident (no notifications yet) +flashduty statuspage create-incident \ + --page-id 42 \ + --title "Database latency elevated" \ + --message "We're investigating reports of slow database queries" \ + --components "comp_1:degraded" + +# 3. See the change ID for follow-up updates +flashduty statuspage changes --page-id 42 --type incident + +# 4. Post updates as the incident progresses +flashduty statuspage create-timeline \ + --page-id 42 --change 101 \ + --status identified \ + --message "Root cause: a runaway query. Rolling back now." + +flashduty statuspage create-timeline \ + --page-id 42 --change 101 \ + --status monitoring \ + --message "Rollback complete. Monitoring for recurrence." + +# 5. Resolve +flashduty statuspage create-timeline \ + --page-id 42 --change 101 \ + --status resolved \ + --message "Latency back to baseline. Closing." +``` + +### Workflow 2: Full Atlassian → Flashduty Migration + +Import structure first, verify, then import subscribers. + +```bash +# 1. Start the structure + history migration +flashduty statuspage migrate structure \ + --from atlassian \ + --source-page-id page_atl_123 \ + --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" +# → captures Job ID: str_abc + +# 2. Poll until completed +flashduty statuspage migrate status --job-id str_abc +# Repeat until Status: completed. +# Capture Target page ID from the completed job's output. + +# 3. Sanity-check the imported page +flashduty statuspage list --id <new_page_id> +flashduty statuspage changes --page-id <new_page_id> --type incident + +# 4. ONLY AFTER VERIFYING: start subscriber migration +flashduty statuspage migrate email-subscribers \ + --from atlassian \ + --source-page-id page_atl_123 \ + --target-page-id <new_page_id> \ + --api-key "$ATLASSIAN_STATUSPAGE_API_KEY" +# → captures Job ID: sub_xyz + +# 5. Poll until completed +flashduty statuspage migrate status --job-id sub_xyz +``` + +### Workflow 3: Stop a Runaway Migration + +```bash +# Saw unexpected warnings or want to retry with a different config +flashduty statuspage migrate cancel --job-id str_abc + +# Confirm it reached a terminal state +flashduty statuspage migrate status --job-id str_abc +# Status should become cancelled. +``` + +## Key Concepts + +- **Page ID** (int) is the Flashduty status page primary key. **Change ID** (int) is the ID of an incident/maintenance within a page. Don't confuse them. +- **Migration is async.** `migrate structure` and `migrate email-subscribers` return immediately with a job ID; the actual work happens on the backend. +- **Two migration jobs, not one.** Structure + history run separately from subscribers. This is deliberate — subscriber import triggers verification emails, so operators verify content first. +- **Migration phases** for the structure job progress in order: `components` → `sections` → `history` (incidents + maintenances) → `templates`. The subscribers job has a single `subscribers` phase. +- **Terminal statuses:** `completed`, `failed`, `cancelled`. Stop polling once any of these appears. +- **`--notify` is subscriber-visible.** In `create-incident`, omit or set `--notify=false` for silent incidents; set `--notify` when you want an announcement. +- **Component statuses vary by change type.** Incident statuses: `operational`, `degraded`, `partial_outage`, `full_outage`. Maintenance statuses: `operational`, `under_maintenance`. +- **Source provider support** is currently Atlassian Statuspage only. Other providers will require SDK + CLI updates. + +## Cross-References + +- **Prerequisites:** `flashduty-shared` — authentication, global flags (`--json`, `--no-trunc`), and safety rules. +- **Related skills:** + - `flashduty-incident` — internal Flashduty incident response (distinct from public status page incidents). + - `flashduty-channel` — channels are how alerts are routed internally; status pages publish to customers. They can be wired together but are independent concepts.