https://github.com/fluxcd/agent-skills
Skills to transform AI Agents into GitOps Engineers
https://github.com/fluxcd/agent-skills
agent-skills ai-agents fluxcd gitops skills
Last synced: about 2 months ago
JSON representation
Skills to transform AI Agents into GitOps Engineers
- Host: GitHub
- URL: https://github.com/fluxcd/agent-skills
- Owner: fluxcd
- License: apache-2.0
- Created: 2026-02-21T14:34:00.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-15T19:12:57.000Z (3 months ago)
- Last Synced: 2026-03-16T07:30:53.642Z (3 months ago)
- Topics: agent-skills, ai-agents, fluxcd, gitops, skills
- Language: Shell
- Homepage: https://fluxcd.io
- Size: 255 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# GitOps Agent Skills
[](https://github.com/fluxcd/agent-skills/releases)
[](https://github.com/fluxcd/agent-skills/blob/main/LICENSE)
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](https://github.com/fluxcd/agent-skills/issues/new).
## Install
### Using Flux Operator CLI
Navigate to your GitOps repository root and run:
```shell
flux-operator skills install ghcr.io/fluxcd/agent-skills --agent claude-code
```
The [Flux Operator](https://fluxoperator.dev/) 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:
```shell
npx skills add fluxcd/agent-skills
```
### Using Claude Code
For Claude Code, add the marketplace and install the skills with:
```shell
/plugin marketplace add fluxcd/agent-skills
/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
- `awk` for text processing and data extraction
- `yq` for YAML parsing and validation
- `kustomize` for building kustomize overlays
- `kubeconform` for validating Kubernetes manifests against OpenAPI schemas
- `flux-operator-mcp` for debugging Flux on live Kubernetes clusters (required by `gitops-cluster-debug`)
A [Brewfile](https://raw.githubusercontent.com/fluxcd/agent-skills/refs/heads/main/Brewfile) is provided for easy installation of the prerequisites on macOS.
## 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:
```text
What's the recommended GitOps structure for a multi-cluster fleet?
```
```text
Generate a HelmRelease for oci://ghcr.io/my-org/frontend,
and a Kustomization to deploy it in the staging cluster.
```
```text
How do I set up preview environments for pull requests with Flux Operator?
```
This skill works best in the context of a GitOps repository that contains an `AGENTS.md`
or `CLAUDE.md` with details about 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.
> [!NOTE]
> Check the [Claude Code Guide](docs/claude-agent-setup.md) for how to orchestrate Flux CD sub-agents and generate audit reports in HTML format.
### gitops-repo-audit
Audits Flux GitOps repositories for structure, security, and operational best practices.
Validates manifests against OpenAPI schemas, detects deprecated API versions,
reviews secrets management, source authentication, RBAC and multi-tenancy configuration,
and generates a structured report with prioritized recommendations.
To invoke the skill, use the following prompt:
```text
Audit the current repo and provide a GitOps report.
```
In Claude Code, you can also invoke the skill directly with `/gitops-repo-audit`.
To run only the manifest validation phase, use:
```text
Validate my repo without auditing it.
```
This prompt can be used when changes have been made to the repository,
and you want to re-run the validation checks without performing a full audit.
You can also use the skill to audit only the files with changes:
```text
Run a GitOps audit only on the files with changes.
```
### gitops-cluster-debug
Debugs and troubleshoots Flux CD on live Kubernetes clusters using the
[Flux MCP](https://fluxoperator.dev/mcp-server/) server. Inspects Flux installation health, diagnoses
HelmRelease and Kustomization failures, analyzes pod logs and traces dependency chains.
To invoke the skill, use the following prompts:
```text
Check the Flux installation on my current cluster.
```
```text
Debug the failing HelmRelease podinfo in the apps namespace.
```
```text
Troubleshoot the Kustomization flux-system/infra-controllers in the staging cluster.
```
The `flux-operator-mcp` server can be configured in Claude Code with:
```bash
claude mcp add --scope project --transport stdio flux-operator-mcp \
--env KUBECONFIG=$HOME/.kube/config \
-- flux-operator-mcp serve --read-only
```
Note that the `--read-only` flag will prevent the Agent from making any changes to the cluster.
The MCP server masks Kubernetes Secrets, the Agent receives only the data key names without values.
## 3rd-Party Indexing
The Flux skills are indexed by various 3rd-party services:
- [tessl.io/registry/skills/github/fluxcd/agent-skills](https://tessl.io/registry/skills/github/fluxcd/agent-skills)
- [skills.sh/fluxcd/agent-skills](https://skills.sh/fluxcd/agent-skills)