CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

diagnostics

Diagnose a crashed, hung, or erroring deployed Databricks App. Use when: (1) an app is crashed / UNAVAILABLE / 502s, (2) an app hangs or is unresponsive, (3) you need the stack trace behind a failure, (4) questions about reading app logs or the diagnostics env toggles.

Quality

89%

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

The canonical home for this skill is diagnostics in databricks/app-templates

SKILL.md
Quality
Evals
Security

Quality

Content

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

An excellent operational skill body: fully executable commands and exact log signatures for both Python and Node, environment-specific reading paths, and a coherent crash-vs-hang diagnostic structure, with almost no token waste. The residual gaps are minor — a couple of Claude-known asides, no explicit post-diagnosis verification step, and a crash-examples pointer that does not resolve inside the bundle.

Suggestions

Trim the Node-default aside to just the observable fact: 'unhandled promise rejections surface here too (origin `unhandledRejection`)' — Claude knows Node's default escalation behavior.

Close the hang/crash workflow with an explicit verification checkpoint, e.g. 'After a fix, re-run `databricks apps get <app-name> --output json | jq '.app_status'` (or reload the log viewer) to confirm the app is AVAILABLE.'

Make the crash-fixtures pointer navigable within the bundle — either add the files under scripts/ and link them relatively, or reword to 'see the repo's `.scripts/agent-integration-tests/crash-examples/` (not bundled)' so the path is not mistaken for a bundle reference.

DimensionReasoningScore

Conciseness

Nearly every token is Databricks-platform-specific operational detail Claude cannot know (logz URL, SSO websocket-302 limitation, exact log signatures, env var table, 'no ptrace / CAP_SYS_PTRACE' rationale). A couple of minor trims exist — the parenthetical '(Node's default `--unhandled-rejections=throw` escalates it to `uncaughtException`)' and 'the app's log stream' re-explain behavior Claude already knows — which fits the 4 anchor ('efficient; minor instances of over-explanation') rather than 5.

4 / 5

Actionability

Copy-paste-ready throughout: the logz viewer URL, `databricks apps logs <app-name> --follow --profile <profile>`, the `jq '.app_status'` pipeline, a complete app.yaml env snippet, `kill -USR1 <pid>`, and the exact log signatures to grep for — covering the common cases (crash, worker-thread crash, SIGTERM kill, unhandled rejection, hang) for both Python and Node. Nothing is pseudocode or vague.

5 / 5

Workflow Clarity

The diagnostic flow is clear and branch-aware: environment check (SSO vs CLI) for reading logs, a signature catalog to match against, and ordered hang guidance ('the SIGTERM all-thread dump (above) shows where it was stuck — check that first') plus an if-then escalation (enable the watchdog env var and redeploy; 'If you can signal the pod, kill -USR1'). Not 5 because the sequence is conveyed by section order rather than explicit steps, and there is no closing validation loop (e.g. confirm `.app_status` is healthy after a fix) — minor checkpoint gaps matching the 4 anchor; well above 3, whose sequence lacks checkpoints entirely.

4 / 5

Progressive Disclosure

Well-organized sections (Reading the logs / What to look for / Diagnosing a hang / Environment toggles / Notes), and at ~75 lines of dense operational reference the inline content is appropriately sized — no monolith or buried references. Not 5 because the one outbound pointer, 'Runnable crash fixtures + the e2e crash test live in `.scripts/agent-integration-tests/crash-examples/`', does not resolve within the skill bundle (no references/, scripts/, or assets/ exist), so it is not a well-signaled one-level reference; that plus the env-toggle table being borderline extractable leaves a minor organization gap at the 4 anchor.

4 / 5

Total

17

/

20

Passed

Description

90%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: concrete what, explicit four-part use-when triggers with natural vocabulary (crashed, hung, 502s, unresponsive, stack trace, app logs), and a clearly bounded niche. The only deductions are the second-person 'you need' phrasing in trigger (3), which both violates the third-person voice rule and leaves the what-clause thinner than the implied capability set.

Suggestions

Rewrite trigger (3) in third person to match the rest, e.g. 'Use when: (3) the user needs the stack trace behind a failure', avoiding the second-person 'you need' that costs specificity under the voice rule.

Make the what-clause enumerate the concrete actions already implied by the triggers, e.g. 'Diagnose a crashed, hung, or erroring deployed Databricks App by reading its logs, stack traces, and diagnostics env toggles.'

DimensionReasoningScore

Specificity

The what-clause names the domain and a single concrete action ('Diagnose a crashed, hung, or erroring deployed Databricks App'), while the when-clauses imply further capabilities (stack traces, log reading, env toggles) — a base of 4 ('several specific actions; minor gaps'). However, trigger (3) 'you need the stack trace behind a failure' uses second-person voice, which the rubric penalizes by reducing specificity by 1, yielding 3.

3 / 5

Completeness

Explicitly answers both: what ('Diagnose a crashed, hung, or erroring deployed Databricks App') and when ('Use when: (1) an app is crashed / UNAVAILABLE / 502s, (2) an app hangs or is unresponsive, (3) you need the stack trace behind a failure, (4) questions about reading app logs or the diagnostics env toggles') — four concrete trigger phrases, matching the 5 anchor exactly.

5 / 5

Trigger Term Quality

Comprehensive natural terms users would actually say: 'crashed', 'hung', 'unresponsive', '502s', 'UNAVAILABLE', 'stack trace', 'app logs', and the diagnostics env toggles — covering synonyms and concrete status codes the way the 5-anchor covers file extensions. Not 4 because no common variation of a crash/hang/log-reading request is missing.

5 / 5

Distinctiveness Conflict Risk

'deployed Databricks App' with crash/hang/log-diagnosis triggers carves a clear niche with minimal overlap; a generic deployment or non-Databricks debugging question would not fire these triggers. Not 4 because the trigger set is uniformly diagnostics-flavored rather than broadly matching Databricks work.

5 / 5

Total

18

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

databricks/app-templates

Path

agent-openai-agents-sdk-multiagent/.claude/skills/diagnostics/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.