observability-designer

Overview of observability-designer skill

What observability-designer is for

observability-designer is an engineering skill for designing practical observability systems: service dashboards, alert reviews, and lightweight SLI/SLO frameworks. It is most useful when you need a structured observability plan for an API, web application, or production service and want the output to reflect metrics, logs, traces, golden signals, alert quality, and dashboard usability.

Best-fit users and jobs

The observability-designer skill fits SREs, platform engineers, backend teams, and technical leads who are adding monitoring to a new service, cleaning up noisy alerts, or standardizing dashboards across teams. It is especially useful when you already know the service shape—criticality, endpoints, dependencies, traffic, ownership, and current alert rules—but need help turning that context into an operational design.

What makes this skill different

Unlike a generic “make me a monitoring plan” prompt, this repository includes runnable Python scripts and examples. dashboard_generator.py can produce dashboard specifications, alert_optimizer.py can analyze alert noise and gaps, and slo_designer.py can scaffold an SLO framework. The included references/ files also encode alert design patterns, dashboard best practices, and SLO guidance, which gives the agent a more opinionated operating model.

Important limitation before install

For deep SLO work—error-budget math, multi-window burn-rate thresholds, and SLO governance—the upstream skill itself points users toward slo-architect. Treat observability-designer for Observability as strongest for dashboard design and alert-noise reduction, with SLO output as a starting scaffold rather than the final authority.

How to Use observability-designer skill

observability-designer install and first files to read

Install from the skill repository with:

npx skills add alirezarezvani/claude-skills --skill observability-designer

Then inspect the skill path: engineering/skills/observability-designer. Read SKILL.md first for routing guidance and quick starts, then README.md for script usage. Review assets/sample_service_api.json, assets/sample_service_web.json, and assets/sample_alerts.json before running anything; these show the expected input shape better than a prose description.

Inputs that produce better observability output

The skill works best when you provide a service profile, not just a service name. Include service type (api, web, worker, batch), criticality, user-facing status, team owner, environment, dependencies, important endpoints or pages, latency expectations, throughput, business metrics, current dashboards, and alert history.

A weak prompt is: “Design monitoring for payments.”
A stronger prompt is: “Use observability-designer for a critical user-facing payment API in Kubernetes. It has POST /payments at 100 TPS with 500 ms target latency, depends on user-service, payment-gateway, and fraud-detection, and current alerts fire 20 times/day with many latency false positives. Produce dashboard sections, alert changes, and SLI/SLO candidates.”

Practical script-based workflow

For dashboard work, start with the generator:

python3 scripts/dashboard_generator.py --service-type api --name payments --criticality critical --role sre --format grafana -o dashboard.json --doc-output dashboard.md

For alert cleanup, use your alert config in the same rough shape as assets/sample_alerts.json:

python3 scripts/alert_optimizer.py --input alerts.json --analyze-only --report alert_report.json

For SLO scaffolding:

python3 scripts/slo_designer.py --service-type api --criticality critical --user-facing true --service-name payment-service

Use the generated files as review artifacts, not as blindly deployable production configuration.

Suggested agent workflow

Ask the agent to read references/alert_design_patterns.md before alert review, references/dashboard_best_practices.md before dashboard generation, and references/slo_cookbook.md before SLO scaffolding. Then have it compare output against expected_outputs/sample_dashboard.json or expected_outputs/sample_slo_framework.json so formatting and coverage are clear. This reduces ambiguity and makes observability-designer usage more repeatable.

observability-designer skill FAQ

Is observability-designer beginner-friendly?

Yes, if the user can describe the service and understands basic monitoring terms such as latency, error rate, saturation, logs, traces, and alerts. Beginners should start from the sample JSON files because they reveal the level of detail needed. The skill will not automatically discover your architecture or telemetry conventions.

When should I not use observability-designer?

Do not use it as the final source of truth for strict SLO policy, compliance reporting, or organization-wide error-budget governance. Also avoid it when you have no service context, no telemetry names, and no operational goals; the output will become generic. For pure SLO architecture, prefer a dedicated SLO skill.

How is it different from an ordinary observability prompt?

An ordinary prompt may produce a plausible checklist. The observability-designer skill adds a repeatable workflow, sample service inputs, expected outputs, and scripts for dashboard generation, alert analysis, and SLO scaffolding. That makes it better for teams that want artifacts they can review, adapt, and store alongside service documentation.

Does it fit Prometheus, Grafana, and cloud observability stacks?

The examples lean toward Prometheus-style alert expressions and Grafana-style dashboard output, but the design logic is portable. You can adapt the generated structure to Datadog, New Relic, CloudWatch, OpenTelemetry-based stacks, or internal platforms if you provide metric names, labels, ownership conventions, and dashboard constraints.

How to Improve observability-designer skill

Improve observability-designer inputs first

The biggest quality gain comes from richer service context. Add real endpoint latency targets, dependency criticality, traffic levels, recent incidents, paging pain, false-positive rates, and business impact metrics. For alert optimization, include historical fields such as fires per day, average duration, false-positive rate, severity, owner, and runbook URL.

Prevent common failure modes

The most common failure is producing dashboards that look complete but do not answer operational questions. Ask for dashboard sections by audience: SRE, developer, executive, and on-call responder. Another failure is alerting on causes instead of user-visible symptoms. Require the output to label each alert as symptom-based, actionable, deduplicated, and tied to a runbook or response.

Iterate after the first output

After the first pass, review for missing dependencies, noisy alerts, unclear thresholds, and panels that cannot be backed by real metrics. Then prompt: “Revise this observability-designer output using only metrics we actually emit, mark missing instrumentation separately, and separate immediate fixes from future telemetry work.” This turns a broad design into an implementation plan.

Add local conventions to make it production-ready

Before adopting generated artifacts, add your naming conventions, severity model, escalation policy, dashboard folder structure, service labels, environment labels, and runbook standards. The observability-designer guide is strongest when it is grounded in your platform rules rather than treated as a universal default.