diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index faad9e0..bd7b1ab 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -17,7 +17,7 @@ "websiteURL": "https://docs.redhat.com/en/documentation/red_hat_openshift_gitops" }, "license": "MIT", - "name": "argo-skills", + "name": "openshift-gitops", "repository": "https://github.com/alimobrem/skills-for-argo", "skills": "./skills/", "version": "0.0.1" diff --git a/README.md b/README.md index e0ba201..94665c2 100644 --- a/README.md +++ b/README.md @@ -13,55 +13,64 @@

Agent Skills for Red Hat OpenShift layered products.
- Deep, measured expertise your AI agent can use — starting with OpenShift GitOps - (Argo CD and Argo Rollouts as the operator ships them): generate manifests, audit repos, - debug clusters, tune performance, onboard teams, and run day-2 operations. + Generate manifests, audit repos, debug clusters, tune performance, onboard teams.
+ Every skill measured against an unaided baseline — see Benchmarks.

--- -
-Quick Start +## Install ```shell # Claude Code /plugin marketplace add alimobrem/skills-for-argo /plugin install openshift-gitops@openshift -# Or, for any agent (Codex, Cline, Amp, Antigravity, Cursor, ...) +# Any other agent — Codex, Cline, Amp, Cursor, Antigravity, and 15 more npx skills add alimobrem/skills-for-argo - -# Then try: -# "Audit the current repo for GitOps best practices" -# "Check if Argo CD is healthy on my cluster" -# "Generate an ApplicationSet with git directory generator" ``` -
+Then just describe what you need — skills activate on context, you never name them: -## Install +```text +"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](https://github.com/vercel-labs/skills) CLI — it +reads this repo directly and installs into whichever agent directories it finds.
-Claude Code +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 | ```shell -/plugin marketplace add alimobrem/skills-for-argo -/plugin install openshift-gitops@openshift +brew bundle # installs all of the above on macOS ``` -After install, the `argocd` agent appears in `/agents` and the 6 GitOps skills -auto-trigger based on context. Run `/reload-plugins` if they don't appear immediately. -
-Codex +Codex — manual marketplace entry Add to `$REPO_ROOT/.agents/plugins/marketplace.json` or `~/.agents/plugins/marketplace.json`: ```json { - "name": "argo-skills", + "name": "openshift-gitops", "category": "Developer Tools", "source": { "source": "url", @@ -75,13 +84,13 @@ Add to `$REPO_ROOT/.agents/plugins/marketplace.json` or `~/.agents/plugins/marke } ``` +Or just use `npx skills add` above, which handles Codex too. +
GitHub Copilot -Copy the agent file to your repository: - ```shell mkdir -p .github/copilot cp agents/github-copilot/argocd.agent.md .github/copilot/ @@ -90,49 +99,24 @@ cp agents/github-copilot/argocd.agent.md .github/copilot/
-Prerequisites - -Required: -- `kubectl` or `oc` for Kubernetes/OpenShift cluster interaction - -Optional (enhances capabilities): -- `kustomize` — Kustomize overlay builds -- `kubeconform` — schema validation against Argo CRDs -- `yq` — YAML parsing -- `argocd` — richer Application debugging and sync operations -- `kubectl-argo-rollouts` — Rollout status and promotion +Claude Code notes -Install all on macOS: -```shell -brew bundle -``` +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.
-## Works with - -Skills are plain Markdown with YAML frontmatter, so they are not tied to one agent. - -| How | Agents | Command | -|-----|--------|---------| -| **Any agent** | 20+ including Codex, Cline, Amp, Cursor, Antigravity | `npx skills add alimobrem/skills-for-argo` | -| **Claude Code** | plugin with the bundled `argocd` agent | `/plugin marketplace add alimobrem/skills-for-argo` | - -`npx skills` is the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI. It -reads this repo directly — nothing to publish, and it installs skills into whichever -agent directories it finds. - ## Products Skills live under `skills//`, one plugin per product, so you install only what you run. -| Product | Skills | Status | -|---------|-------:|--------| -| [**gitops**](skills/gitops) — Argo CD, Argo Rollouts | 6 | shipping, benchmarked | -| [**servicemesh**](skills/servicemesh) — Istio | 0 | [open for contributions](docs/adding-a-skill.md) | -| [**serverless**](skills/serverless) — Knative | 0 | [open for contributions](docs/adding-a-skill.md) | -| [**pipelines**](skills/pipelines) — Tekton | 0 | [open for contributions](docs/adding-a-skill.md) | +| Product | Covers | Skills | Status | +|---------|--------|-------:|--------| +| [**gitops**](skills/gitops) | Argo CD, Argo Rollouts | **6** | shipping, benchmarked | +| [**servicemesh**](skills/servicemesh) | Istio | — | [open for contributions](docs/adding-a-skill.md) | +| [**serverless**](skills/serverless) | Knative | — | [open for contributions](docs/adding-a-skill.md) | +| [**pipelines**](skills/pipelines) | Tekton | — | [open for contributions](docs/adding-a-skill.md) | Adding skills for your product? Start with **[docs/adding-a-skill.md](docs/adding-a-skill.md)**. Evals are required — the guide explains the bar and why it is set where it is. @@ -577,15 +561,25 @@ before quoting any of these numbers. The first question most platform teams ask is *"will this let an agent break my cluster?"* -**Every write follows the same protocol, and the agent stops at the gate.** +**Every write follows the same five steps, and the agent stops 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 +> `ArgoCD` CR 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. -| Step | What happens | -|------|--------------| -| **1. Generate** | Produces the manifest or command and shows it in full. Nothing runs. | -| **2. Preview** | `kubectl diff` for updates, `--dry-run=server --validate=strict` for creates. Never `--dry-run=client`, which validates nothing and cannot show what an update changes. | -| **3. Blast radius** | Resolves what *else* the change touches — how many Applications stop reconciling, which tenants share the instance, what gets deleted. A diff shows one object; most Argo CD objects are fan-out points. | -| **4. Confirm** | Asks explicitly. Destructive operations require typing the resource name. | -| **5. Verify** | After applying, checks it actually worked and reports the result. | +**5 · Verify** — after applying, checks it actually worked and reports the result. Read-only work — audits, status checks, backups — skips the gate entirely. diff --git a/skills/gitops/argo-team-onboard/references/onboarding-guide.md b/skills/gitops/argo-team-onboard/references/onboarding-guide.md index f129201..2cce5a0 100644 --- a/skills/gitops/argo-team-onboard/references/onboarding-guide.md +++ b/skills/gitops/argo-team-onboard/references/onboarding-guide.md @@ -36,6 +36,12 @@ templates for every resource, and a post-onboarding validation checklist. ## AppProject Template +> **Sync-window selectors are OR-ed, not AND-ed.** Argo CD: *"If more than one option is +> specified, by default, the enabled options will be OR-ed."* So +> `applications: ['*']` alongside `namespaces: [...]` matches **every Application on the +> instance**, not the intersection — a deny window meant to freeze one tenant freezes +> everyone. Use exactly one selector unless you genuinely want the union. + ```yaml apiVersion: argoproj.io/v1alpha1 kind: AppProject @@ -617,7 +623,6 @@ syncWindows: schedule: '0 8 * * 1-5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off # Mon-Fri 8am UTC duration: 10h # Until 6pm UTC - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: true # ESCAPE HATCH: lets a human sync outside the window @@ -626,7 +631,6 @@ syncWindows: schedule: '0 18 * * 5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off # Friday 6pm UTC duration: 62h # Until Monday 8am UTC - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: false # (default) emergency manual syncs are ALSO blocked ``` diff --git a/skills/gitops/argo-team-onboard/references/onboarding-variants.md b/skills/gitops/argo-team-onboard/references/onboarding-variants.md index aad4046..fe85130 100644 --- a/skills/gitops/argo-team-onboard/references/onboarding-variants.md +++ b/skills/gitops/argo-team-onboard/references/onboarding-variants.md @@ -323,6 +323,12 @@ Delta: add `syncWindows` to the AppProject spec. **Business hours only (production):** +> **Sync-window selectors are OR-ed, not AND-ed.** Argo CD: *"If more than one option is +> specified, by default, the enabled options will be OR-ed."* So +> `applications: ['*']` alongside `namespaces: [...]` matches **every Application on the +> instance**, not the intersection — a deny window meant to freeze one tenant freezes +> everyone. Use exactly one selector unless you genuinely want the union. + ```yaml spec: syncWindows: @@ -330,7 +336,6 @@ spec: schedule: '0 8 * * 1-5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off # Mon-Fri 8am UTC duration: 10h # Until 6pm UTC - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: true # ESCAPE HATCH: lets a human sync outside the window ``` @@ -344,7 +349,6 @@ spec: schedule: '0 18 * * 5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off # Friday 6pm UTC duration: 62h # Until Monday 8am UTC - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: false # (default) emergency manual syncs are ALSO blocked ``` @@ -358,14 +362,12 @@ spec: schedule: '0 8 * * 1-5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off duration: 10h - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: true - kind: deny schedule: '0 18 * * 5' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off duration: 62h - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: false ``` @@ -379,7 +381,6 @@ spec: schedule: '0 2 * * 3' timeZone: UTC # REQUIRED in practice: a bare schedule is evaluated in the controller's timezone, so a window annotated 'UTC' can fire hours off # Wednesday 2am UTC duration: 4h # Until 6am UTC - applications: ['*'] namespaces: ['{{TEAM_NAME}}-prod'] manualSync: true ```