CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

troubleshooting-dbt-job-errors

Diagnoses dbt Cloud/platform job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues. Use when a dbt Cloud/platform job fails and you need to diagnose the root cause, especially when error messages are unclear or when intermittent failures occur. Do not use for local dbt development errors.

Quality

83%

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

The canonical home for this skill is dbt-labs/dbt-agent-skills

SKILL.md
Quality
Evals
Security

Quality

Content

67%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-structured, highly actionable troubleshooting workflow whose main weakness is redundancy: the anti-shortcut guidance is stated three times and a quick-reference table duplicates earlier commands. Splitting peripheral detail into references and adding an explicit verify-the-fix step would raise quality.

Suggestions

Consolidate the redundant anti-shortcut guidance: merge 'The Iron Rule', the 'Rationalizations That Mean STOP' table, and the overlapping 'Common Mistakes' entries into one section, cutting ~30 lines of repetition.

Remove or shrink the 'Quick Reference' table since every command in it already appears in the workflow steps, or replace the inline endpoint/artifact-URL details with a short reference file to reduce SKILL.md length.

Add an explicit validation step in the resolution path: run the added test (and the fixed model) before creating the PR, e.g., `dbt test --select test_name` after implementing the fix.

DimensionReasoningScore

Conciseness

The guidance is mostly efficient and command-dense, but the same don't-game-the-test message is repeated three times ("The Iron Rule", the five-row "Rationalizations That Mean STOP" table, and the "Common Mistakes" section), and the "Quick Reference" table re-lists commands already shown verbatim in the workflow steps.

3 / 5

Actionability

Concrete, mostly executable guidance throughout: real MCP tool names, an exact artifact-URL template with placeholders, git/dbt commands, and a complete unit-test YAML example. Minor gaps: the Python-style `list_jobs()` / `mcp__dbt_parse()` snippets are illustrative rather than literal invocations, and there are small typos ("selectos").

4 / 5

Workflow Clarity

A clear four-step sequence (Gather → Classify → Investigate → Resolve) with a decision flowchart, an error-type classification table, and found/not-found root-cause branches. Not a 5 because the resolution path says to add a test but never instructs to actually run the test or the fix before opening the PR.

4 / 5

Progressive Disclosure

Well-sectioned body with clear headers, and the single bundle file (references/investigation-template.md) is real, one level deep, and linked exactly at the point of need. Not a 5 because nearly everything is inlined in one long SKILL.md — e.g., endpoint/artifact-URL details could live in a reference file.

4 / 5

Total

15

/

20

Passed

Description

92%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 capabilities, an explicit Use-when clause with specific triggers, and an explicit negative boundary. Only minor trigger-term synonyms are missing.

DimensionReasoningScore

Specificity

The description lists four concrete actions — "analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues" — which comprehensively cover the diagnostic workflow, matching the top anchor for multiple specific concrete actions without coverage gaps.

5 / 5

Completeness

It explicitly answers both what ("Diagnoses dbt Cloud/platform job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues") and when ("Use when a dbt Cloud/platform job fails... especially when error messages are unclear or when intermittent failures occur") with concrete trigger phrases.

5 / 5

Trigger Term Quality

Natural trigger phrases like "job fails", "diagnose the root cause", "error messages are unclear", and "intermittent failures" are present, but common user variations such as "run failed", "pipeline failure", or "dbt Cloud run" are missing, so coverage is good rather than comprehensive.

4 / 5

Distinctiveness Conflict Risk

It carves a clear niche (dbt Cloud/platform job failure diagnosis) with distinct triggers and an explicit exclusion ("Do not use for local dbt development errors"), minimizing the risk of firing for the wrong skill.

5 / 5

Total

19

/

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

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

dbt-labs/dbt-agent-skills

Path

skills/dbt/skills/troubleshooting-dbt-job-errors/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.