gitops-cluster-debug

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, image automation not updating tags, alerts or webhooks not being delivered, or need live cluster Flux Operator troubleshooting.

Quality

93%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

87%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable and well-organized with strong progressive disclosure via real bundle files, but the destructive manifest-apply path lacks an explicit validation feedback loop, capping workflow clarity.

Suggestions

Add an explicit validate-after-apply checkpoint (e.g. re-fetch the resource and confirm Ready/status after apply_kubernetes_manifest) so the destructive operation has a feedback loop.

Tighten the repeated 'Call get_flux_instance to check the ... controller deployment status and the apiVersion of the ... kind' opener shared across workflows 2–5 by referencing a shared helper step.

Trim the role-framing opening paragraph ('You are a Flux cluster debugger specialized in...') since the description frontmatter already establishes the skill's purpose.

Dimension	Reasoning	Score
Conciseness	Dense with actionable specifics (tool names, field paths, grep commands) and assumes Claude's competence without explaining Flux/Kubernetes basics; the role-framing intro and repeated 'Call get_flux_instance' patterns add minor bulk but each line earns its place covering distinct cases.	3 / 3
Actionability	Fully executable guidance throughout — specific MCP tool names, exact field paths (e.g. '.spec.git.push.branch', '.spec.eventSources'), concrete grep commands, and named status conditions to check.	3 / 3
Workflow Clarity	Eight clearly numbered workflows with implicit per-step verification (check Ready, analyze status), but the one destructive operation (applying manifests) has only a guardrail and no explicit validate-after-apply feedback loop, capping destructive-operation workflow clarity per the rubric.	2 / 3
Progressive Disclosure	Well-structured overview with one-level-deep, clearly signaled references — a CRD table linking to per-kind field index files in assets/schemas/ and a 'Loading References' section pointing to flux-crds.md and troubleshooting.md, with inline references from workflows.	3 / 3
	Total	11 / 12 Passed

Description

100%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concrete, trigger-rich, and complete, answering both what the skill does and when to use it with explicit natural-language triggers. It is clearly distinguishable from generic Kubernetes or Git skills.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('inspects Flux resource status, reads controller logs, traces dependency chains, and performs installation health checks') rather than vague language.	3 / 3
Completeness	Explicitly answers both what (debug/troubleshoot Flux CD via the MCP server with listed actions) and when ('Use when users report...'), with an explicit 'Use when' trigger clause.	3 / 3
Trigger Term Quality	Covers natural terms users would say — 'failing, stuck, or not-ready Flux resources', 'reconciliation errors', 'artifact pull failures', 'image automation not updating tags', 'alerts or webhooks not being delivered'.	3 / 3
Distinctiveness Conflict Risk	Narrow, clearly scoped niche (Flux CD on live Kubernetes clusters via the Flux MCP server) with distinct triggers unlikely to overlap with unrelated skills.	3 / 3
	Total	12 / 12 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 19 deeper-than-1-level	Warning
referenced_paths_exist	Referenced path issues: 20 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: fluxcd/agent-skills
Path: skills/gitops-cluster-debug/SKILL.md
Commit: 2f9e4f8

Reviewed: 9 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.