Agent skill

Gitops Knowledge

Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging).

Apache-2.0Auto-check passedDevOps & Cloud

Install Gitops Knowledge

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/gitops-knowledge .claude/skills/gitops-knowledge && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .claude/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/gitops-knowledge .agents/skills/gitops-knowledge && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .agents/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/gitops-knowledge .cursor/skills/gitops-knowledge && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .cursor/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/fluxcd/agent-skills.git --path skills/gitops-knowledge

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/gitops-knowledge .gemini/skills/gitops-knowledge && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .gemini/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/gitops-knowledge .github/skills/gitops-knowledge && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .github/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add fluxcd/agent-skills --skill gitops-knowledge -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install fluxcd/agent-skills gitops-knowledge --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/fluxcd/agent-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/gitops-knowledge .opencode/skills/gitops-knowledge && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "gitops-knowledge" agent skill from https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-knowledge into .opencode/skills/gitops-knowledge/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gitops-knowledge", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: gitops-knowledge
GitHub stars: 230
Token cost: ~3.8k tokens
SKILL.md length: 1,266 words
Files: 39 (incl. references, assets)
Skills in repo: 6
Repo updated: Oct 2, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging).

Works in 6 steps: GitOps Pipeline (GitRepository +… → Helm from OCI Registry (Recommended) → FluxInstance with OCI Sync (Gitless… → …
Users ask about Flux concepts
SKILL.md covers What is Flux, Controllers, CRDs and References, Ordering and Reactivity and Decision Trees, plus 2 more sections
Reaches github.com

What it does

Gitops Knowledge is an agent skill from fluxcd/agent-skills. Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging). Use when users ask about Flux concepts, want manifests for HelmRelease, Kustomization, GitRepository, OCIRepository, ResourceSet, FluxInstance, or any Flux resource. When user needs guidance on GitOps repository structure, bootstrap Flux with Terraform, multi-tenancy, OCI-based delivery, image tag automation, drift detection, preview environments, monorepo app…

Its SKILL.md is about 3.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 40 other files, including reference files and assets.

It sits in DevOps & Cloud, covering GitOps. It works with Model Context Protocol and Terraform. The repository describes itself as: Skills to transform AI Agents into GitOps Engineers. The licence is Apache-2.0.

When your agent uses it

Users ask about Flux concepts
Want manifests for HelmRelease
Any Flux resource
Needs guidance on GitOps repository structure

Example prompts

“/gitops-knowledge”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

GitOps Pipeline (GitRepository + Kustomization)
Helm from OCI Registry (Recommended)
FluxInstance with OCI Sync (Gitless GitOps)
ResourceSet for Multi-Component Orchestration
Image Automation
Notifications

What it can do on your machine

Read from SKILL.md and the folder at commit 0d1fa6c. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are yaml).
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
- github.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Gitops Knowledge loads about 3.8k tokens when it runs, and up to ~60k if it reads all its reference files. Until then it costs about 162 tokens; SKILL.md has 1,266 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~162
When it runs · the whole SKILL.md, loaded when a task matches: ~3.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~60k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from fluxcd/agent-skills at commit 0d1fa6c, republished under its Apache-2.0 licence (© fluxcd). 1,266 words, ~3,832 tokens.

Download SKILL.mdSave it as .claude/skills/gitops-knowledge/SKILL.md (or your agent's skills folder). This skill also uses 38 other files; get the full folder from GitHub.

name: gitops-knowledge
description: Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging). Use when users ask about Flux concepts, want manifests for HelmRelease, Kustomization, GitRepository, OCIRepository, ResourceSet, FluxInstance, or any Flux resource. When user needs guidance on GitOps repository structure, bootstrap Flux with Terraform, multi-tenancy, OCI-based delivery, image tag automation, drift detection, preview environments, monorepo app delivery, running migration Jobs before or after a deployment, notifications, or the Flux Web UI and MCP Server.
license: Apache-2.0

Flux CD Knowledge Base

You are an expert on Flux CD, the GitOps toolkit for Kubernetes. Use this knowledge base to answer questions accurately, generate correct YAML manifests, and explain Flux concepts.

Rules:

Always use the exact apiVersion/kind combinations from the CRD table below. Never invent API versions.
Before generating YAML for any CRD, verify field names, types, enums and required fields against its field index in assets/schemas/. Each line is <dotted.path> <type> [(required)] [enum=a|b] [default=x] [pattern="..."] [min=N max=N] # description (arrays as path[], maps as <map[string]T>). Grep a path prefix to list a subtree (grep '^spec\.chart\.' assets/schemas/helmrelease-helm-v2.fields.txt) or a field name to find where it lives. Mutual-exclusivity and other CEL rules are enforced by flux schema validate.
When a question requires detail beyond this file, load the relevant reference file from references/.
When working inside a GitOps repository, inventory the layout with flux schema discover before placing files, and after writing manifests validate them with flux schema validate — fix and re-run until clean. Load references/flux-cli.md for the full CLI workflow, local rendering, and overlay debugging. If the tools aren't installed, skip validation and say so.
Prefer Flux Operator (FluxInstance) for cluster setup. Do not reference flux bootstrap or legacy gotk-* files.

What is Flux

Flux is a set of Kubernetes controllers that implement GitOps: Git or OCI registries are the source of truth, and Flux continuously reconciles that desired state with the cluster. Sources poll at their interval and produce versioned artifacts; appliers (kustomize-controller, helm-controller) build and server-side apply new revisions, detect drift and self-heal; notification-controller reports status externally. Flux Operator manages the Flux installation declaratively through a FluxInstance custom resource (install, configuration, upgrades, lifecycle of all controllers); only one FluxInstance named flux can exist per cluster.

Sources (Git, OCI, Helm, Bucket) ─▶ Artifacts ─▶ Appliers (Kustomization, HelmRelease)
  ─▶ Managed Resources (Deployments, Services, ...) ─▶ Notifications (Provider + Alert)

ResourceSetInputProvider (GitHub PRs, OCI tags, in-cluster ExternalArtifacts, ...)
  ─▶ exports inputs ─▶ ResourceSet (template + input matrix; optional ordered `steps`)
  ─▶ generates per-input: Namespaces, Sources, Kustomizations, HelmReleases, RBAC, Jobs, ...

Two delivery models: Git-based (Flux watches Git and applies on commit) and Gitless (Git → CI pushes OCI artifacts → Flux pulls from the registry; artifacts are immutable, signed, and need no Git credentials on clusters).

Controllers, CRDs and References

The field index for each CRD is assets/schemas/<kind>-<group>-<version>.fields.txt in lowercase (e.g. helmrelease-helm-v2.fields.txt, fluxinstance-fluxcd-v1.fields.txt).

Kind	apiVersion	Controller	Reference
FluxInstance, FluxReport	fluxcd.controlplane.io/v1	flux-operator	`references/flux-operator.md`
ResourceSet, ResourceSetInputProvider	fluxcd.controlplane.io/v1	flux-operator	`references/resourcesets.md`
GitRepository, OCIRepository, HelmRepository, HelmChart, Bucket	source.toolkit.fluxcd.io/v1	source-controller	`references/sources.md`
ExternalArtifact	source.toolkit.fluxcd.io/v1	(3rd-party controllers)	`references/sources.md`
ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	source-watcher	`references/sources.md`
Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomize-controller	`references/kustomization.md`
HelmRelease	helm.toolkit.fluxcd.io/v2	helm-controller	`references/helmrelease.md`
Provider, Alert	notification.toolkit.fluxcd.io/v1beta3	notification-controller	`references/notifications.md`
Receiver	notification.toolkit.fluxcd.io/v1	notification-controller	`references/notifications.md`
ImageRepository, ImagePolicy	image.toolkit.fluxcd.io/v1	image-reflector-controller	`references/image-automation.md`
ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	image-automation-controller	`references/image-automation.md`

Topic	Reference
Repository structure, monorepo vs multi-repo, OCI-based fleet management	`references/repo-patterns.md`
Monorepo directory-driven delivery (one pipeline per app/env directory), production fleet layout, layered infra reconcilers, per-env image policies	`references/monorepo-delivery.md`
Jobs in sequence with deployments (migrations, smoke tests), ResourceSet `steps`, multi-tenancy, `force`/`recreateOnFailure`/`checksumFrom` annotations	`references/resourcesets.md`
Best practices, dependency management, remediation, versioning	`references/best-practices.md`
Gitless GitOps, Flux OCI artifacts, `flux push artifact`, registry-based delivery	`references/gitless-gitops.md`
Gitless image automation (ResourceSet + OCIArtifactTag)	`references/gitless-image-automation.md`
Flux CLI and plugins: `flux schema` discover/validate/extract, local rendering with `flux build` and `flux operator build`, overlay debugging	`references/flux-cli.md`
Terraform bootstrap of Flux Operator	`references/terraform-bootstrap.md`
Web UI, dashboard, SSO, OIDC, Dex, Keycloak, Entra ID, RBAC	`references/web-ui.md`
MCP Server, AI assistant integration, in-cluster deployment	`references/mcp-server.md`

Ordering and Reactivity

Use dependsOn to control reconciliation order (CRDs before CRs, infrastructure before apps):

yaml

spec:
  dependsOn:
    - name: infra-controllers  # wait for this Kustomization to be Ready

ResourceSet dependsOn entries take apiVersion/kind/name/namespace of any resource, plus ready: true or a readyExpr CEL expression for custom readiness. For ordering within a single ResourceSet, use spec.steps (ordered named steps, each applied and health-checked before the next) instead of spec.resources — see references/resourcesets.md.

Controllers poll sources at their interval. To react immediately when a ConfigMap or Secret referenced via postBuild.substituteFrom or valuesFrom changes, label it reconcile.fluxcd.io/watch: Enabled.

Decision Trees

Which Source Type?

Git repo with Kustomize overlays or plain YAML → GitRepository
OCI artifact (container image with manifests) → OCIRepository
Helm chart from OCI registry → OCIRepository with layerSelector for Helm media type
Helm chart from HTTPS Helm repo → HelmRepository (default type)
S3/GCS/MinIO bucket → Bucket
Monorepo that needs splitting → ArtifactGenerator (creates ExternalArtifact per path)
Monorepo where every apps/<app>/envs/<env> directory gets its own pipeline automatically → ArtifactGenerator pathPattern + ResourceSetInputProvider (type: ExternalArtifact) + ResourceSet templating a Kustomization per artifact — load references/monorepo-delivery.md
Helm chart + env-specific values from Git → ArtifactGenerator (composes chart with values overlay)

Kustomization vs HelmRelease vs ResourceSet?

Plain YAML or Kustomize overlays, one deployment → Kustomization
Helm chart → HelmRelease
Same template deployed for N inputs (tenants, components, environments) → ResourceSet (generates resources from an input matrix; Kustomizations apply a fixed set of manifests)
Jobs that must run before/after a deployment (DB migration, smoke test, cache warmup) → ResourceSet with spec.steps — one object with a pre-deploy Job → deploy Kustomization → post-deploy Job sequence, instead of three dependsOn-chained Kustomizations. See references/resourcesets.md (Step-Based Reconciliation).
Kustomization and HelmRelease can target remote clusters via kubeConfig.

Show full SKILL.md (506 more words)Show less

How to Set Up GitOps from Scratch

Install Flux Operator (Helm chart or Terraform) → create a FluxInstance named flux in flux-system with .spec.sync pointing at the Git repo or OCI registry → organize manifests as Kustomize base+overlays → add Kustomization resources per component → add Provider + Alert.

Canonical YAML Patterns

1. GitOps Pipeline (GitRepository + Kustomization)

yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/org/my-app.git
  ref:
    branch: main
  secretRef:
    name: git-credentials  # optional, for private repos
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: ./deploy/production
  prune: true
  wait: true
  timeout: 5m

2. Helm from OCI Registry (Recommended)

yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: cert-manager-chart
  namespace: cert-manager
spec:
  interval: 1h
  url: oci://quay.io/jetstack/charts/cert-manager
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy
  ref:
    semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  interval: 1h
  chartRef:
    kind: OCIRepository
    name: cert-manager-chart
  install:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  upgrade:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  values:
    crds:
      enabled: true

For HTTPS Helm repositories use HelmRepository + HelmRelease with spec.chart.spec (chart, version: "3.x", sourceRef) instead of chartRef — see references/helmrelease.md.

3. FluxInstance with OCI Sync (Gitless GitOps)

yaml

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
  components:
    - source-controller
    - source-watcher
    - kustomize-controller
    - helm-controller
    - notification-controller
  cluster:
    type: kubernetes
    size: medium
    multitenant: true
    tenantDefaultServiceAccount: flux
    networkPolicy: true
  sync:
    kind: OCIRepository
    url: "oci://ghcr.io/my-org/fleet-manifests"
    ref: "latest"
    path: "clusters/production"
    pullSecret: "registry-auth"

4. ResourceSet for Multi-Component Orchestration

A ResourceSet lists spec.inputs (e.g. tenant/environment pairs) and spec.resources templates that reference them with << inputs.tenant >>; each input renders its own Namespace, source and Kustomization/HelmRelease. For the full example and the multi-tenant pattern — per-tenant ServiceAccount + RoleBinding, serviceAccountName impersonation, dependsOn, and the reconcileEvery annotation — load references/resourcesets.md.

5. Image Automation

Git-based — ImageRepository + ImagePolicy + ImageUpdateAutomation commit tag bumps to Git via $imagepolicy YAML markers; requires image-reflector-controller and image-automation-controller. Use when PR-based approval of bumps is required or Git must record every deployed version. Load references/image-automation.md.
Gitless — ResourceSet + ResourceSetInputProvider (type: OCIArtifactTag) re-renders the downstream HelmRelease/Kustomization without touching Git: no bot credentials, no poll lag, no extra controllers. Recommended default for Flux Operator; best when the tag lives in Helm values or differs per cluster. Load references/gitless-image-automation.md.

6. Notifications

Provider + Alert (v1beta3) for outgoing notifications, Receiver (v1) for incoming webhooks. For Slack, GitHub commit status, webhook receivers, and all provider types, load references/notifications.md.

Common Mistakes

Wrong template delimiters:

ResourceSet uses << inputs.field >> — NOT {{ .inputs.field }} or {{ inputs.field }}
Go templates {{ }} are only used in ImageUpdateAutomation .spec.git.commit.messageTemplate

Mutual exclusivity:

HelmRelease: spec.chart.spec and spec.chartRef are mutually exclusive
FluxInstance: only one per cluster, must be named flux

HelmRelease strategy fields:

Install/upgrade strategy is at spec.install.strategy.name and spec.upgrade.strategy.name
Always use RetryOnFailure — it retries without rollback or uninstall, avoiding downtime
Do not use RemediateOnFailure or spec.install.remediation / spec.upgrade.remediation

OCIRepository for Helm charts:

Set layerSelector (mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip", operation: copy) to extract the chart, as in pattern 2.

Jobs managed by a ResourceSet:

Job specs are immutable — annotate the Job with fluxcd.controlplane.io/force: enabled so a changed spec (new image tag) recreates it instead of failing the apply; add fluxcd.controlplane.io/recreateOnFailure: enabled only for idempotent Jobs.
Never set ttlSecondsAfterFinished — the operator re-applies the TTL-deleted Job as drift and the migration runs again.
Set spec.wait: true on a stepped ResourceSet, otherwise the final step is not health-checked.

Post-build substitution pitfalls:

substituteFrom only resolves ConfigMaps/Secrets in the Kustomization's own namespace — copy cluster variables into tenant namespaces with fluxcd.controlplane.io/copyFrom (ResourceSet) rather than referencing flux-system from elsewhere.
Kustomize spec.images[].name must match a plain image reference in the manifests (image: frontend); image rewriting runs at build time, before ${var} substitution.
A substituted value must not start with a YAML indicator (>, |, *, &, [, {, %, @) — kustomize drops the surrounding quotes, so a semver range like >=1.0.0 yields invalid YAML. Use x, 1.x, ~1.2.0, ^1.2.0 or x || >=0.0.0-0.

Drift control — pick the right knob:

Kustomization spec.ignore — exclude specific JSON-pointer fields from drift detection/apply (e.g. HPA replicas). Distinct from the kustomize.toolkit.fluxcd.io/ssa: Ignore annotation, which skips a whole object.
HelmRelease spec.driftDetection.ignore — the HelmRelease equivalent, only active when driftDetection.mode is warn/enabled.

Files

SKILL.md and 38 other files (references, assets) in skills/gitops-knowledge of fluxcd/agent-skills.

SKILL.md
assets/schemas/alert-notification-v1beta3.fields.txt
assets/schemas/artifactgenerator-source-v1beta1.fields.txt
assets/schemas/bucket-source-v1.fields.txt
assets/schemas/externalartifact-source-v1.fields.txt
assets/schemas/fluxinstance-fluxcd-v1.fields.txt
assets/schemas/fluxreport-fluxcd-v1.fields.txt
assets/schemas/gitrepository-source-v1.fields.txt
assets/schemas/helmchart-source-v1.fields.txt
assets/schemas/helmrelease-helm-v2.fields.txt
assets/schemas/helmrepository-source-v1.fields.txt
assets/schemas/imagepolicy-image-v1.fields.txt
assets/schemas/imagerepository-image-v1.fields.txt
assets/schemas/imageupdateautomation-image-v1.fields.txt
assets/schemas/kustomization-kustomize-v1.fields.txt
assets/schemas/ocirepository-source-v1.fields.txt
assets/schemas/provider-notification-v1beta3.fields.txt
assets/schemas/receiver-notification-v1.fields.txt
assets/schemas/resourceset-fluxcd-v1.fields.txt
… and 20 more

Open the folder on GitHubat commit 0d1fa6c

Compare with similar skills

Gitops Knowledge next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Gitops Knowledge compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Gitops Knowledge this skillfluxcd/agent-skills	230	—	~3.8k	Automated safety check: Pass	Apache-2.0	5 days ago
Create Policyharness/harness-skills	115	—	~1.9k	Automated safety check: Pass	Apache-2.0	today
Manage Iacmharness/harness-skills	115	—	~1.6k	Automated safety check: Pass	Apache-2.0	today
Terravision Cloud Diagramspatrickchugh/terravision	1.6k	—	~5.6k	Automated safety check: Notes	AGPL-3.0-only	yesterday
Infra Syncagentic-community/mcp-gateway-registry	962	—	~2.7k	Automated safety check: Pass	Apache-2.0	yesterday
Eks Best Practicesaws-samples/appmod-blueprints	113	—	~5k	Automated safety check: Pass	MIT-0	yesterday

Similar skills

Create Policy
harness/harness-skills
Create OPA governance policies for Harness via MCP. An agent skill from harness/harness-skills.
115 GitHub stars~1.9k tokensUpdated today
DevOps & CloudAuto-check passed
Manage Iacm
harness/harness-skills
Manage Harness Infrastructure as Code Management (IaCM) via MCP.
115 GitHub stars~1.6k tokensUpdated today
DevOps & CloudAuto-check passed
Terravision Cloud Diagrams
patrickchugh/terravision
Draw cloud architecture diagrams for AWS, Azure or GCP with the official provider icon sets, using TerraVision.
1.6k GitHub stars~5.6k tokensUpdated yesterday
DevOps & CloudAuto-check: notes
Infra Sync
agentic-community/mcp-gateway-registry
Keep Terraform and CDK infrastructure in sync. An agent skill from agentic-community/mcp-gateway-registry.
962 GitHub stars~2.7k tokensUpdated yesterday
DevOps & CloudAuto-check passed
Eks Best Practices
aws-samples/appmod-blueprints
Official
Advisory guidance for Amazon EKS architecture and configuration decisions — compute strategy, networking, security, reliability, cost, autoscaling, observability, multi-tenancy, and upgrade planning.
113 GitHub stars~5k tokensUpdated yesterday
DevOps & CloudAuto-check passed
Ksail
devantler-tech/ksail
Use the ksail CLI to spin up and manage Kubernetes clusters (Kind/K3d/Talos/vCluster/KWOK — local via Docker; EKS — cloud via AWS) and GitOps workloads declaratively.
166 GitHub stars~1.1k tokensUpdated today
DevOps & CloudAuto-check passed

More from fluxcd/agent-skills

Gitops Repo Audit
fluxcd/agent-skills
Audit and validate Flux CD GitOps repositories by scanning local repo files (not live clusters) — runs Kubernetes schema validation, detects deprecated Flux APIs, reviews RBAC/multi-tenancy/secrets…
230 GitHub stars~3.8k tokensUpdated 5 days ago
Auto-check passed
Commit Assisted By
fluxcd/agent-skills
Add an Assisted-by: <agent-name/<model-id git trailer to commits made during an AI-assisted coding session.
230 GitHub stars~1.3k tokensUpdated 5 days ago
Auto-check passed
Flux Controller Minor Releases
fluxcd/agent-skills
Run the upstream Flux controller minor release procedure for helm-controller, image-automation-controller, image-reflector-controller, kustomize-controller, notification-controller…
230 GitHub stars~3.9k tokensUpdated 5 days ago
Auto-check passed
Flux Controller Patch Releases
fluxcd/agent-skills
Run the upstream Flux controller patch release procedure for helm-controller, image-automation-controller, image-reflector-controller, kustomize-controller, notification-controller…
230 GitHub stars~4.7k tokensUpdated 5 days ago
Auto-check passed
Gitops Cluster Debug
fluxcd/agent-skills
Debug and troubleshoot Flux CD on live Kubernetes clusters (not local repo files) via the Flux MCP server — inspects Flux resource status, reads controller logs, traces dependency chains, and…
230 GitHub stars~4.2k tokensUpdated 5 days ago
Auto-check passed

Works with

Questions about Gitops Knowledge

What does Gitops Knowledge do?

Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging). Gitops Knowledge is an agent skill from fluxcd/agent-skills. Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging).

When should I use Gitops Knowledge?

Gitops Knowledge fits situations like: users ask about Flux concepts; want manifests for HelmRelease; any Flux resource; needs guidance on GitOps repository structure.

How do I install Gitops Knowledge in Claude Code?

Run `npx skills add fluxcd/agent-skills --skill gitops-knowledge -a claude-code`. Or copy the skill folder (skills/gitops-knowledge in fluxcd/agent-skills) into .claude/skills/gitops-knowledge in your project. Claude Code loads it when a task matches its description.

How do I install Gitops Knowledge in Codex?

Run `npx skills add fluxcd/agent-skills --skill gitops-knowledge -a codex`. Or copy the skill folder (skills/gitops-knowledge in fluxcd/agent-skills) into .agents/skills/gitops-knowledge in your project. Codex loads it when a task matches its description.

Can I use Gitops Knowledge in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add fluxcd/agent-skills --skill gitops-knowledge -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/gitops-knowledge, .gemini/skills/gitops-knowledge, .github/skills/gitops-knowledge and .opencode/skills/gitops-knowledge in your project.

What does Gitops Knowledge need to run?

SKILL.md names no scripts, command-line tools or credentials: Gitops Knowledge is instructions for the agent only.

Does Gitops Knowledge access the network?

SKILL.md names 1 domain. In commands or code: github.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Gitops Knowledge safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Gitops Knowledge use?

Gitops Knowledge is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Gitops Knowledge use?

About 3.8k tokens (SKILL.md is roughly 15k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 56k tokens, read only when the agent opens those files.

What are the alternatives to Gitops Knowledge?

Skills that share tags, products or a category with Gitops Knowledge: Create Policy (harness/harness-skills, 115 stars), Manage Iacm (harness/harness-skills, 115 stars), Terravision Cloud Diagrams (patrickchugh/terravision, 1.6k stars) and Infra Sync (agentic-community/mcp-gateway-registry, 962 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Gitops Knowledge?

fluxcd (a GitHub organization) maintains it in fluxcd/agent-skills, which has 230 GitHub stars. The repository holds 6 skills in this directory. The repository was last updated on October 2, 2026.

Source: fluxcd/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Gitops Knowledge

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Flux CD Knowledge Base

What is Flux

Controllers, CRDs and References

Ordering and Reactivity

Decision Trees

Which Source Type?

Kustomization vs HelmRelease vs ResourceSet?

How to Set Up GitOps from Scratch

Canonical YAML Patterns

1. GitOps Pipeline (GitRepository + Kustomization)

2. Helm from OCI Registry (Recommended)

3. FluxInstance with OCI Sync (Gitless GitOps)

4. ResourceSet for Multi-Component Orchestration

5. Image Automation

6. Notifications

Common Mistakes

Files

Compare with similar skills

Similar skills

More from fluxcd/agent-skills

Related

Questions about Gitops Knowledge