grafana/skills

cue-kind-definition

Author CUE kind definitions for grafana-app-sdk apps - schemas, versioning, field constraints, named type definitions, custom routes, and codegen configuration.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/grafana/skills --skill cue-kind-definition

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

CUE Kind Definition

Common Workflows

Adding a new kind

bash
# 1. Scaffold the kind files
grafana-app-sdk project kind add MyKind --overwrite
# Produces kinds/mykind.cue + kinds/mykind_v1alpha1.cue + updates kinds/manifest.cue.

# 2. Edit the generated .cue files — fill in schema.spec / schema.status fields

# 3. Generate types and clients
grafana-app-sdk generate

# 4. Verify the generated artifacts exist
ls pkg/generated/    # should contain new types for MyKind

If generate fails with CUE errors:

  • Read the error — CUE prints the offending file + line + which constraint failed
  • Common causes: missing required field, type mismatch (e.g. string field assigned an int), unresolved reference between version files
  • Fix the .cue source, re-run grafana-app-sdk generate. Never edit files under pkg/generated/ — they're overwritten on every run.

Adding a new version to an existing kind

bash
# 1. Copy the existing version file
cp kinds/mykind_v1alpha1.cue kinds/mykind_v1.cue

# 2. Edit kinds/mykind_v1.cue — rename the top-level object (e.g. myKindv1) and adjust the schema

# 3. Register the new version in kinds/manifest.cue
#    Add a versions["v1"]: { schema: myKindv1 } entry

# 4. Re-generate
grafana-app-sdk generate

# 5. Verify both versions were generated — per-version Go types live under pkg/generated/<group>/<version>/
ls pkg/generated/             # should list both version directories (e.g. v1alpha1/ v1/)
# Optionally inspect the CRD spec under definitions/ to confirm both versions appear in `spec.versions[]`

Breaking changes (removing fields, changing types, adding required fields) must go into a new version — never modify a stable version (v1, v2) in place.

Kind file structure

The CLI produces a flat layout under kinds/:

kinds/
├── manifest.cue           # App manifest + version list declarations
├── mykind.cue             # Common (cross-version) kind metadata
└── mykind_v1alpha1.cue    # v1alpha1 schema + codegen config

For multi-version kinds, additional version files sit alongside (mykind_v1.cue, etc.). For very large kind sets (10+ kinds), consider the per-kind subdirectory layout — full kind anatomy reference in references/kind-layout.md.

CUE Kind Anatomy

Three layers per kind:

1. Common kind metadata

cue
// kinds/mykind.cue
package kinds

myKind: {
    kind: "MyKind"               // Required: PascalCase kind name
    // other cross-version fields (scope, pluralName, validation, mutation, conversion, …)
    // Full field reference in references/kind-layout.md.
}

2. Per-version schema

cue
// kinds/mykind_v1alpha1.cue
package kinds

myKindv1alpha1: myKind & {
    schema: {
        spec: {                       // desired state — user-set
            title:       string
            description: string | *""
            count:       int & >=0
            enabled:     bool | *true
        }
        status: {                     // observed state — operator-set
            lastObservedGeneration: int | *0
            state:                  string | *""
            message:                string | *""
        }
    }
    codegen: {
        ts: { enabled: true }
        go: { enabled: true }
    }
}

3. App manifest

cue
// kinds/manifest.cue
package kinds

App: {
    appName: "my-app"
    versions: {
        "v1alpha1": { schema: myKindv1alpha1 }
    }
}

Codegen configuration

Control what gets generated per kind per version:

cue
codegen: {
    ts: { enabled: true | false }   // TypeScript types
    go: { enabled: true | false }   // Go types + client
}

Disabling go for frontend-only apps avoids unused Go code. Disabling ts for backend-only resources reduces bundle size. Both default to true when omitted.

References

External resources

Related by task

from this repository

More skills

All skills
grafana
Community

loki

Grafana Loki log aggregation and LogQL query language. Covers LogQL syntax (log queries, metric queries, label matchers, line filters, parsers: json/logfmt/pattern/regexp/unpack, label filters, lineformat), Loki architecture, log ingestion via Alloy/Promtail/Fluent Bit, structured metadata, and Logs Drilldown. Use when writing LogQL queries, configuring Loki, troubleshooting log pipelines, or analyzing logs.

1h installs
2
GitHub stars
313
Updated
Nov 19
grafana
Community

profilecli-insights

Query live Pyroscope profiles with profilecli, analyze them with pprof, and correlate hot functions with checked-out source code. Use when the user asks to investigate a service with a configured Pyroscope server, profilecli, and pprof.

1h installs
2
GitHub stars
313
Updated
Nov 19
grafana
Community

prometheus-label-strategy

Expert evaluator for Prometheus label strategy on Grafana Cloud. Audits, designs, and improves label schemas using cardinality scoring, access-pattern alignment, static vs. dynamic label rules, histogram bucket discipline, and instrumentation hygiene. Prevents high cardinality at the source — in application code and scrape target labels — without dropping labels that make series unique (which breaks the data). For reducing the cost of series already in Grafana Cloud, routes to the adaptive-metri

1h installs
2
GitHub stars
313
Updated
Nov 19
grafana
Community

promql

Write, validate, and optimize PromQL for Prometheus / Grafana Mimir / Grafana Cloud Metrics. Covers rate vs irate vs increase, label matchers and regex, sum / avg / topk / by / without aggregation, classic + native histogramquantile, ratios with divide-by-zero guards, absent / changes for staleness, time offsets and predictlinear, recording-rule naming, SLO + burn-rate math, and a cardinality-hunting playbook. Use when writing a metric query, fixing wrong p95s, building an error-budget alert, de

1h installs
2
GitHub stars
313
Updated
Nov 19