# generate-resource-stubs

Generates Go stub files with grafana-foundation-sdk builders for dashboards and alert rules, as scaffolding to edit.

Skill by Grafana Labs. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add grafana/gcx --skill generate-resource-stubs
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add grafana/gcx --skill generate-resource-stubs -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 19. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/site/grafana.gcx/generate-resource-stubs)

## Source

[Open the source](https://github.com/grafana/gcx/tree/HEAD/claude-plugin/skills/generate-resource-stubs). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: generate-resource-stubs
description: >
  Generates typed Go stub files and grafana-foundation-sdk builder
  boilerplate for dashboards and alert rules. Use only when the user
  explicitly asks for stubs, generated resource skeletons, or builder
  boilerplate. This is scaffolding only; for designing or creating a usable
  dashboard with datasource discovery and snapshot iteration, use the
  create-dashboard skill instead. Triggers on "generate stub", "dashboard
  stub", "create alert rule stub", "foundation-sdk builder", or "builder
  boilerplate".
---

# Generate Typed Resource Stubs

Generate ready-to-edit Go files for dashboards and alert rules using
`gcx dev generate`. The generated code uses the grafana-foundation-sdk
builder pattern and compiles without modification.

This skill stops at scaffolding. If the task is to decide which dashboard
panels, variables, queries, and layout should exist, use `create-dashboard`
after generating the stub.

## Quick Start

```bash
# Dashboard stub
gcx dev generate dashboards/my-service-overview.go

# Alert rule stub
gcx dev generate alerts/high-cpu-usage.go

# Batch generation
gcx dev generate dashboards/a.go dashboards/b.go alerts/c.go
```

## How Type Inference Works

The resource type is inferred from the **immediate parent directory**:

| Directory | Type |
|-----------|------|
| `dashboards/` or `dashboard/` | dashboard |
| `alerts/`, `alertrules/`, or `alertrule/` | alertrule |

Override with `--type` when the directory doesn't match:

```bash
gcx dev generate internal/monitoring/cpu-alert.go --type alertrule
```

## Output

- Filename is normalized to snake_case: `my-dashboard.go` → `my_dashboard.go`
- Function name is CamelCase: `my-dashboard` → `MyDashboard()`
- Package name is derived from the parent directory

## After Generation: Building Real Dashboards

The generated stub is a starting point. See `references/foundation-sdk-guide.md`
for the full builder API reference to customize your dashboards and alerts.

### Dashboard Customization Cheat Sheet

```go
import (
    dashboard "github.com/grafana/grafana-foundation-sdk/go/dashboardv2beta1"
    "github.com/grafana/grafana-foundation-sdk/go/prometheus"
    "github.com/grafana/grafana-foundation-sdk/go/timeseries"
)

builder := dashboard.NewDashboardBuilder("My Dashboard").
    Tags([]string{"team:platform", "env:production"}).
    Editable(true).
    // Add a panel
    Panel("requests-panel",
        dashboard.NewPanelBuilder().
            Title("Request Rate").
            Visualization(timeseries.NewVisualizationBuilder()).
            Data(
                dashboard.NewQueryGroupBuilder().
                    Target(
                        dashboard.NewTargetBuilder().Query(
                            prometheus.NewDataqueryBuilder().
                                Expr(`rate(http_requests_total[$__rate_interval])`).
                                LegendFormat("{{method}} {{status}}"),
                        ),
                    ),
            ),
    ).
    // Layout
    AutoGridLayout(
        dashboard.AutoGrid().
            WithItem("requests-panel"),
    )

return dashboard.Manifest("my-dashboard", builder)
```

### Alert Rule Customization Cheat Sheet

```go
import (
    "github.com/grafana/grafana-foundation-sdk/go/alerting"
    "github.com/grafana/grafana-foundation-sdk/go/resource"
)

rule := alerting.NewRuleBuilder("High CPU Usage").
    Condition("A").
    For("5m").
    FolderUID("my-folder").
    RuleGroup("cpu-alerts").
    Labels(map[string]string{
        "severity": "critical",
        "team":     "platform",
    }).
    Annotations(map[string]string{
        "summary":     "CPU usage above 90% for 5 minutes",
        "description": "Instance {{ $labels.instance }} has high CPU usage.",
    })
```

## Common Issues

| Issue | Fix |
|-------|-----|
| "cannot infer resource type" | Directory name doesn't match known types; use `--type dashboard` or `--type alertrule` |
| "file already exists" | Delete the existing file first or use a different name |
| Need to add to registry | Manually add the function call to your `All()` function in `all.go` |
````

- Previous: [slo-investigate](https://syn4pse.dev/terminal/slo-investigate.md)
- Next: [slo-manage](https://syn4pse.dev/terminal/slo-manage.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
