Cue Kind Definition

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

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/grafana/cue-kind-definition/download

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

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

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

External resources

Files

ATTRIBUTION.mdAdded by AutoGineer861 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md5.3 KiB
references/cue-constraints.md6.3 KiB
references/custom-routes.md1.6 KiB
references/kind-layout.md7.6 KiB
references/schema-types.md2.0 KiB
references/versioning-guide.md6.3 KiB

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.

Deployment Strategies Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, state management, and enterprise-grade IaC patterns.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Terraform Module Library
Seth Hobson· Community
A comprehensive guide to building reusable, production-ready Terraform modules across AWS, Azure, GCP, and OCI.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Cloud Infrastructure Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, module design, and enterprise-grade GitOps workflows.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Cicd Automation Terraform Specialist
Seth Hobson· Community
An expert Terraform and OpenTofu specialist for advanced infrastructure automation, state management, and enterprise-grade GitOps workflows.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Terraform Azure Planning
GitHubOfficial
An expert Azure Cloud Engineering persona that generates structured Terraform implementation plans.
Cloud and DevOpsGitHub Copilot
MITGitHub stars of the source repository40.9k
Terratest Module Testing
GitHubOfficial
Generate and refactor Go Terratest suites for Terraform modules with CI-safe patterns and negative-path validation.
Cloud and DevOpsGitHub Copilot
MITGitHub stars of the source repository40.9k

Download ZIP

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