module-scaffold
/module-scaffold
Given a component name, generate a complete standalone ODH module operator repository. Produces Go module, CRD types implementing PlatformObject, controller skeleton with reconciler builder pattern, Helm chart, Makefile, CI config, singleton webhook, and AGENTS.md. Use when starting a new module from scratch.
- Author
- opendatahub-io ↗
- Repository
- ai-helpers ↗
- Licence
- Apache-2.0
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Given a component name, generate a complete standalone ODH module operator repository. Produces Go module, CRD types implementing PlatformObject, controller skeleton with reconciler builder pattern, Helm chart, Makefile, CI config, singleton webhook, and AGENTS.md. Use when starting a new module from scratch.
Arguments
/module-scaffold <component-name>
Original author description
Given a component name, generate a complete standalone ODH module operator repository. Produces Go module, CRD types implementing PlatformObject, controller skeleton with reconciler builder pattern, Helm chart, Makefile, CI config, singleton webhook, and AGENTS.md. Use when starting a new module from scratch.
How it works
- Step 1: Parse arguments
- Step 2: Create directory structure
- Step 3: Generate CRD types
- Step 4: Generate controller
- Step 5: Generate Helm chart
- Step 6: Generate supporting files
- Step 7: Initialize Go module
- Step 8: Validate
- Gotchas
SKILL.md preview
---
name: module-scaffold
description: >-
Given a component name, generate a complete standalone ODH module operator
repository. Produces Go module, CRD types implementing PlatformObject,
controller skeleton with reconciler builder pattern, Helm chart, Makefile,
CI config, singleton webhook, and AGENTS.md. Use when starting a new module
from scratch.
allowed-tools: Bash Read Grep Glob Write Edit
user-invocable: true
disable-model-invocation: true
argument-hint: "<component-name>"
metadata:
author: ODH
version: "1.0"
tags: "odh, module, scaffold, operator, generator"
---
# ODH Module Scaffold
Generate a complete standalone module operator repository for the ODH platform.
## Step 1: Parse arguments
Extract the component name from `$ARGUMENTS`. If not provided, ask the user.
Derive these values from the component name (example: `model-registry`):
| Variable | Example Value |
|----------|---------------|
| `COMPONENT` | `model-registry` |
| `COMPONENT_SNAKE` | `model_registry` |
| `COMPONENT_PASCAL` | `ModelRegistry` |
| `COMPONENT_LOWER` | `modelregistry` |
| `COMPONENT_LOWER_PLURAL` | `modelregistries` |
| `MODULE_REPO` | `<COMPONENT>-operator` |
| `API_GROUP` | `components.platform.opendatahub.io` |
| `API_VERSION` | `v1alpha1` |
| `SINGLETON_NAME` | `default-<COMPONENT>` |
Ask the user:
1. Which API group to use: `components.platform.opendatahub.io` or
`services.platform.opendatahub.io`? Default: `components`.
2. Target directory? Default: `./<MODULE_REPO>`.
## Step 2: Create directory structure
Generate this layout:
```text
<MODULE_REPO>/
├── api/<API_VERSION>/
│ ├── <COMPONENT_SNAKE>_types.go
│ ├── <COMPONENT_SNAKE>_common.go
│ ├── groupversion_info.go
│ └── doc.go
├── internal/
│ ├── controller/
│ │ ├── <COMPONENT_SNAKE>_controller.go
│ │ └── <COMPONENT_SNAKE>_controller_actions.go
│ └── webhook/
│ └── singleton.go
├── charts/<MODULE_REPO>/
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ ├── deployment.yaml
│ ├── serviceaccount.yaml
│ ├── clusterrole.yaml
│ ├── clusterrolebinding.yaml
│ ├── webhook-service.yaml
│ ├── webhook-certificate.yaml
│ └── _helpers.tpl
├── cmd/
│ └── main.go
├── config/
│ └── samples/
│ └── <COMPONENT_SNAKE>.yaml
├── go.mod
├── Makefile
├── Containerfile
├── .github/workflows/
│ └── ci.yaml
├── .rules/
│ ├── api-types.md
│ ├── controller.md
│ ├── helm-chart.md
│ ├── security.md
│ └── testing.md
├── AGENTS.md
├── README.md
└── .gitignore
```
## Step 3: Generate CRD types
Use the templates from `${CLAUDE_SKILL_DIR}/references/templates.md` to
generate each file. Key requirements:
### `api/<API_VERSION>/<COMPONENT_SNAKE>_types.go`
The CR type must:
- Embed `metav1.TypeMeta` and `metav1.ObjectMeta`
- Have `Spec` field using `<COMPONENT_PASCAL>Spec`
- Have `Status` field using `<COMPONENT_PASCAL>Status`
- Include kubebuilder markers: `+kubebuilder:object:root=true`,
`+kubebuilder:subresource:status`, `+kubebuilder:resource:scope=Cluster`
- Include CEL singleton validation for the name
- Include compile-time assertion: `var _ common.PlatformObject = (*<COMPONENT_PASCAL>)(nil)`
- Implement all PlatformObject methods (GetStatus, GetConditions,
SetConditions, GetReleaseStatus, SetReleaseStatus)
The status struct must embed `common.Status` and
`common.ComponentReleaseStatus` both as **anonymous (unnamed) fields** with
`json:",inline"` tags. Use `common.ComponentReleaseStatus \`json:",inline"\``
instead of a named field like
`Releases common.ComponentReleaseStatus json:"releases,omitempty"` because
a named field serializes as a nested object `{releases: {releases: [...]}}`
instead of the flat array `{releases: [...]}` the CRD expects, causing
status update failures.
### `api/<API_VERSION>/<COMPONENT_SNAKE>_common.go`
Define `<COMPONENT_PASCAL>CommonSpec` with `common.ManagementSpec` embedded
inline. This struct is inlined into `<COMPONENT_PASCAL>Spec`.
### `api/<API_VERSION>/groupversion_info.go`
Standard kubebuilder groupversion registration using the chosen API group
and version.
### `api/<API_VERSION>/doc.go`
Package doc comment with `+groupName=<API_GROUP>` marker.
## Step 4: Generate controller
### `internal/controller/<COMPONENT_SNAKE>_controller.go`
The controller setup must:
- Use `reconciler.NewReconciler` with functional options pattern
- Register render, deploy, and gc actions (gc MUST be last)
- Use `ReconcilerFor` builder pattern with `WithReconcilerOpts` for release
info. The default conditions (Ready + ProvisioningSucceeded) are sufficient
for the scaffold. Add `WithConditions("Degraded")` only when real actions
explicitly manage it via `rr.Conditions.MarkFalse`/`MarkTrue`
- Import from `odh-platform-utilities` packages:
- `framework/controller/reconciler` for reconciler setup
- `framework/controller/conditions` for condition management
- `framework/controller/actions/deploy` for resource deployment
- `framework/controller/actions/gc` for garbage collection
- `framework/controller/actions/render` for manifest rendering
- `framework/api` for Release type
- `pkg/cluster` for platform detection
- `pkg/metadata` for label/annotation constants
### `internal/controller/<COMPONENT_SNAKE>_controller_actions.go`
Define three action functions:
1. **renderAction** -- use `framework/controller/actions/render`
2. **deployAction** -- use `framework/controller/actions/deploy` with SSA mode
3. **gcAction** -- use `framework/controller/actions/gc`
Each action follows the signature:
`func(ctx context.Context, rr *types.ReconciliationRequest) error`
## Step 5: Generate Helm chart
### `charts/<MODULE_REPO>/Chart.yaml`
```yaml
apiVersion: v2
name: <MODULE_REPO>
description: Helm chart for the <COMPONENT_PASCAL> module controller
version: 0.1.0
appVersion: "0.1.0"
type: application
```
### `charts/<MODULE_REPO>/values.yaml`
Provide defaults for: image repository/tag, replicas (1), resources
(requests: 100m CPU, 128Mi memory; limits: 500m CPU, 512Mi memory),
service account name, node selector, tolerations.
### Templates
Generate ONLY controller infrastructure manifests:
- **deployment.yaml** -- Controller Deployment with leader election,
health/readiness probes, security context (non-root, read-only rootfs)
- **serviceaccount.yaml** -- ServiceAccount for the controller
- **clusterrole.yaml** -- ClusterRole with module-specific RBAC (no wildcards)
- **clusterrolebinding.yaml** -- Bind the ClusterRole to the ServiceAccount
- **webhook-service.yaml** -- Service exposing webhook port 443 for the
singleton admission webhook
- **webhook-certificate.yaml** -- cert-manager Certificate for webhook TLS
(uses a self-signed Issuer scoped to the release namespace)
- **_helpers.tpl** -- Standard Helm helpers (name, labels, selectors)
Do NOT generate application-level manifests.
## Step 6: Generate supporting files
### `cmd/main.go`
Standard controller-runtime manager setup with:
- Scheme registration for the module API
- Health/readiness endpoints
- Leader election support
- Controller and webhook registration
### `Makefile`
Include targets: `build`, `test`, `lint`, `manifests`, `generate`, `fmt`,
`vet`, `docker-build`, `docker-push`, `helm-lint`.
### `Containerfile`
Multi-stage build: Go builder stage + distroless runtime stage.
### `.github/workflows/ci.yaml`
GitHub Actions workflow with: lint, test, build jobs. Pin actions to full
commit SHAs. Set `permissions: read-all`.
### `AGENTS.md`
Use the comprehensive template from
`${CLAUDE_SKILL_DIR}/../module-compliance/references/agents-md-template.md`
as a starting point. Replace `<COMPONENT_PASCAL>` and other placeholders with
the actual component values. This file provides passive guidance to AI agents
working in the module repo -- covering PlatformObject contract, controller
patterns, Helm chart rules, security, and separation of concerns.
### `.rules/` directory
Copy the rule files from
`${CLAUDE_SKILL_DIR}/../module-compliance/references/rules/` into the
generated repo's `.rules/` directory. These are path-scoped rules that
fire automatically when agents edit matching files (e.g., `api/**/*.go`,
`internal/controller/**/*.go`, `charts/**`). Files to copy:
- `api-types.md` -- CRD type conventions
- `controller.md` -- Controller patterns and GC ordering
- `helm-chart.md` -- Chart content restrictions
- `security.md` -- Webhook, TLS, RBAC, and metadata rules
- `testing.md` -- Test patterns and conventions
### `config/samples/<COMPONENT_SNAKE>.yaml`
A sample CR manifest with the singleton name and `managementState: Managed`.
### `README.md`
Brief README with: project description, prerequisites (Go 1.25+,
controller-runtime, cert-manager), build instructions, usage instructions.
### `.gitignore`
Standard Go gitignore (bin/, vendor/, *.exe, etc.).
## Step 7: Initialize Go module
Run the following commands in the generated directory:
```bash
cd <MODULE_REPO>
go mod init github.com/opendatahub-io/<MODULE_REPO>
go mod edit -require github.com/opendatahub-io/odh-platform-utilities@v0.1.0
go mod edit -require github.com/opendatahub-io/odh-platform-utilities/framework@v0.1.0
```
The root module (`api/common`, `pkg/`) is tagged at `v0.1.0`. The `framework`
sub-module has its own `go.mod` and requires a separate dependency line.
Note: `go mod tidy` will fail until the controller code compiles. Inform the
user that they should run `go mod tidy` after filling in the controller
implementation details and installing `controller-gen`.
## Step 8: Validate
Suggest the user run the `module-compliance` skill against the generated repo
to verify all contract rules pass. Also suggest running `make lint` and
`make test` once the Go dependencies are resolved.
## Gotchas
- `go mod tidy` will fail until controller-gen generates deepcopy methods and
all placeholder code compiles. Run `make generate` first.
- The Helm chart must contain ONLY controller manifests. Application workloads
are embedded in the controller binary and applied by the controller at
runtime.
- Do not import `github.com/openshift/api` for ManagementState. The shared
library uses a plain string type that is wire-compatible.
- The GC action must always be the last `.WithAction()` in the reconciler
builder chain. Deploy stamps annotations that GC reads -- reversing the
order deletes resources that were just deployed.
- The singleton name in the CEL rule must exactly match what the orchestrator
creates. Convention is `default-<component>`.
- `common.ComponentReleaseStatus` MUST be an anonymous inline embed in the
status struct: `common.ComponentReleaseStatus \`json:",inline"\``.
A named field like `Releases common.ComponentReleaseStatus` wraps the
inner `releases` array in an extra JSON object, producing
`{releases: {releases: [...]}}` which fails CRD validation.
- RBAC resource names (ClusterRole, ClusterRoleBinding) must be unique and
must not collide with names the in-tree operator handler creates for the
same component. The in-tree handler typically creates resources like
`<component>-operator-manager-role` and will overwrite any resource with
the same name via SSA, stripping the standalone controller's permissions.
Use the Helm `fullname` helper (which defaults to the chart name) to
generate unique names like `<MODULE_REPO>` instead of common patterns
like `*-manager-role`.
Files in this package (2)
- SKILL.md 11 KB
- references/templates.md 18 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · opendatahub-io/ai-helpers | 100 | Apache-2.0 |
| 26zl/cybersec-toolkit | 95 | MIT |
Database snapshot: 13.11.2026 · package version ddb0427a896f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100module-migrate
Read existing in-tree ODH operator component code and produce a step-by-step extraction checklist for migrating it to a standalone module. Analyzes controller logic, webhooks, RBAC, embedded manifests, and DSC field mappings. Use when extracting a component from the monolithic… - 100helm-framework
Scaffold and configure Helm charts that depend on the helm-framework library chart. Use when adding helm-framework as a Helm dependency, writing values.yaml for a chart built on it, or looking up what a value controls. - 100ark-controller-development
Guidance for developing the Ark Kubernetes operator. Use when modifying Go types, CRDs, controllers, or webhooks. Helps with CRD generation and Helm chart sync issues. - 90kubernetes-operator
Use when building a Kubernetes Operator — custom controllers that reconcile CRD state. Triggers on "build an operator", "CRD design", "reconcile loop", "controller-runtime", "kubebuilder", "operator-sdk", "custom resource", or "operator capability levels". NOT a generic k8s… - 95helm-patterns
Use this skill when the user says 'helm', 'helm chart', 'helm template', 'helm install', 'helm upgrade', 'helm rollback', 'helmfile', 'helm secrets', 'helm values', 'helm dependency', 'helm repository', 'helm plugin', 'helm unittest', 'helm lint', 'helm package', 'helm… - 100helm-chart-builder
This skill should be used when the user asks to "analyze Helm charts", "validate Helm values", "review chart structure", "check Kubernetes Helm templates", or "audit chart dependencies and configuration".