module-scaffold
/module-scaffold
Generuje z nazwy komponentu kompletne repozytorium samodzielnego operatora modułu ODH: moduł Go, typy CRD, szkielet kontrolera, chart Helm, Makefile, CI i webhook.
- Autor
- opendatahub-io ↗
- Repozytorium
- ai-helpers ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 22.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Generuje z nazwy komponentu kompletne repozytorium samodzielnego operatora modułu ODH: moduł Go, typy CRD, szkielet kontrolera, chart Helm, Makefile, CI i webhook.
Argumenty
/module-scaffold <component-name>
Oryginalny opis (EN)
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.
Jak działa
- 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
Podgląd SKILL.md
---
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`.
Pliki w paczce (2)
- SKILL.md 11 KB
- references/templates.md 18 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · opendatahub-io/ai-helpers | 100 | Apache-2.0 |
| 26zl/cybersec-toolkit | 95 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki ddb0427a896f (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100module-migrate
Czyta kod komponentu operatora ODH i tworzy krok po kroku listę kontrolną wydzielenia go do samodzielnego modułu, analizując kontrolery, webhooki, RBAC i manifesty. - 100helm-framework
Tworzy szkielet i konfiguruje chart Helm oparty na bibliotecznym chart helm-framework: dodanie zależności, pisanie values.yaml i sprawdzanie, co dana wartość kontroluje. - 100ark-controller-development
Wspiera rozwój operatora Ark dla Kubernetes przy zmianach typów Go, CRD, kontrolerów i webhooków oraz problemach z generowaniem CRD i synchronizacją Helm chart. - 90kubernetes-operator
Pomaga budować Operatora Kubernetes, czyli własne kontrolery uzgadniające stan CRD: projekt CRD, pętla reconcile, controller-runtime, kubebuilder i operator-sdk. - 95helm-patterns
Pomaga przy poleceniach i wzorcach Helm: instalacja, aktualizacja, wycofanie, wartości, testy, hooki i rejestry OCI. - 100helm-chart-builder
Analizuje charty Helm, waliduje wartości, recenzuje strukturę chartu, sprawdza szablony Kubernetes i audytuje zależności i konfigurację.