// Build and modify Grafana dashboards following the user's established style conventions. Use when creating new dashboards, adding panels, modifying existing dashboards, or reviewing dashboard JSON for consistency. Requires the Grafana MCP to be enabled.
| name | grafana-dashboard |
| description | Build and modify Grafana dashboards following the user's established style conventions. Use when creating new dashboards, adding panels, modifying existing dashboards, or reviewing dashboard JSON for consistency. Requires the Grafana MCP to be enabled. |
Activate this skill when the user asks to:
Before performing any Grafana operation, verify the Grafana MCP is available by attempting a lightweight call (e.g. search_dashboards).
If the Grafana MCP is not available or not responding, stop and tell the user:
The Grafana MCP server is not enabled. To use this skill you need to configure it.
- Install
mcp-grafana— seemcp/grafana.mdin this repo for instructions.- Add the server config to
.kiro/settings/mcp.json(or your user-level config).- Reconnect MCP servers from the Kiro MCP panel.
Once the Grafana MCP is connected, try again.
Do not attempt to generate raw JSON without the MCP — the skill relies on live queries to discover metrics, labels, and datasource UIDs.
The following conventions are extracted from the user's existing dashboards. All new dashboards and panels MUST follow these rules.
http, performance, tracking, business, sdk, grpc, kafka). Tags should cover: the domain, the component, and the dashboard purpose.Ads Delivery Platform -> tag ads-delivery-platform; application tracking-api -> tag tracking-api.description field — one sentence summarizing what it monitors and for which service.now-6h to now for business/performance dashboards; now-1h to now for operational/real-time dashboards.refresh: "30s" only for operational dashboards (queues, pipelines). Omit for analytical dashboards.cluster variable:
queryM2qX4-R4k)label_values(<a_relevant_metric>{...}, cluster)includeAll: true, allValue: ".*"app variable when the dashboard covers multiple apps:
label_values(<metric>{kubernetes_namespace="<ns>"}, app)includeAll: falsemethod_filter, brand, pod) as custom or query types when needed.label_values(...) syntax, refresh on dashboard load (refresh: 1).The dashboard follows a top-down drill-down pattern:
stat panels showing KPIs at a glance.Row IDs use round numbers with spacing for future inserts: 100, 200, 300, 400, 500, 600.
Grafana uses a 24-column grid. Every horizontal line of panels MUST sum to exactly 24 columns. Never leave empty space at the end of a row.
The core principle: plan the full row first, then assign widths.
Handling orphan panels (the most common mistake):
An "orphan" is a panel that ends up alone (or with too few siblings) on a row, leaving large empty space. This looks bad:
BAD: [■■■][ ] ← 1 stat alone on a row (w:3, 21 cols wasted)
BAD: [■■■■■■■■■■■■][ ] ← 1 timeseries alone (w:12, 12 cols wasted)
Fix orphan panels using one of these strategies (in order of preference):
w:24. A single timeseries → w:24. Two stats → w:12 each. Three stats → w:8 each.[stat w:4][timeseries w:10][timeseries w:10] = 24.[stat w:4][timeseries w:20] = 24, or [stat w:3][timeseries w:21] = 24.Never place a panel that occupies less than the full 24 columns on a row by itself.
Stat panel row sizing — pick the width that fills the row:
| Stat count per row | Width each | Layout | Total |
|---|---|---|---|
| 8 | w: 3 | 3×8 | 24 ✓ |
| 6 | w: 4 | 4×6 | 24 ✓ |
| 5 | w: 5,5,5,5,4 | mixed | 24 ✓ |
| 4 | w: 6 | 6×4 | 24 ✓ |
| 3 | w: 8 | 8×3 | 24 ✓ |
| 2 | w: 12 | 12×2 | 24 ✓ |
| 1 | w: 24 | full-width | 24 ✓ |
| 7 | w: 3,3,3,3,4,4,4 | mixed | 24 ✓ |
When the count doesn't divide evenly into 24, widen the last few panels to absorb the remainder. For example, 7 stats → four w:3 + three w:4 = 24.
Multi-row stat blocks (e.g. 9+ stats): fill complete rows of 8 (w:3) first, then apply the table above to the remainder row. Example: 9 stats → row 1: eight w:3, row 2: one stat w:3 merged with related timeseries to fill 24, or widened to w:24 if standalone.
Multi-row stat blocks by group (e.g. Outbound API with 12 stats grouped by protocol): arrange as multiple full rows. Example: 6 stats per row × 2 rows, each w:4.
Timeseries panel row sizing:
| Panel count per row | Width each | Total |
|---|---|---|
| 1 | w: 24 | 24 ✓ |
| 2 | w: 12 | 24 ✓ |
| 3 | w: 8 | 24 ✓ |
A single timeseries MUST be w:24 — never w:12 alone on a row.
Pie + Timeseries paired rows (used in Validation dashboards):
Each dimension gets a pie chart + timeseries side by side. Two pairs per row:
[pie w:4] [timeseries w:8] [pie w:4] [timeseries w:8] = 24 ✓
One pair alone on a row: [pie w:6] [timeseries w:18] = 24 ✓ (widen to fill)
Stat + Timeseries mixed rows (used in Pipeline dashboards):
When combining stat cards with a large timeseries in the same row, ensure they tile to 24:
[stat w:4] [stat w:3] [timeseries w:17] = 24 ✓
Bar gauge / Bar chart panels: Use w:12 (half, paired with another panel) or w:24 (full) to fill the row.
Self-check before finalizing any dashboard: Scan every y coordinate. For each unique y, sum the w values of all panels at that y. If any sum is less than 24, fix it before saving.
When panels on the same row have different heights, the shorter panel(s) must collectively fill the full column height — otherwise a blank gap appears below them.
BAD: [stat h:4 ][timeseries h:8]
[ gap h:4 ]
← stat leaves 4 rows of blank space below it
GOOD: [stat h:8 ][timeseries h:8] ← single stat stretched to match
GOOD: [stat h:4][stat h:4][timeseries h:8] ← two stats stacked (y and y+4) fill h:8 together
Rule: For any column of panels adjacent to a taller panel, the sum of h values in that column MUST equal the height of the tallest panel in the row.
Concretely, when pairing stat(s) with a timeseries (h:8):
h:8h:4 (4+4=8 ✓)h:3,h:3,h:2 or restructurestatbackground_solidnonelastNotNullh: 4 always.w: 3 (8 per row), w: 4 (6 per row), or w: 5 (≈5 per row with mixed widths). Choose the width that makes the row sum to exactly 24.description explaining what it shows and (for threshold-based ones) the threshold meaning.| Metric Type | Unit | Thresholds (color steps) |
|---|---|---|
| Count / Total | short | Single step: blue at base |
| Success Rate | percentunit | green (base) → yellow at 0.95 → red below 0.95 (inverted: higher is better) |
| Error Rate | percentunit | green (base) → orange at 0.01 → red at 0.05 |
| Mean Latency | ms | green (base) → yellow at 50 → red at 100 |
| P95 Latency | ms | green (base) → yellow at 100 → red at 200 |
| Kafka Success Rate | percentunit | green (base) → yellow at 0.99 → red below 0.99 |
| Flagged / Blocked % | percentunit | green (base) → orange at 0.05 → red at 0.10 |
| Queue depth / Pending | short | green (base) → yellow at warning → red at critical (context-dependent) |
h: 8 always.w: 12 (2 per row), w: 8 (3 per row), or w: 24 (full-width). Never use a width that leaves a gap.linesmooth115opacity5, show points: autonone (unless explicitly showing stacked throughput by status)multi with sort desc for multi-query panels; single for single-query panels.list placement bottom. Include calcs: ["max", "mean"] for latency panels; omit calcs for throughput panels.symlog (log base 10) for latency panels to handle spikes. Use linear for throughput/QPS panels.histogram_quantile() with sum(rate(..._bucket{...}[1m])) by (le).1000 to convert seconds → milliseconds. Unit: ms.byRegexp matcher to set display names: P99, P95, P90, P50.sum(rate(..._count{...}[1m])) for QPS timeseries.sum(rate(...[1m])) by (status) to break down by status.1m for timeseries panels, 5m for stat panel averages.sum(increase(...[$__range])) by (dimension).<Metric> — % by <Dimension>.topk(N, ...).sum by (code) (increase(...[1h])).cluster=~"$cluster" in every query.app="$app" when the app variable exists.sum(increase(...[$__range])).avg_over_time(sum(rate(...[5m]))[$__range]).sum(increase(...{success}[$__range])) / clamp_min(sum(increase(...[$__range])), 1).
clamp_min(..., 1) on denominators to avoid division by zero. Exception: when the denominator is guaranteed non-zero (e.g. total requests in a high-traffic service), a plain division is acceptable.$__rate_interval or 1m as the rate window.histogram_quantile(0.XX, sum(rate(..._bucket{...}[interval])) by (le)) * 1000.sum(rate(..._sum{...}[interval])) / sum(rate(..._count{...}[interval])) * 1000.<namespace>_<component>_<metric_name>_<unit> (e.g. as_sdk_tracking_sdk_tracking_request_seconds_count).Every panel MUST have a description field. Follow this pattern:
"Average request latency across all endpoints over the selected time range. Green < 50ms, yellow < 100ms, red >= 100ms.""Aggregate HTTP request throughput across all endpoints, computed as a 1-minute rate.""Top Pixel validation issue types over the selected time range."Total Events, Mean QPS, Success Rate, P95 Latency, Error Rate.Event Throughput by Status (QPS), Request Latency, Non-Success Request Rate.<Subject> — % by <Dim> and <Subject> — Rate by <Dim>.Overview, Detail, Error Detail, Queue & Throughput, Latency & Audit Quality, Runtime Health.Overview stats: Total Requests → Mean QPS → Error Rate → Active Requests → Mean Latency → P95 → P90 → P50. Timeseries: QPS → Latency Percentiles → Top 10 Slowest Endpoints → Error Rate → Volume by Endpoint. Drill-down rows: Detailed URI Performance, Error Details.
Overview stats: Total Events → Mean QPS → Success Rate → Mean Latency → P95 Latency → HTTP Error Rate → Kafka Success Rate → Flagged %. Timeseries: Event Throughput by Status → Avg Latency. Drill-down rows: Regional Breakdown, Detail, Error Detail, SDK Version Adoption.
Overview stats: grouped by protocol (gRPC / HTTP Client / Feign) — each group has Total Calls → Success Rate → QPS → Mean Latency. Detail rows: one per protocol + Kafka Producer.
Overview stats: queue depths (Pending, Processing, Dispatched) → resource counts (Engines Registered, Available) → throughput stats (Request Rate, Success Rate, Avg Latency). Timeseries: Pipeline State Over Time (multiple gauge queries overlaid). Detail rows: one per pipeline stage (Ingestion, Dispatch, Engine Pool, Result Processing, Callback, System Health).
Overview stats: Total Events → Invalid Ratio → Rejected % → Flagged %. Sections per event source (SDK / Pixel): Total Issues → Avg Rate → Top 10 bar gauge → paired (pie + timeseries) for each dimension.
NEVER send a full dashboard JSON in a single update_dashboard call unless creating a brand-new empty dashboard skeleton. Large JSON payloads are expensive on context, error-prone, and hard to debug.
Instead, use incremental patch operations to build and modify dashboards piece by piece:
<project-name> and <application-name>.add operations.Step 1: collect or infer the project name and application name, normalize them to lowercase hyphenated tags
Step 2: update_dashboard with minimal dashboard JSON (no panels, just metadata + templating), ensuring `tags` includes both identity tags plus any domain/purpose tags
Step 3: update_dashboard with uid + operations: [{"op": "add", "path": "$.panels/- ", "value": <row panel>}]
Step 4: update_dashboard with uid + operations: [{"op": "add", "path": "$.panels/- ", "value": <stat panel 1>}]
...repeat for each panel or small batch of panels
Use uid + operations (patch mode) to make targeted changes:
| Task | Patch operation |
|---|---|
| Change a panel title | {"op": "replace", "path": "$.panels[2].title", "value": "New Title"} |
| Update a query | {"op": "replace", "path": "$.panels[2].targets[0].expr", "value": "new_promql{...}"} |
| Add a panel at the end | {"op": "add", "path": "$.panels/- ", "value": <panel JSON>} |
| Remove a panel | {"op": "remove", "path": "$.panels[5]"} |
| Update dashboard description | {"op": "replace", "path": "$.description", "value": "..."} |
| Change time range | {"op": "replace", "path": "$.time", "value": {"from": "now-6h", "to": "now"}} |
get_dashboard_summary or get_dashboard_property to inspect the current state before patching — don't guess panel indices.get_dashboard_summary after bulk removes.list_prometheus_metric_names and list_prometheus_label_values to find available metrics and labels for the target service.update_dashboard with a minimal JSON — title, description, tags, templating variables, time range. No panels yet. The tags array must include both the project tag and the application tag.update_dashboard with uid + operations (patch mode) to append panels row by row — overview stats first, then timeseries, then drill-down rows.get_dashboard_summary to confirm the dashboard structure is correct, including the required identity tags.generate_deeplink to give the user a direct link.Create or update a skill in this repository under skills/<skill-name>. Use when the user asks to add a new skill, improve an existing skill, scaffold skill structure, or align a skill with repository standards.
Work with Obsidian vaults — create and edit Obsidian Flavored Markdown (.md), Bases (.base), JSON Canvas (.canvas), and interact with vaults via the Obsidian CLI. Use when working with Obsidian notes, wikilinks, callouts, embeds, properties, frontmatter, tags, bases, canvas files, or vault operations.
Operate GitLab from terminal with `glab` for repositories, merge requests, issues, pipelines, releases, and API calls. Use for any GitLab task. For template-compliant MR creation, load reference workflow under references/.
Operate GitHub from terminal with `gh` for repositories, pull requests, issues, releases, actions, and API calls. Use for any GitHub task. For template-compliant PR or issue creation, load reference workflows under references/.
Manage day-to-day Git workflow with safe branch creation, conventional commits, rebasing, pushing, MR creation, active-branch sync, and integration-branch consolidation. Use when the user asks to create branches, commit, push, sync feature/fix branches, rebuild dev branches, or open merge requests.
Detect when the user is correcting the AI's approach or pointing out mistakes. Trigger phrases include 'you should', 'why not', 'that's wrong', 'use X instead', 'not like that', 'I said', 'no, do', 'wrong tool', 'wrong approach', 'I meant', 'actually', 'instead of', '不对', '应该用', '为什么不', '错了'. On activation, the AI reflects on what went wrong, identifies the correct approach, and logs the lesson to Obsidian for future reference.