Agent Skills for Red Hat OpenShift layered products.
Generate manifests, audit repos, debug clusters, tune performance, onboard teams.
Every skill measured against an unaided baseline — see Benchmarks.
# Claude Code
/plugin marketplace add alimobrem/skills-for-argo
/plugin install openshift-gitops@openshift
# Any other agent — Codex, Cline, Amp, Cursor, Antigravity, and 15 more
npx skills add alimobrem/skills-for-argoThen just describe what you need — skills activate on context, you never name them:
"Audit this repo for GitOps best practices"
"Why is my Application stuck OutOfSync?"
"Generate an ApplicationSet with a git directory generator"
Skills are plain Markdown with YAML frontmatter, so they are not tied to one agent.
npx skills is the vercel-labs/skills CLI — it
reads this repo directly and installs into whichever agent directories it finds.
Prerequisites
Required — kubectl or oc.
Optional, each unlocking more capability:
| Tool | Adds |
|---|---|
kustomize |
overlay builds during repo audits |
kubeconform |
schema validation against Argo CRDs |
yq |
YAML-aware parsing and duplicate detection |
argocd |
richer Application debugging and sync operations |
kubectl-argo-rollouts |
Rollout status and promotion |
brew bundle # installs all of the above on macOSCodex — manual marketplace entry
Add to $REPO_ROOT/.agents/plugins/marketplace.json or ~/.agents/plugins/marketplace.json:
{
"name": "openshift-gitops",
"category": "Developer Tools",
"source": {
"source": "url",
"url": "https://github.com/alimobrem/skills-for-argo.git",
"ref": "main"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
}
}Or just use npx skills add above, which handles Codex too.
GitHub Copilot
mkdir -p .github/copilot
cp agents/github-copilot/argocd.agent.md .github/copilot/Claude Code notes
After install the argocd agent appears in /agents and the 6 GitOps skills activate on
context. Run /reload-plugins if they do not appear immediately.
Skills live under skills/<product>/, one plugin per product, so you install only what
you run.
| Product | Covers | Skills | Status |
|---|---|---|---|
| gitops | Argo CD, Argo Rollouts | 6 | shipping, benchmarked |
| servicemesh | Istio | — | open for contributions |
| serverless | Knative | — | open for contributions |
| pipelines | Tekton | — | open for contributions |
Adding skills for your product? Start with docs/adding-a-skill.md. Evals are required — the guide explains the bar and why it is set where it is.
Full guide with all example prompts: docs/USER_GUIDE.md
Skills are grouped by product. Expand the one you use.
🔵 GitOps — Argo CD, Argo Rollouts · 6 skills, benchmarked
Scope — Red Hat OpenShift GitOps. These skills cover Argo CD and Argo Rollouts as shipped and supported by the OpenShift GitOps operator, including the operator-managed CRDs (
ArgoCD,RolloutManager,NotificationsConfiguration,NamespaceManagement,ImageUpdater). They work against vanilla Argo CD too, but OpenShift GitOps is the target.Argo Workflows and Argo Events are deliberately out of scope — they are separate upstream projects the operator does not ship, and on OpenShift pipelines are normally OpenShift Pipelines (Tekton). For those, see the Argo Workflows and Argo Events docs.
GitOps Promoter is covered for environment promotion, but is installed separately — it is argoproj-labs, not operator-owned.
Targets Red Hat OpenShift GitOps 1.19+ · Argo CD v2.14+ / v3.x · Argo Rollouts v1.8+. Measured against OpenShift GitOps 1.21.3 / Argo CD v3.4.5.
The agent automatically selects the right skill based on what you ask:
Ask a question ────► argo-knowledge "How do I...?"
Audit a repo ──────► argo-repo-audit "Audit this repo"
Debug a cluster ───► argo-cluster-debug "Why is X failing?"
Make a change ─────► argo-operations "Install / create / promote / upgrade..."
Tune performance ──► argo-performance-tuning "Why is this slow at scale?"
Onboard a team ────► argo-team-onboard "Set up a new team on Argo CD"
You don't need to invoke skills manually — just describe what you need.
Use when you need to understand OpenShift GitOps concepts or generate manifests.
# Generate manifests
Generate a multi-source Application that combines a Helm chart from
oci://registry.example.com/myapp with values from a Git repo.
# Architecture guidance
What's the best way to structure a multi-cluster GitOps repo?
Should I use app-of-apps or ApplicationSet?
# Newer features
How do I set up argocd-agent for 200 edge clusters behind firewalls?
How do I run Applications in any namespace for multi-tenancy?
# OpenShift-specific
Generate an ArgoCD CR for the OpenShift GitOps operator with OAuth and Routes.
Reference docs included
| Topic | Reference |
|---|---|
| Application spec, sync policies, health checks, multi-cluster | applications.md |
| ApplicationSet generators, progressive syncs, templates | applicationsets.md |
| AppProject RBAC, source/destination restrictions, sync windows | app-projects.md |
| Rollout canary/blue-green, traffic management, AnalysisTemplate | rollouts.md |
| Notification services, templates, triggers, subscriptions | notifications.md |
| Image updater annotations, strategies, write-back | image-updater.md |
| Repository patterns (app-of-apps, ApplicationSet, monorepo) | repo-patterns.md |
| Best practices (sync, RBAC, health, secrets) | best-practices.md |
| argocd-agent hub-and-spoke architecture | agent-mode.md |
| Multi-tenancy, apps-in-any-namespace, Autopilot | multi-tenancy.md |
| OpenShift GitOps Operator, ArgoCD CRD, Routes, SCCs, OAuth | openshift.md |
| Operator-only CRDs — RolloutManager, NotificationsConfiguration, NamespaceManagement, ImageUpdater, GitopsService | openshift-gitops-operator.md |
| GitOps Promoter, PromotionStrategy, branch-per-env promotion, commit status gating | gitops-promoter.md |
Use when you want to validate a GitOps repo before deploying or during a review.
# Full audit
Audit the current repo and provide a GitOps report.
# Targeted checks
Check for security issues in my AppProject configurations.
Are there any hardcoded secrets in Helm values?
Do my Applications have proper sync retry configuration?
# Validation only
Just validate YAML syntax and schemas, don't do a full audit.
What it catches:
| Severity | Examples |
|---|---|
| Critical | Wildcard * in AppProject sourceRepos/destinations, plain-text Secrets, hardcoded passwords in Helm values, clusterResourceWhitelist: */* |
| Warning | Missing syncPolicy, targetRevision: HEAD in production, no retry/backoff, missing ignoreDifferences for controller-managed fields |
| Info | Missing ignoreDifferences for HPA-managed replicas, no progressive sync on multi-cluster ApplicationSets |
Use when something is broken or you want a health check.
# Health check
Check if Argo CD is properly installed on my cluster.
# Application issues
Why is my Application podinfo stuck in OutOfSync?
Debug the degraded Application in the production namespace.
# Rollout issues
The canary rollout for frontend is stuck at step 2. Why?
Are my AnalysisTemplates actually testing anything meaningful?
# Multi-tenant review
Compare all ArgoCD instances on this cluster and check for security gaps.
# Deep investigation
Inspect all Rollouts on this cluster and give me a health report.
Review the Argo CD configuration for security concerns.
Use when you want to make changes. Writes are specified to follow a five-step gate: Generate → Preview with a server-side dry-run → Blast radius → Confirm → Verify. The agent stops at Confirm and waits for you.
# Setup
Install Argo CD on my OpenShift cluster using the GitOps operator.
Create an AppProject for the frontend team with restricted access.
Add the staging cluster to Argo CD.
# Deploy
Create an Application for my Helm chart with automated sync.
Create an ApplicationSet with git directory generator and progressive syncs.
Set up Slack notifications for sync failures.
# Promote
Promote the canary rollout frontend in production.
Sync the Application with server-side apply.
Abort the failing rollout and retry.
# Maintain
Upgrade Argo CD to the latest version.
Back up all my Applications and AppProjects to YAML files.
Rotate the Git credentials for the infra repo.
See Safety model for the full protocol.
Use when OpenShift GitOps is slow, resource-hungry, or struggling at scale.
# Repo-server under pressure
Our argocd-repo-server keeps getting OOMKilled every time we push to our
500-application monorepo.
# UI/controller sluggishness
The Argo CD UI feels sluggish and drift detection takes forever with 2,000 apps.
# Multi-cluster scaling
We have 20 clusters registered but only one application-controller pod and
it's maxed out on CPU.
# Timeout errors
Users see "context deadline exceeded" opening an Application with a huge Helm chart.
# Git provider limits
Our GitHub org is rate-limiting us — 500 apps all point at the same repo and branch.
# Reconciliation churn (no real drift)
Our controller CPU is constantly high even though every Application shows
Synced/Healthy — nothing in Git has changed.
Diagnoses the bottleneck first — including whether the controller is reconciling for the
right reasons at all (resource.ignoreResourceUpdatesEnabled, resource.exclusions,
per-Application manifest-generate-paths cache scoping for monorepos) before reaching for
repo-server concurrency, controller processors, sharding (static or Dynamic Cluster
Distribution), or Git rate-limits — then applies the same Generate → Preview → Confirm
safety model as Operations before changing anything live.
Reference docs included
| Topic | Reference |
|---|---|
| Full settings table, per-setting fixes, sharding algorithms, standalone vs. OpenShift GitOps Operator YAML, common mistakes, tuning order of leverage | tuning-settings.md |
Use when you need to onboard app teams onto Argo CD. The skill discovers what each team already has (CI, registry, source type) and generates only the Argo CD pieces — no assumptions about your stack.
Onboarding output is a commit, not a kubectl apply. The tenant boundary —
AppProject, RBAC, namespace, quotas, NetworkPolicies — is GitOps config like anything
else, so the skill writes it to your GitOps repo and hands off to Argo CD to reconcile.
Applying it directly would put the boundary outside Git: invisible in review, missing
from the audit trail, and reverted the next time anything reconciles. The only exception
is a one-time bootstrap when no control loop exists yet, and the skill names it as such.
The recommended model follows Thomas Jungbauer's
project onboarding with GitOps and Helm:
onboarding a tenant means adding one small values.yaml, which a shared onboarding chart
renders and an ApplicationSet discovers. Committing rendered manifests or Kustomize
overlays is also supported.
# Single team onboarding
Onboard the payments team. They use Kustomize, deploy from
https://github.com/acme/payments.git, need dev/staging/prod namespaces.
# Helm-based team
Onboard analytics — they deploy a Helm chart from OCI registry
oci://registry.acme.com/charts/analytics with values in a separate config repo.
# Self-service at scale
Set up self-service onboarding so teams can add themselves via PR.
# Multi-environment with promotion
Onboard the checkout team with gitops-promoter gating dev → staging → prod.
Production should require manual approval.
What it generates:
| Resource | When | Why |
|---|---|---|
| AppProject | Always | Security boundary — scoped sourceRepos, destinations, RBAC |
| Application | Always | Points to team's repo with correct source type (Helm/Kustomize/directory) |
| RBAC role | Always | Project-scoped permissions for team's SSO group |
| Namespace | Always | With Pod Security Standards (enforce: restricted) and monitoring labels |
| NetworkPolicies | Always | Default-deny egress (with DNS allowed) plus router, monitoring, and same-namespace ingress — without these the namespace is open to every pod on the cluster |
| ResourceQuota + LimitRange | If needed | Capacity limits, via t-shirt size or explicit values |
| PromotionStrategy | If multi-env | Branch-per-environment promotion with health gates |
| ApplicationSet | If self-service | Per-tenant values discovered by a **/values.yaml git generator |
What it refuses:
| Request | Response |
|---|---|
sourceRepos: '*' |
Lists repos explicitly — wildcards defeat multi-tenancy |
clusterResourceWhitelist: '*/*' |
Scopes to specific CRD groups needed |
exec permission |
Redirects to kubectl exec with scoped RBAC |
| Hardcoded secrets | References ExternalSecret or SealedSecret patterns |
| "Just apply it to the cluster" | Explains the drift cost and offers the commit path; proceeds only if it's a genuine bootstrap, and commits the same manifests alongside |
Reference docs included
| Topic | Reference |
|---|---|
| Recommended model — per-tenant values + onboarding chart, discovery ApplicationSet, t-shirt sizes, default NetworkPolicies, Pod Security Standards, two-instance split | gitops-onboarding.md |
| What gets created, AppProject/Application/RBAC templates, validation checklist | onboarding-guide.md |
| Self-service via ApplicationSet, PR workflow, guard rails | self-service-pattern.md |
| Helm/Kustomize/directory variants, Rollouts, notifications, sync windows, promoter | onboarding-variants.md |
🟣 Service Mesh — Istio · no skills yet
No Service Mesh skills have been contributed yet. Likely first candidates:
- Sidecar injection — why a pod has no proxy, namespace labels vs the webhook
- Traffic — VirtualService/DestinationRule precedence, mTLS PeerAuthentication modes
- Diagnosing 503s between workloads, and telemetry that stops arriving
If you work on Service Mesh, this is an open area — see
skills/servicemesh/ and docs/adding-a-skill.md.
Evals are required; the guide explains the bar and why it is set there.
🟢 Serverless — Knative Serving & Eventing · no skills yet
No Serverless skills have been contributed yet. Likely first candidates:
- Serving — Revisions stuck in NotReady, traffic splitting, scale-to-zero and cold starts
- Eventing — Broker/Trigger wiring, Channel delivery, dead-letter sinks, source health
If you work on Serverless, this is an open area — see
skills/serverless/ and docs/adding-a-skill.md.
Evals are required; the guide explains the bar and why it is set there.
🟡 Pipelines — Tekton · no skills yet
No Pipelines skills have been contributed yet. Likely first candidates:
- PipelineRun/TaskRun failure triage — step exit codes, init-container ordering
- Workspaces, results passing between tasks, matrix fan-out
- Triggers — EventListener, TriggerBinding and TriggerTemplate not firing
If you work on Pipelines, this is an open area — see
skills/pipelines/ and docs/adding-a-skill.md.
Evals are required; the guide explains the bar and why it is set there.
A skill is a Markdown file with YAML frontmatter. No runtime, no service, no daemon.
skills/gitops/argo-cluster-debug/
├── SKILL.md # always in context once the skill activates — kept short
├── references/ # loaded only when the workflow calls for them
└── scripts/ # deterministic checks the agent runs instead of improvising
The agent picks a skill by matching your request against its description, so you never
invoke one by name — you describe the problem and the right expertise loads. Reference
files stay out of context until needed, which is why a skill can carry hundreds of lines
of operator-specific detail without consuming the window.
Where being exactly right matters, the skill runs a script rather than describing a
procedure. A documented command can be followed loosely; scripts/validate.sh cannot.
Every skill in this repo is measured against an unaided baseline — same model, same
prompts, same live cluster, no access to skills/. Graded blind: the grader sees
"Condition A" and "Condition B" and is not told which is which.
That bar applies to every product, not just the one that has skills today. A skill with no measured baseline is a guess, and this repo does not publish guesses — including when the answer is unflattering.
🔵 GitOps — 6 skills, 587 expectations per condition
| Skill | with-skill | baseline | delta | |
|---|---|---|---|---|
argo-performance-tuning |
96.7% | 64.0% | +32.7 | |
argo-repo-audit |
95.3% | 79.4% | +15.9 | |
argo-operations |
96.4% | 81.6% | +14.8 | |
argo-cluster-debug |
99.2% | 89.3% | +9.8 | |
argo-team-onboard |
89.4% | 84.6% | +4.8 | unresolved |
argo-knowledge |
98.5% | 93.9% | +4.5 | unresolved |
| Weighted overall | 95.8% | 82.2% | +13.6 |
The delta tracks how product-specific a skill is. Performance tuning — exact setting names, defaults the operator silently overrides, which CR field actually wins — gains most. General Argo CD knowledge the model already has gains least.
Treat direction as reliable and magnitude as not. Re-running one suite unchanged, on the same cluster, moved its delta from +4.9 to +9.8 — so anything under ~5 points is marked unresolved above rather than claimed as a win, and even the large numbers are worth reading as "clearly helps", not as a measurement. The methodology page has the variance data, and the cases where fixing our own evals lowered a published score.
🟣 Service Mesh · 🟢 Serverless · 🟡 Pipelines — not yet measured
No skills yet, so nothing to measure. When they land they are held to the same bar: a strong unaided baseline on the same prompts, blind grading, per-expectation scoring with evidence, and the numbers published whichever way they come out.
See docs/adding-a-skill.md for what that involves.
→ Methodology, grader-variance analysis, and caveats — read before quoting any of these numbers.
The first question most platform teams ask is "will this let an agent break my cluster?"
The honest answer first: these skills are instructions, not a sandbox. They tell the
agent to stop and ask before writing, and in measured runs it does. But a Markdown
instruction is followed most of the time, not always — we have a run where a
documented step was skipped, and the eval caught it. The guarantee you can actually rely
on is the one outside this repo: the agent can do nothing your kubeconfig cannot.
Scope its RBAC to what you are willing to let it change, and treat everything below as
defence in depth rather than the perimeter.
With that said — every write is specified to follow the same five steps, stopping at step 4.
1 · Generate — produces the manifest or command and shows it in full. Nothing runs.
2 · Preview — kubectl diff for an update, --dry-run=server --validate=strict for a
create.
Never
--dry-run=client. It validates nothing, and for an update it only echoes your input back — it cannot show what would change.
3 · Blast radius — resolves what else the change touches.
A diff shows one object. Most Argo CD objects are fan-out points: a one-field edit to an
ArgoCDCR restarts components that every Application on the instance depends on. This step names how many Applications stop reconciling, which tenants share the instance, and what gets deleted.
4 · Confirm — asks explicitly, and waits. Destructive operations require typing the resource name.
5 · Verify — after applying, checks it actually worked and reports the result.
Read-only work — audits, status checks, backups — skips the gate entirely.
Recommendations carry impact too, not just urgency. A skill that tells you to raise a memory limit also tells you that doing so restarts the server and interrupts everyone on that instance. "How soon" is the easy half; "what else moves" is the half you cannot work out from the recommendation alone.
BLOCKER — Delete Rollout/openshift-gitops/example (no containers; hot-loops the controller)
Impact: argo-rollouts controller only. The Rollout is invalid so nothing runs from
it; no workload is affected. Controller restarts once.
Three skills (repo-audit, cluster-debug, performance-tuning in diagnosis mode)
contain no write operations at all, so for those the gate never has to fire. If you want
that enforced rather than specified, run the agent with a read-only kubeconfig — the
skills behave identically and the question stops being a matter of trust.
The skills send nothing anywhere. They are inert Markdown and shell scripts in your checkout — there is no telemetry, no callback, no account.
Be clear about what your agent does, though: when it reads cluster state to answer a question, that output becomes part of the conversation with whichever model you are using. That is a property of using an AI coding agent at all, not of these skills, but it is worth knowing before pointing one at a production cluster.
Practical consequences:
- Three skills (
repo-audit,cluster-debug, andperformance-tuningwhile diagnosing) specify only read operations — no create, apply, patch or delete anywhere in them. That is a property of the instructions, not an enforced sandbox; see Safety model. - The agent acts with your credentials and can do nothing your
kubeconfigcannot. This is the only hard limit in the list, and it is the one worth configuring. repo-auditrunskubeconformwith-skip=Secret, so Secret contents are not sent through schema validation.repo-auditreports credential locations, not values. It runsscan-credentials.sh, which prints file, line, key name and value length — enough to triage and to find the string yourself, not enough to use it. This replaced a documentedgrepthat printed whole matching lines; an audit run put a decoded username and password into the transcript before it was fixed. The scanner also separates real plaintext from SOPS/SealedSecret ciphertext and from values marked# notsecretorEXAMPLE-.- That is a property of the script, not a guarantee about the agent. The skill
instructs it never to
cata Secret orbase64 -da value, and the scanner leaks nothing by construction — but an agent asked point-blank to show a secret can still read the file. Audit a repo holding live credentials with the same care you would give to opening that file.
New skills — including for a product not listed above — are welcome. Read docs/adding-a-skill.md first: it covers the eval bar, baselines, fixtures, and the guards CI enforces. CONTRIBUTING.md covers the mechanics — branches, commits, review.
Development
# Install prerequisites (macOS)
brew bundle
# Download Argo CRD schemas for validation (13 schemas, every in-scope kind)
make download-schemas
# Checks — all of these also run in CI
make test-discover # discovery script against the test fixtures
make test-validate # YAML syntax, schema validation, kustomize builds
make test-registration # every skill registered in manifests, agent, banner, README, CI
make test-expectations # eval expectations' field paths resolve against the CRD schemas
# Evals
make eval # all six skills
make eval-knowledge # no cluster needed
make eval-repo-audit # no cluster needed
make eval-cluster-debug # needs a live cluster
make eval-operations # needs a live cluster
make eval-performance-tuning # needs a live cluster
make eval-team-onboard # needs a live clusterTwo guards worth knowing about, because they catch the mistakes that actually happened here:
make test-registration— a new skill cannot be added without being wired into the marketplace manifest, agent definition, Makefile eval targets, banner, README and eval workflow. The banner silently lagged two skills behind before this existed.make test-expectations— resolves everyspec.*path asserted in an eval against the committed CRD schemas. Three expectations were found grading for manifests the API server rejects or prunes; this stops that recurring.
See AGENTS.md for the repo layout, skill conventions, and eval runner instructions.
This is a community project. It is not a Red Hat product and carries no Red Hat support. There is no SLA, no guaranteed response, and no entitlement attached to it.
- Questions, bugs and feature requests: open a GitHub issue.
- Contributions are welcome — see docs/adding-a-skill.md.
- Fixes land on a best-effort basis, by whoever has time.
Using these skills does not affect the support status of your OpenShift or OpenShift GitOps subscription. They generate manifests and run read-only commands against your cluster; nothing here modifies a supported component's configuration without you approving the change first.
For supported OpenShift GitOps guidance, use Red Hat documentation and a support case.
This project follows the Contributor Covenant Code of Conduct.
See SECURITY.md for reporting vulnerabilities.