gitops-skills

GitOps Agent Skills

A collection of reusable skills that give AI Agents expertise in Flux CD, Kubernetes, and GitOps best practices for generating manifests, answering Flux questions, auditing repository structure, security, operational readiness, and debugging live cluster installations.

[!NOTE] These are the official AI Skills for Flux CD, developed by the Flux project maintainers. We are looking for users to try them out and provide feedback on accuracy, usefulness, and any gaps when steering Agents through GitOps tasks. If you have suggestions for improvements or new skills, please open an issue.

Install

Using Flux CLI

Install the operator plugin with:

flux plugin install operator

Navigate to your GitOps repository root and run:

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

The Flux Operator CLI verifies the cosign signature (validating that the OCI artifact is published by the Flux team) and extracts the skills in the repo root at .agents/skills.

The --agent flag creates per-skill symlinks from agent-specific directories to the canonical location. If your agent supports the conventional .agents/skills path, you can omit the --agent flag.

To update the skills run flux operator skills update.

Using NPX

Install the skills with Vercel's skills tool:

npx skills add fluxcd/agent-skills

Using Claude Code

For Claude Code, add the marketplace and install the skills with:

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

Using Codex

Add the FluxCD marketplace and install the plugin with:

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

Start a new Codex thread after installation so the skills are discovered.

Using GitHub Copilot

For Copilot CLI, add the FluxCD marketplace and install the plugin with:

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

Prerequisites

The skills in this repository rely on the following tools being available in the environment:

• flux for dry running and manifest generation
• flux-schema for discovering and validating Kubernetes manifests (install with flux plugin install schema)
• kustomize (or kubectl, which embeds kustomize) for building kustomize overlays
• flux-operator-mcp for debugging Flux on live Kubernetes clusters (required by gitops-cluster-debug)

A Brewfile is provided for easy installation of the prerequisites on macOS.

Kubernetes Ecosystem Schema Catalog MCP

The skills are complemented by the Flux Schema Catalog MCP server, which gives the agent access to JSON schemas and field indexes for core Kubernetes, OpenShift and a broad set of Cloud Native projects. The AI Agent uses it to look up the real kinds, field names, types, constraints, when generating or reviewing custom resources.

When installing the skills as a plugin (Claude Code, Copilot or Codex), the schema MCP server is configured automatically. For the other installation methods, it can be added manually. See the schema catalog documentation for more details.

Available Skills

The skills are designed to work together and the agent automatically selects the right one based on context: gitops-knowledge for answering Flux questions and generating manifests, gitops-repo-audit for validating and auditing repository contents, and gitops-cluster-debug for troubleshooting live clusters.

gitops-knowledge

Answers questions about Flux CD and generates up-to-date YAML for all Flux custom resources. Bundled with OpenAPI schemas for every Flux resource and reference documentation covering sources, HelmRelease, Kustomization, ResourceSets, image automation, notifications, repository patterns, and the Flux Operator APIs.

To invoke the skill, use the following 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?