Skip to content

Introducing the Flux CD Agent Skills

The Flux project maintainers have released the official GitOps Agent Skills for Flux CD, and this post walks through what they do and how to use them. The skills give AI agents expertise in Flux, Kubernetes, and GitOps best practices: answering questions with up-to-date knowledge, generating schema-validated manifests, auditing repository structure and security, and troubleshooting live clusters.

Flux CD GitOps Agent Skills

Why Agent Skills for GitOps

Ask a general-purpose AI assistant to write Flux manifests and the weaknesses show quickly. It confidently emits deprecated API versions, invents spec field, or reaches for flux bootstrap when your platform standardized on the Flux Operator. The model's knowledge of the Flux APIs is whatever happened to be current when it was trained, and it has no way to tell a remembered field from an invented one.

Agent skills solve this by packaging expert knowledge that the agent loads on demand. A skill is a set of markdown instructions, reference documents, schemas, and scripts that steer the agent through a task using current, authoritative information instead of frozen training data. The Flux skills bundle curated reference docs written by the maintainers, OpenAPI schemas and executable scripts that ground the agent's claims in deterministic tool output.

The three skills are designed to work together, and the agent picks the right one based on context: gitops-knowledge for questions and manifest generation, gitops-repo-audit for validating and auditing repository contents, and gitops-cluster-debug for troubleshooting live clusters.

gitops-knowledge

This skill turns the agent into a Flux CD and Flux Operator expert. It answers questions about GitOps concepts and generates YAML for all Flux custom resources, from HelmRelease and Kustomization to ResourceSets, image automation, and notifications.

The skill encodes the decision trees a Flux maintainer would walk through: which source type fits which delivery model, when to use a ResourceSet instead of a Kustomization, how to choose between Git-based and Gitless image automation. It also carries the canonical YAML patterns and a list of the mistakes agents make most often, like using Go template delimiters in ResourceSets or setting mutually exclusive HelmRelease fields.

Before generating YAML for any custom resource, the agent reads the bundled OpenAPI schema to verify exact field names, types, and enum values. After writing manifests, it validates them with Flux Schema and fixes any violations before showing you the result. The generate-validate-fix loop means the YAML you get has already passed the same checks the Kubernetes API server would apply.

Example prompts:

What's the recommended GitOps structure for a multi-cluster fleet?

Generate a HelmRelease for oci://ghcr.io/my-org/frontend,
and a Kustomization to deploy it in the staging cluster.

How do I set up preview environments for pull requests with Flux Operator?

The skill works best inside a GitOps repository that contains an AGENTS.md describing your organization's structure, cluster topology, and secret management approach. The agent combines the skill's reference files with the repository context to generate manifests tailored to your setup.

gitops-repo-audit

This skill turns the agent into a GitOps repository auditor. It works entirely on local files (no cluster access needed) and walks through six phases: discovery, manifest validation, API compliance, best practices assessment, security review, and a final report with recommendations prioritized by severity.

Each phase is grounded in deterministic tooling rather than the agent's own reading of the files. Discovery runs flux schema discover to build a structured inventory of directories, resources, and Flux objects. Validation runs flux schema validate on both raw manifests and rendered overlays. API compliance runs flux migrate --dry-run to pinpoint deprecated API versions with exact file paths and line numbers. The best practices and security phases then work from maintainer-written checklists covering RBAC, multi-tenancy, secrets management, source authentication, and supply chain security.

To run a full audit, ask:

Audit the current repo and provide a GitOps report.

In Claude Code, you can also invoke the skill directly with /gitops-repo-audit. Targeted prompts work too: you can validate the repo without a full audit, or audit only the files with changes, which makes the skill useful as a pre-push check during day-to-day work.

For larger setups, the repository includes a Claude Code guide for orchestrating Flux sub-agents that audit multiple repositories (fleet, infra, and apps repos) and aggregate the results into an HTML report.

gitops-cluster-debug

This skill turns the agent into a Flux troubleshooter for live Kubernetes clusters. It connects through the Flux MCP server and follows the same debugging playbooks the maintainers use: check the Flux installation health, trace a failing HelmRelease or Kustomization from its source through to the managed workloads, analyze controller and pod logs, and walk dependency chains to find the actual root cause instead of the symptom.

The skill ships dedicated workflows for the failures users hit most: sources stuck on fetch failed, image automation not committing tag updates, alerts not being delivered, and ResourceSets with failing input providers. The result is a root cause analysis report with the dependency chain, the evidence from status conditions and logs, and prioritized remediation steps.

Example prompts:

Check the Flux installation on my current cluster.

Debug the failing HelmRelease podinfo in the apps namespace.

Troubleshoot the Kustomization flux-system/infra-controllers in the staging cluster.

The MCP server can be configured in Claude Code with:

claude mcp add --scope user --transport stdio flux-operator-mcp \
  --env KUBECONFIG=$HOME/.kube/config \
  -- flux-operator-mcp serve --read-only

With the --read-only flag, the agent can inspect but not mutate the cluster. The MCP server also masks Kubernetes Secrets, so the agent sees only the data key names, never the values.

Measuring the Impact

The skills are developed with an eval harness that runs each scenario with and without the skill, asserting on the correctness of the generated manifests and audit findings. The benchmarks are published in the repository alongside the skill releases.

For the latest release (v0.1.0), the overall results:

Skill Model With Skill Baseline
gitops-knowledge Claude Opus 4.8 121/121 (100%) 87/121 (72%)
gitops-knowledge Claude Sonnet 5 119/121 (98%) 84/121 (69%)
gitops-repo-audit Claude Opus 4.8 73/76 (96%) 54/76 (71%)
gitops-repo-audit Claude Sonnet 5 71/76 (93%) 54/76 (71%)

The gap is widest exactly where you would expect: newer APIs like ResourceSets and preview environments, where the Opus 4.8 baseline scores 33% and the skill brings it to 100%. Even frontier models cannot know APIs that shipped after their training cutoff, and that is precisely what the skills correct.

Getting Started

The recommended installation method is the Flux Operator CLI, which verifies the cosign signature of the OCI artifact, confirming it was published by the Flux team:

flux plugin install operator

Then, from the root of your GitOps repository:

flux operator skills install ghcr.io/fluxcd/agent-skills --agent claude-code

This extracts the skills to .agents/skills and creates per-skill symlinks for the chosen agent. If your agent supports the conventional .agents/skills path, you can omit the --agent flag. To update the skills later, run flux operator skills update.

For Claude Code and Codex you can also install straight from the plugin marketplace:

/plugin marketplace add fluxcd/agent-skills
/plugin install gitops-skills@fluxcd

Or with Vercel's skills tool, which works across agents:

npx skills add fluxcd/agent-skills

The skills rely on a few CLIs being available in the environment: flux, flux-schema (install with flux plugin install schema), kustomize or kubectl, and flux-operator-mcp for the cluster debugging skill. A Brewfile is provided for easy installation on macOS and Linux.

Feedback Welcome

The agent skills are Apache 2.0 licensed and developed in the open at fluxcd/agent-skills. We are looking for users to try them out and report back on accuracy, usefulness, and any gaps when steering agents through GitOps tasks. If you have suggestions for improvements or ideas for new skills, please open an issue on GitHub.