CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

debug-openshell-cluster

Debug why an OpenShell gateway deployment is unhealthy, unreachable, or unable to create sandboxes. Use for gateway health failures, Docker/Podman runtime issues, Helm failures, Kubernetes scheduling, TLS or auth, gateway interceptors, supervisor middleware startup or runtime failures, external compute-driver sockets, VM drivers, or sandbox startup. Trigger keywords - debug gateway, gateway failing, deployment failing, helm install failing, cluster health, gateway health, gateway not starting, health check failed, sandbox pending, docker driver, podman driver, kubernetes driver, external driver, compute driver socket, gateway interceptor, supervisor middleware, middleware failed, vm driver.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

66%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.

The skill is exceptionally actionable and its diagnostic workflow is clearly sequenced with findings-to-fix mappings and safety guardrails. Its dominant weakness is structure: nearly all deep-dive material lives in SKILL.md itself, making it a ~29k-token monolith with only one externalized reference and some verbatim duplication across platform sections.

Suggestions

Split the deep-dive material into one-level reference files (e.g., references/kubernetes-troubleshooting.md, references/postgres-locks.md, references/proxy.md, references/openshift.md) and keep SKILL.md to the workflow, per-step first checks, and the failure-pattern table, expanding beyond the single supervisor-middleware.md reference.

Deduplicate the repeated 'Common findings' bullets shared between the Docker (Step 4) and Podman (Step 5) sections — identity-resolution, image pull, and OCI workspace validation bullets are reproduced nearly verbatim.

Move the multi-replica PostgreSQL advisory-lock essay (lock keys, pool sizing, pg_terminate_backend cautions, SSH identity keys) out of Step 6 into a reference and retain only the symptom-driven entry points in the Common Failure Patterns table, whose cells are also very long.

DimensionReasoningScore

Conciseness

The body runs ~1,740 lines / ~127KB (~29k tokens) of dense troubleshooting detail inlined into SKILL.md, including a ~500-line PostgreSQL advisory-lock treatise inside Step 6, three near-duplicate corporate-proxy sections, and bullets repeated verbatim across the Docker and Podman sections (identity-resolution, image-missing). While it never explains concepts Claude already knows, the volume and redundancy are far beyond the token-efficiency midpoint; it is not a 1 because essentially all content is novel product-specific fact rather than padding.

2 / 5

Actionability

Guidance is copy-paste executable throughout: exact bash blocks ('kubectl -n openshell get configmap openshell-config -o jsonpath=...', 'docker info --format '{{json .DiscoveredDevices}}'', 'stat /run/openshell/<driver>.sock'), exact error strings to grep for ('mutation lock held longer than the lock wait timeout', 'MountVolume.SetUp failed'), named config keys, and specific fixes per finding.

5 / 5

Workflow Clarity

The workflow is explicitly ordered (Step 1 CLI reachability → Step 2 identify compute platform → Step 3 startup dependencies → Steps 4–7 per-platform) with a stopping rule ('Run diagnostics in order and stop once the root cause is clear'), per-step 'Common findings' mapping observed output → cause → fix, and explicit safety guardrails (do not terminate lock sessions, do not relabel managed ConfigMaps, do not add capabilities as workaround).

5 / 5

Progressive Disclosure

Only one bundle reference exists (references/supervisor-middleware.md) and it is clearly signaled twice, but roughly 1,500 lines of platform-specific material that clearly belongs in separate reference files — Kubernetes TLS/cert-manager/peer-relay details, the PostgreSQL advisory-lock internals, OpenShift SCC guidance, per-platform proxy configuration — are inlined in SKILL.md, matching the anchor for content that should be separate files staying inline.

2 / 5

Total

14

/

20

Passed

Description

100%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.

The description is a strong example: third-person, dense with load-bearing detail, explicit about both capability and triggers, and highly distinctive to the OpenShell gateway domain. Its only cost is sheer length, but every phrase is a distinct trigger or capability, not padding.

DimensionReasoningScore

Specificity

The description names a concrete action ('Debug why an OpenShell gateway deployment is unhealthy, unreachable, or unable to create sandboxes') and enumerates the specific failure classes covered — 'Docker/Podman runtime issues, Helm failures, Kubernetes scheduling, TLS or auth, gateway interceptors, supervisor middleware... external compute-driver sockets, VM drivers, or sandbox startup' — giving comprehensive coverage of the debugging domain, matching the top anchor.

5 / 5

Completeness

It explicitly answers 'what' (first sentence: debug an unhealthy/unreachable OpenShell gateway deployment or sandbox creation failures) and 'when' (an explicit 'Use for...' clause listing concrete triggering scenarios plus a trigger-keyword sentence), matching the anchor for both what and when with concrete triggers.

5 / 5

Trigger Term Quality

The trigger list covers natural user phrases across the whole domain: 'debug gateway, gateway failing, deployment failing, helm install failing, cluster health, gateway health, gateway not starting, health check failed, sandbox pending, docker driver, podman driver, kubernetes driver, external driver, compute driver socket, gateway interceptor, supervisor middleware, middleware failed, vm driver' — comprehensive with synonyms and platform variants.

5 / 5

Distinctiveness Conflict Risk

It is scoped to a clearly named niche product ('OpenShell gateway deployment') with triggers tied to that product's specific components (compute drivers, gateway interceptors, supervisor middleware), so it is unlikely to fire for unrelated skills.

5 / 5

Total

20

/

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

skill_md_line_count

SKILL.md is long (1743 lines); consider splitting into references/ and linking

Warning

Total

15

/

16

Passed

Repository

NVIDIA/OpenShell

Path

skills/debug-openshell-cluster/SKILL.md

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.