Index of every page on this site: llms.txt
All skills
kubernetes-sigs avatar

/k8s-api-conventions

@413f058
Run it yourself

Guides the agent to follow Kubernetes API conventions for OSS standards.

Use this Skill: https://skilld.dev/gh/kubernetes-sigs/agent-sandbox/k8s-api-conventions

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈23 tokens for metadata: the name and description. ≈1.5k when used: this file. ≈29k more on demand in 1 file.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈94 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Kubernetes API Conventions Skill

Purpose

This skill ensures that all Custom Resource Definitions (CRDs) generated or modified in this project follow the established conventions defined by the Kubernetes community.

Instructions

  1. CRDs as First-Class APIs: Adhere to the guidelines in the official Kubernetes API conventions. CRDs must follow the same conventions regarding field naming, types, and structure (Spec/Status separation) as core Kubernetes resources.
  2. Primary Guidelines: Rely on the condensed "Gotchas" below for 90% of standard CRD and API reviews. These represent the most common compliance failures derived from Kubernetes API conventions and community best practices, which automated linters often miss:
    • Label Values: Do NOT use full resource names as label values. Kubernetes enforces a strict 63-character limit on label values, whereas resource names can be up to 253 characters. Using full resource names in labels can lead to asynchronous runtime failures (e.g., a parent resource is successfully created, but the controller continuously fails to create child resources due to label length limits). When resource names must be reflected in labels, implement safe truncation or hashing in the controller logic to ensure values remain under 63 characters.
    • Preview Features: Do NOT use annotations for alpha/preview features. Use new API fields instead, to avoid migration difficulties later.
    • Status Properties: Use conditions instead of phase for tracking state.
    • Condition Lifecycle: Once a controller sets a condition, keep it and change its status (True, False, Unknown) instead of removing it. Removing a condition erases lastTransitionTime, the record of when it last changed, and breaks automation that waits for a status, such as kubectl wait --for=condition=Suspended=False. Set new conditions the first time the controller reconciles the object, using Unknown if the state isn't known yet. Clients should check status and treat a missing condition as Unknown, not as a separate state. Making an existing condition persistent changes behavior for clients that check presence, so it needs a release note (see Suspended in #1150).
    • Mutating Spec: The spec of the primary Custom Resource (CR) being reconciled is user-owned and should not be modified and saved back to the API server by the reconciler. This avoids mutating user intent. Controllers may, however, create and update the spec of secondary or target objects (for example, the HPA controller updating a Deployment's spec.replicas).
    • Zero vs. Unset: Use pointers for fields where it is important to distinguish between a zero value (e.g., 0) and the field being unset.
    • Scalability: Avoid storing unbounded lists of items in the API (etcd has size limits). Consider aggregating or summarizing lists in status.
    • Metrics Cardinality & Normalization: Never introduce high or unbounded cardinality Prometheus labels (e.g., pod names, UIDs, timestamps, raw errors). When deriving label values from dynamic input or errors, apply metrics normalization (an allowlist switch or categorizer) to map strings into a small, fixed enum.
    • Think twice about booleans: Avoid booleans for fields that might evolve to have more states in the future. Use enums or string fields instead.
    • Declarative Field Names: Ensure field names describe the desired state, not an action (e.g., use suspended instead of suspend).
    • Lists over Maps: Do not use maps of subobjects (e.g., ports: {www: {port: 80}}). Use a list of subobjects containing a name field (e.g., ports: [{name: www, port: 80}]). The only exceptions are pure string maps (labels, annotations).
    • Integer & Float Types: Always use explicit int32 or int64 (preferring int32), never ambiguously sized int or unsigned integers (uint). Avoid floating-point types entirely in spec.
    • Duration & Timestamp Naming: Express durations with a Seconds suffix (e.g., periodSeconds, timeoutSeconds). For timestamps, use somethingTime (e.g., lastTransitionTime), avoiding the word stamp.
    • Allocated Values in Status: If a controller automatically allocates a resource (like a ClusterIP, port number, or storage ID) on behalf of the user, store the resulting allocated value in status, not spec.
    • Breaking Changes: Whenever reviewing or proposing changes that alter existing default runtime behaviors, flag them as breaking changes that require deprecation cycles and migration paths.
    • Controller CLI Flags vs. Declarative CRs: Do NOT use global controller command-line flags to configure tenant workload semantics or operational behaviors; all workload behavior must be configured declaratively via Custom Resources. When global CLI flags exist for platform-level baseline governance, ensure declarative Custom Resource configuration always takes precedence.
    • API Schema Minimization: Do NOT expand CRD schemas with new fields unless strictly necessary. Avoid toggle proliferation (introducing multiple overlapping configuration mechanisms for a single behavior) and establish clear, declarative precedence hierarchies.
    • Controller Logging Discipline: In high-frequency Reconcile loops, reserve logger.Info / V(0) for major state changes and lifecycle milestones (e.g., resource created, claim adopted). Require logger.V(4).Info for routine steady-state checks, cache lookups, or status fall-throughs.
    • Call-Site & Downstream Impact Auditing: When modifying helper predicates, validation functions, or error return criteria, audit all call sites across reconcilers to prevent downstream side effects (e.g., premature queue evictions or cache drops).
  3. Deep-Dive Reference: If you encounter complex architectural ambiguity, custom subresources, or edge cases not covered by the Gotchas above, consult the full upstream specification at references/api-conventions.md.

References

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    The skill provides instructional guidance on following Kubernetes API conventions for Custom Resource Definitions (CRDs) and general API design. It is purely informational and contains no executable code or risky patterns.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: HIGH · 1 issue

Signed by skilld at 413f058. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for kubernetes-sigs/agent-sandbox/k8s-api-conventions