AutoGineer
Generated banner for Cue Kind Definition
Generated logo for Cue Kind Definition

Cue Kind Definition

Grafana LabsOfficialPublished by Grafana Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

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.
— the description by Grafana Labs

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to defining resource kinds within the grafana-app-sdk ecosystem using CUE. It covers the full lifecycle of kind management, including scaffolding new resources, defining complex schemas with field constraints, versioning, and configuring code generation for Go and TypeScript. It ensures that developers can maintain consistent, type-safe resource models while adhering to the framework's specific manifest and directory requirements.

What it does

  • Scaffolds new resource kinds using the CLI.
  • Defines spec and status schemas with advanced CUE constraints like regex, enums, and ranges.
  • Supports reusable struct definitions using # prefixed types.
  • Manages multi-version resource schemas and manifest registration.
  • Configures per-kind code generation settings for Go and TypeScript.
  • Facilitates the definition of custom API routes at the kind or version level.

When to use it

  • When creating a new resource type for a grafana-app-sdk application.
  • When adding a new version to an existing resource kind.
  • When defining or updating schema field constraints and validation rules.
  • When you need to define reusable struct types for complex resource models.
  • When adding custom API routes to your application.

Advantages

  • Ensures type safety through CUE's constraint-based language.
  • Automates the generation of Go and TypeScript code from schema definitions.
  • Provides a standardized directory structure for maintainable projects.
  • Supports explicit versioning to handle breaking changes safely.
  • Reduces manual boilerplate by integrating directly with the SDK's generation tools.

Usage examples

“How do I add a new resource kind called 'DashboardConfig' to my app?”
The agent will guide you to run 'grafana-app-sdk project kind add DashboardConfig', edit the generated .cue files in the kinds/ directory, and execute 'grafana-app-sdk generate' to create the necessary Go and TypeScript artifacts.
“I need to add a regex constraint to a string field in my schema.”
The agent will show you how to use the '&' operator with the regex pattern, such as 'myField: string & =~"^[a-z]+"'.
“How do I create a new version for an existing kind?”
The agent will instruct you to copy the existing version file, rename the top-level object, register the new version in 'kinds/manifest.cue', and re-run the generation command.
“How can I define a reusable struct for my spec?”
The agent will explain how to define a '#'-prefixed type within the schema block, which allows you to reuse the struct across multiple fields and ensures it is generated as a named type.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/grafana/cue-kind-definition/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip cue-kind-definition.zip -d .agents/skills

Documentation by Grafana Labs

CUE Kind Definition

Common Workflows

Adding a new kind
# 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
# 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
// 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
// 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
// kinds/manifest.cue
package kinds

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

Codegen configuration

Control what gets generated per kind per version:

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

Files

ATTRIBUTION.md

Attribution

This folder is an unmodified copy of the Agent Skill "cue-kind-definition", distributed by AutoGineer (https://autogineer.com/agent-skills).

The skill's own files are unmodified copies. AutoGineer is not affiliated with or endorsed by the author or the publisher.

Files added by AutoGineer

  • ATTRIBUTION.md: this file, written by AutoGineer

  • LICENSE: copied from LICENSE

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Grafana Labs
Publisher
Grafana Labs (Official)
Source
grafana/skills · skills/grafana-app-sdk/cue-kind-definition · commit 8fb72a5
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Grafana Labs.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cue-kind-definition.zip