CtrlK
BlogDocsLog inGet started
Tessl Logo

break-fix-troubleshooting

Diagnose caddy-security deployment and runtime failures from configs, logs, versions, and HTTP evidence. Use for focused fixes, unresolved support handoffs, or preparing break-fix issue reports.

67

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

75%Weight 40%Scale 1-5

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

A well-engineered troubleshooting body: an explicit workflow with validation and safety constraints, symptom-specific checklists dense with repo-specific knowledge Claude cannot infer, and a fully specified issue-report deliverable. The main improvements are architectural rather than substantive — move the detailed OIDC consent procedure into the already-referenced reference files, and make validation commands concrete per failure class instead of contingent on local context.

Suggestions

Move the detailed OIDC consent POST / Referrer-Policy procedure out of Symptom Checks and into the already-linked reference (oidc-provider.md or a dedicated break-fix reference), leaving only a one-line pointer and trigger conditions in SKILL.md.

Replace the contingent validation instruction in step 6 with concrete per-domain commands (e.g., the exact caddy adapt invocation and the exact focused go test command) so the guidance is copy-paste ready when local context supports it.

Trim the Symptom Checks bullets to the distinguishing checks per failure class; several items (e.g., generic redirect/cookie checks) repeat knowledge already covered by the linked configuration and testing skills.

DimensionReasoningScore

Conciseness

The body is dense and almost entirely non-obvious, repo-specific knowledge (e.g., "older binaries may lack `security version`", "Adaptation does not prove runtime behavior") with no padding or explanation of concepts Claude already knows. It is not a 5 because several sections could still be tightened — the OIDC consent bullet and parts of the Symptom Checks run long — landing it at anchor 4 (efficient, minor instances that could be trimmed) rather than anchor 5's every-token-earns-its-place.

4 / 5

Actionability

Concrete, executable specifics abound: "`caddy list-modules --versions | rg '(auth|security)'`", the report filename pattern "YYYYMMDD_HHMM_<short-issue-slug>.md", exact issue-template sections, and exact paths like "tmp/breakfix/". It stops short of anchor 5 because validation commands are deliberately contingent ("Use Caddy adaptation or focused Go tests when local context supports it; otherwise describe the exact command the reporter should run") rather than copy-paste ready per failure class.

4 / 5

Workflow Clarity

The 8-step workflow has a clear sequence, an explicit validation step with safety constraints ("Validate with the narrowest available command", "Reproduce with disposable local data before provisioning a supplied deployment config"), and an acceptance-criteria checklist. It falls short of anchor 5 because there is no explicit feedback loop (validate → fix → re-validate) and step 6's checkpoint is conditional rather than a deterministic command.

4 / 5

Progressive Disclosure

Section headers (Purpose, Workflow, Symptom Checks, Response Shape, Issue Report File, Skill Gap Feedback, Acceptance criteria) give clear navigation, and detail material is consistently delegated via well-signaled one-level markdown links to sibling skills and their references (e.g., ../configuration/SKILL.md, references/oidc-provider.md, references/oidc-conformance.md) — no bundle files ship alongside this SKILL.md, so the body must stand alone. It is anchor 4 rather than 5 because some inlined material, notably the ~14-line OIDC consent POST procedure inside Symptom Checks, reads like reference-file content that should live beside the oidc-provider.md material it already points to.

4 / 5

Total

16

/

20

Passed

Description

87%Weight 40%Scale 1-5

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

A strong description: third-person voice, explicit what and when clauses, concrete evidence sources and deliverables, and a tightly scoped niche that is unlikely to trigger for the wrong skill. The only meaningful gap is the absence of symptom-level trigger phrases (login, redirect loop, callback, 401/403) that users would most naturally say when a caddy-security deployment breaks.

DimensionReasoningScore

Specificity

The description names concrete actions grounded in specific evidence sources — "Diagnose caddy-security deployment and runtime failures from configs, logs, versions, and HTTP evidence" — plus deliverables ("focused fixes, unresolved support handoffs, or preparing break-fix issue reports"), but only one diagnostic verb and no symptom-level specifics. This matches anchor 4 (several specific actions, minor coverage gaps) rather than 5, which would enumerate a fuller range of capabilities; it is well above anchor 3's single-pair of domain-plus-actions.

4 / 5

Completeness

Both parts are explicit: the "what" is "Diagnose caddy-security deployment and runtime failures from configs, logs, versions, and HTTP evidence" and the "when" is the concrete trigger clause "Use for focused fixes, unresolved support handoffs, or preparing break-fix issue reports." This matches the anchor-5 example structure (what + explicit Use-for triggers with concrete phrases); anchor 4 would leave the when-clause weaker or less specific.

5 / 5

Trigger Term Quality

Natural terms like "deployment and runtime failures", "configs", "logs", "HTTP evidence", "fixes", "support handoffs", and "break-fix issue reports" give good keyword coverage for what a user or maintainer would say. It sits at anchor 4 rather than 5 because common symptom phrasings users actually type (login failure, redirect loop, callback error, 401/403, OAuth/SAML/LDAP) are absent.

4 / 5

Distinctiveness Conflict Risk

The caddy-security break-fix niche is highly specific — deployment/runtime failure diagnosis from configs, logs, versions, and HTTP evidence, with issue-report preparation as a distinct deliverable — so it occupies a clear niche with minimal overlap risk against generic configuration or testing skills. It clearly matches anchor 5's "clear niche with distinct triggers" rather than anchor 4's minor overlap with closely related skills.

5 / 5

Total

18

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 5 suspicious

Warning

Total

15

/

16

Passed

Repository
greenpau/caddy-security
Reviewed

Table of Contents

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.