# Operator API Standards

> Standards, conventions, and dos/don'ts for adding or changing CRD types in the operator API (`operator/api/v1`). Use this skill whenever editing or creating files under `operator/api/v1/` (any *_types.go), adding/removing/renaming a CRD field, introducing a new Kind/CRD, adding kubebuilder validation or defaulting markers, or designing an overrides/configuration field. Trigger even if the user doesn't mention "standards" — any change to operator CRD types should follow these conventions.

- Skill: `projectcalico/operator-api-standards` (Agent Skill)
- Install (CLI): `npx skillmds@latest add projectcalico/operator-api-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/projectcalico/operator-api-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: projectcalico (https://skillmd.com/u/projectcalico)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/projectcalico/operator-api-standards

---


# Operator API Standards

When adding or changing CRD types under `operator/api/v1/`:

1. **Read [`operator/docs/api_design.md`](../../../operator/docs/api_design.md)** — the API design
   principles plus the concrete Go/kubebuilder coding conventions (optional vs
   required fields, the `Enabled`/`Disabled` enum idiom, validation/CEL markers,
   the top-level Kind marker block, shared-type reuse, the Deployment override
   pattern) and the end-of-file **checklist**. Apply all of it, and run the
   checklist before you finish.
2. **Read [`DESIGN.md`](../../../operator/DESIGN.md)** for related rules
   ("Respect User Input", "Resource Ownership") when a judgement call isn't
   settled by `api_design.md`.
3. Follow the post-change workflow in `api_design.md` — `make gen-files`,
   verify scope didn't flip to `Namespaced`, update `convert` if relevant, and
   `make dirty-check`.