Cue Kind Definition

by grafana1ccacf29049fApache-2.0279 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Author CUE kind definitions for grafana-app-sdk apps - schemas, versioning, field constraints, named type definitions, custom routes, and codegen configuration. Scaffolds kinds via `grafana-app-sdk project kind add`, writes spec/status schemas with type constraints (regex, enum, range), defines `#`-prefixed named types for reusable structs, registers versions in the app manifest, and runs `grafana-app-sdk generate` with explicit error recovery. Use when working with CUE kinds, adding a new resource type, adding a version to an existing kind, writing schema field constraints, defining `#Definition` types, adding custom routes, editing files under `kinds/`, or when the user asks to "model a resource", "add a CUE schema", or "write a kind" — even without saying "CUE" explicitly.

Instructions onlySoftware Development AI & Agents

AI-generated overview

Authors CUE kind definitions for grafana-app-sdk apps, covering schemas, versioning, constraints and codegen.

What it does: This skill guides the authoring of CUE kind definitions for grafana-app-sdk applications. It scaffolds kinds with the grafana-app-sdk project kind add command, writes spec and status schemas with field constraints, defines reusable named types, registers versions in the app manifest, and runs grafana-app-sdk generate with error recovery. It also covers adding a version to an existing kind and configuring TypeScript and Go code generation.
When to use it: Use it when working with CUE kinds, adding a new resource type or a version to an existing kind, writing schema field constraints, defining named types, adding custom routes, or editing files under kinds/. It also applies when a user asks to model a resource, add a CUE schema, or write a kind.
Requirements: Requires the grafana-app-sdk CLI for scaffolding and code generation, and CUE tooling for schema validation. It ships no scripts, only instructions and reference documents.

CUE Kind Definition

Common Workflows

Adding a new kind

bash

# 1. Scaffold the kind filesgrafana-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 clientsgrafana-app-sdk generate
# 4. Verify the generated artifacts existls pkg/generated/    # should contain new types for MyKind

# 1. Scaffold the kind filesgrafana-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 clientsgrafana-app-sdk generate
# 4. Verify the generated artifacts existls 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 filecp 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-generategrafana-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[]`

# 1. Copy the existing version filecp 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-generategrafana-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

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 [blocked].

CUE Kind Anatomy

Three layers per kind:

1. Common kind metadata

cue

// kinds/mykind.cuepackage 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.}

// kinds/mykind.cuepackage 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.cuepackage 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 }    }}

// kinds/mykind_v1alpha1.cuepackage 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.cuepackage kinds
App: {    appName: "my-app"    versions: {        "v1alpha1": { schema: myKindv1alpha1 }    }}

// kinds/manifest.cuepackage 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}

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

references/kind-layout.md [blocked] — full common-metadata field reference + app manifest fields + per-kind subdirectory layout
references/schema-types.md [blocked] — CUE schema field types (basic types, constraints, regex, enums, maps, lists) + #-prefixed named type definitions
references/custom-routes.md [blocked] — kind-level + version-level custom routes + handler registration in app.go

External resources

Source and attribution

Source:grafana/skillsinskills/grafana-app-sdk/cue-kind-definitionat commit1ccacf2

License: Apache-2.0

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from grafana/skills

React 19 Plugin Migration

grafana

Guides migration of a Grafana plugin to React 19 compatibility through ordered build, dependency and source-code steps.

Software Development279updated today

Plugin Bundle Size

grafana

Guides optimisation of Grafana app plugin bundle size using React.lazy, Suspense and webpack code splitting.

Software Development279updated today

Grafana Scenes

grafana

Builds Grafana plugin pages with the @grafana/scenes framework, covering scenes, panels, variables and drilldowns.

Software Development279updated today

Check Npm

grafana

Read-only audit of npm, yarn, or pnpm configuration for supply-chain hardening in a JS/TS repository.

Security279updated today

Mimir

grafana

Guides standing up and operating Grafana Mimir for scalable, multi-tenant, long-term Prometheus and OTLP metrics storage.

DevOps & Cloud279updated today

K6 Trend Analysis

grafana

Analyze Grafana Cloud k6 test run trends over time. Detects slow metric drift (e.g., P95 latency creeping up while still passing thresholds), computes headroom to thresholds, flags anomalies, and recommends threshold tightening. Use when the user asks about test performance trends, wants to know if metrics are degrading, asks whether thresholds should be tightened, or wants a health check across recent runs for a specific test. Trigger on phrases like "how is my test trending", "is P95 getting worse", "check for performance regression", "should I tighten thresholds", "are my tests degrading", "show me trends for test X", "analyze my k6 test runs", or "is my test getting slower". Also trigger when a user asks to check all tests in a project -- run this skill once per test and synthesize.

Awaiting classification279updated today

Cue Kind Definition

CUE Kind Definition

Common Workflows

Adding a new kind

Adding a new version to an existing kind

Kind file structure

CUE Kind Anatomy

1. Common kind metadata

2. Per-version schema

3. App manifest

Codegen configuration

References

External resources

Source and attribution

More from grafana/skills

React 19 Plugin Migration

Plugin Bundle Size

Grafana Scenes

Check Npm

Mimir

K6 Trend Analysis

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices