From e8db55692348773cd6899947f9c6555f6914f77a Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Tue, 21 Apr 2026 13:51:19 +0530 Subject: [PATCH 1/2] feat: improve skill scores for agent-skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix commit-assisted-by description validation failure (XML-like angle brackets in frontmatter) — score jumps from 17% to 90% - Improve gitops-knowledge content: trim verbose conceptual sections, add validation checkpoints to setup workflow, add schema validation feedback loop — score rises from 89% to 94% - Convert all 5 skill descriptions from YAML block scalar (>) to quoted strings for frontmatter compliance - Trim reconciliation loop and "What is Flux" sections in gitops-knowledge to reduce file size toward the ~15KB guideline | Skill | Before | After | Change | |--------------------------------|--------|-------|--------| | commit-assisted-by | 17% | 90% | +73% | | gitops-knowledge | 89% | 94% | +5% | | gitops-cluster-debug | 94% | 94% | 0% | | gitops-repo-audit | 94% | 94% | 0% | | flux-controller-patch-releases | 97% | 97% | 0% | --- internal/skills/commit-assisted-by/SKILL.md | 7 +--- .../flux-controller-patch-releases/SKILL.md | 8 +--- skills/gitops-cluster-debug/SKILL.md | 7 +--- skills/gitops-knowledge/SKILL.md | 41 +++++++------------ skills/gitops-repo-audit/SKILL.md | 6 +-- 5 files changed, 18 insertions(+), 51 deletions(-) diff --git a/internal/skills/commit-assisted-by/SKILL.md b/internal/skills/commit-assisted-by/SKILL.md index 5570273..550e881 100644 --- a/internal/skills/commit-assisted-by/SKILL.md +++ b/internal/skills/commit-assisted-by/SKILL.md @@ -1,11 +1,6 @@ --- name: commit-assisted-by -description: > - Add an `Assisted-by: /` git trailer to commits made during an AI-assisted coding - session. Trigger on any `git commit` activity visible in the session — either commits you make yourself, - or commits the user makes outside your tool calls that surface in the conversation — even without an - explicit request. Also trigger when the user explicitly asks to tag existing commits in a branch (e.g. - "add assisted-by to commits in this branch"). +description: "Add an Assisted-by git trailer (agent-name/model-id) to commits made during an AI-assisted coding session. Trigger on any git commit activity visible in the session — either commits you make yourself, or commits the user makes outside your tool calls that surface in the conversation — even without an explicit request. Also trigger when the user explicitly asks to tag existing commits in a branch (e.g. 'add assisted-by to commits in this branch')." license: Apache-2.0 allowed-tools: Bash(*/safety-check.sh) Bash(git commit:*) Bash(git log:*) --- diff --git a/internal/skills/flux-controller-patch-releases/SKILL.md b/internal/skills/flux-controller-patch-releases/SKILL.md index 6c594e7..c7f141b 100644 --- a/internal/skills/flux-controller-patch-releases/SKILL.md +++ b/internal/skills/flux-controller-patch-releases/SKILL.md @@ -1,12 +1,6 @@ --- name: flux-controller-patch-releases -description: > - Run the upstream Flux controller patch release procedure for helm-controller, - image-automation-controller, image-reflector-controller, kustomize-controller, - notification-controller, source-controller, and source-watcher. Use when - preparing a new controller patch release from a release series branch, - drafting changelog entries, tagging releases, and opening the follow-up - changelog PRs back to main. +description: "Run the upstream Flux controller patch release procedure for helm-controller, image-automation-controller, image-reflector-controller, kustomize-controller, notification-controller, source-controller, and source-watcher. Use when preparing a new controller patch release from a release series branch, drafting changelog entries, tagging releases, and opening the follow-up changelog PRs back to main." license: Apache-2.0 --- diff --git a/skills/gitops-cluster-debug/SKILL.md b/skills/gitops-cluster-debug/SKILL.md index 20ed94c..363dd1e 100644 --- a/skills/gitops-cluster-debug/SKILL.md +++ b/skills/gitops-cluster-debug/SKILL.md @@ -1,11 +1,6 @@ --- name: gitops-cluster-debug -description: > - Debug and troubleshoot Flux CD on live Kubernetes clusters (not local repo files) via the Flux MCP - server — inspects Flux resource status, reads controller logs, traces dependency chains, and performs - installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a - cluster, reconciliation errors, controller issues, artifact pull failures, or need live cluster - Flux Operator troubleshooting. +description: "Debug and troubleshoot Flux CD on live Kubernetes clusters (not local repo files) via the Flux MCP server — inspects Flux resource status, reads controller logs, traces dependency chains, and performs installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a cluster, reconciliation errors, controller issues, artifact pull failures, or need live cluster Flux Operator troubleshooting." license: Apache-2.0 compatibility: Requires flux-operator-mcp --- diff --git a/skills/gitops-knowledge/SKILL.md b/skills/gitops-knowledge/SKILL.md index b1b0c46..1a557d0 100644 --- a/skills/gitops-knowledge/SKILL.md +++ b/skills/gitops-knowledge/SKILL.md @@ -1,12 +1,6 @@ --- name: gitops-knowledge -description: > - Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML - for all Flux CRDs (not repo auditing or live cluster debugging). Use when users ask about - Flux concepts, want manifests for HelmRelease, Kustomization, GitRepository, OCIRepository, - ResourceSet, FluxInstance, or any Flux resource. When user needs guidance on GitOps repository - structure, bootstrap Flux with Terraform, multi-tenancy, OCI-based delivery, image tag automation, - drift detection, preview environments, notifications, or the Flux Web UI and MCP Server. +description: "Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging). Use when users ask about Flux concepts, want manifests for HelmRelease, Kustomization, GitRepository, OCIRepository, ResourceSet, FluxInstance, or any Flux resource. When user needs guidance on GitOps repository structure, bootstrap Flux with Terraform, multi-tenancy, OCI-based delivery, image tag automation, drift detection, preview environments, notifications, or the Flux Web UI and MCP Server." license: Apache-2.0 --- @@ -17,16 +11,14 @@ to answer questions accurately, generate correct YAML manifests, and explain Flu **Rules:** - Always use the exact apiVersion/kind combinations from the CRD table below. Never invent API versions. -- Before generating YAML for any CRD, read its OpenAPI schema from `assets/schemas/` to verify field names, types, and enum values. +- Before generating YAML for any CRD, read its OpenAPI schema from `assets/schemas/` to verify field names, types, and enum values. After generating, validate the output against the schema — if fields don't match, correct and re-validate before presenting to the user. - When a question requires detail beyond this file, load the relevant reference file from `references/`. - Prefer Flux Operator (FluxInstance) for cluster setup. Do not reference `flux bootstrap` or legacy `gotk-*` files. ## What is Flux -Flux is a set of Kubernetes controllers that implement GitOps — the practice of using Git -(or OCI registries) as the source of truth for declarative infrastructure and applications. -Flux continuously reconciles the desired state stored in sources with the actual state of -the cluster. +Flux is a set of Kubernetes controllers that continuously reconcile desired state from sources +(Git, OCI, Helm, S3) with live cluster state. **Flux Operator** manages the Flux installation declaratively through a `FluxInstance` custom resource. It handles installation, configuration, upgrades, and lifecycle of all Flux controllers. @@ -95,17 +87,10 @@ Namespaces, Sources, Kustomizations, HelmReleases, RBAC, ... ### Reconciliation Loop -Flux controllers run a continuous reconciliation loop: - -1. **Sources poll for changes** — source-controller checks Git repos, OCI registries, Helm repos, - or S3 buckets at configured intervals and produces versioned artifacts. -2. **Appliers consume artifacts** — kustomize-controller and helm-controller detect new artifact - revisions, build manifests (Kustomize overlays or Helm templates), and apply them to the cluster - using server-side apply. -3. **Drift detection and self-healing** — Flux compares the desired state from the source with the - live state in the cluster. When drift is detected, Flux corrects it automatically (if enabled). -4. **Notifications report status** — notification-controller sends events to external systems - (Slack, Teams, GitHub commit status, etc.) based on Alert rules. +1. **Sources poll** — source-controller fetches from Git/OCI/Helm/S3 at configured intervals, producing versioned artifacts. +2. **Appliers consume** — kustomize-controller and helm-controller detect new revisions, build manifests, and apply via server-side apply. +3. **Drift correction** — Flux detects and auto-corrects drift between desired and live state (if enabled). +4. **Notifications** — notification-controller sends events to external systems based on Alert rules. ### Dependency Ordering @@ -172,10 +157,12 @@ references it via `postBuild.substituteFrom` or `valuesFrom` will reconcile imme 1. Install Flux Operator (Helm chart or Terraform) 2. Create a `FluxInstance` named `flux` in the `flux-system` namespace -3. Configure `.spec.sync` to point to your Git repo or OCI registry -4. Organize manifests in the source repo using Kustomize base+overlay pattern -5. Create `Kustomization` resources to apply manifests from the source -6. Add `Provider` + `Alert` for notifications +3. **Verify**: `kubectl get fluxinstance flux -n flux-system` — confirm `Ready: True` before proceeding +4. Configure `.spec.sync` to point to your Git repo or OCI registry +5. Organize manifests in the source repo using Kustomize base+overlay pattern +6. Create `Kustomization` resources to apply manifests from the source +7. **Verify**: `kubectl get kustomizations -n flux-system` — confirm all show `Ready: True` +8. Add `Provider` + `Alert` for notifications ## Canonical YAML Patterns diff --git a/skills/gitops-repo-audit/SKILL.md b/skills/gitops-repo-audit/SKILL.md index 012bad3..8f05012 100644 --- a/skills/gitops-repo-audit/SKILL.md +++ b/skills/gitops-repo-audit/SKILL.md @@ -1,10 +1,6 @@ --- name: gitops-repo-audit -description: > - Audit and validate Flux CD GitOps repositories by scanning local repo files (not live clusters) — - runs Kubernetes schema validation, detects deprecated Flux APIs, reviews RBAC/multi-tenancy/secrets - management, and produces a prioritized GitOps report. Use when users ask to audit, analyze, - validate, review, or security-check a GitOps repo. +description: "Audit and validate Flux CD GitOps repositories by scanning local repo files (not live clusters) — runs Kubernetes schema validation, detects deprecated Flux APIs, reviews RBAC/multi-tenancy/secrets management, and produces a prioritized GitOps report. Use when users ask to audit, analyze, validate, review, or security-check a GitOps repo." license: Apache-2.0 compatibility: Requires awk, git, kustomize, kubeconform, flux, yq --- From 1cf3b81f777ccc292412432f7c3a8efa7e1f5647 Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Tue, 21 Apr 2026 13:52:17 +0530 Subject: [PATCH 2/2] ci: add Tessl skill review workflow for SKILL.md PRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add .github/workflows/skill-review.yml that runs tesslio/skill-review on every PR touching SKILL.md files. Posts scores as a single PR comment using only GITHUB_TOKEN — no extra accounts needed. Non-blocking by default (fail-threshold: 0). --- .github/workflows/skill-review.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/skill-review.yml diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml new file mode 100644 index 0000000..aee21d6 --- /dev/null +++ b/.github/workflows/skill-review.yml @@ -0,0 +1,22 @@ +# Tessl Skill Review — runs on PRs that change any SKILL.md; posts scores as one PR comment. +# Docs: https://github.com/tesslio/skill-review +name: Tessl Skill Review + +on: + pull_request: + branches: [main] + paths: + - "**/SKILL.md" + +jobs: + review: + runs-on: ubuntu-latest + permissions: + pull-requests: write + contents: read + steps: + - uses: actions/checkout@v4 + - uses: tesslio/skill-review@main + # Optional quality gate (off by default — do not enable unless user asked): + # with: + # fail-threshold: 70