Skip to content
Skills Library
DevOps & cloud · Building & coding

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.

Repository
ai-helpers ↗
Licence
Apache-2.0
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

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

  1. Step 1: Parse arguments
  2. Step 2: Create directory structure
  3. Step 3: Generate CRD types
  4. Step 4: Generate controller
  5. Step 5: Generate Helm chart
  6. Step 6: Generate supporting files
  7. Step 7: Initialize Go module
  8. Step 8: Validate
  9. Gotchas
Original SKILL.md headings · 296 lines, 1,259 words
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

RepositoryScoreLicence
This page · opendatahub-io/ai-helpers100Apache-2.0
26zl/cybersec-toolkit95MIT

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".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.