dbt-labs/dbt-agent-skills
A curated collection of Agent Skills for working with dbt, to help AI agents understand and execute dbt workflows more effectively.
91
Does it follow best practices?
Validation for skill structure
troubleshooting-dbt-job-errors
skills/dbt/skills/troubleshooting-dbt-job-errors/SKILL.md
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the key criteria. It provides specific concrete actions, includes natural trigger terms users would actually say, explicitly states both what it does and when to use it, and carves out a distinct niche with clear boundaries including an explicit exclusion clause.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'analyzing run logs', 'querying the Admin API', 'reviewing git history', and 'investigating data issues'. These are clear, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('Diagnoses dbt Cloud/platform job failures by analyzing run logs...') and when ('Use when a dbt Cloud/platform job fails and you need to diagnose the root cause'). Also includes helpful exclusion criteria ('Do not use for local dbt development errors'). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'dbt Cloud', 'job fails', 'job failures', 'run logs', 'error messages', 'intermittent failures'. Also explicitly excludes 'local dbt development' to prevent false triggers. | 3 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting dbt Cloud/platform job failures specifically. The explicit exclusion of local dbt development errors and focus on cloud platform diagnostics creates clear boundaries that minimize conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-structured skill that provides actionable guidance for diagnosing dbt job failures. The workflow is clear with explicit validation steps and decision points. Minor verbosity in the behavioral guidance sections ('Iron Rule', 'Rationalizations' table) could be trimmed, but overall the skill effectively balances comprehensiveness with usability.
Suggestions
Consider condensing the 'Iron Rule' and 'Rationalizations That Mean STOP' sections into a single brief warning, as Claude understands the importance of proper diagnosis without extensive justification.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but includes some redundant content like the 'Rationalizations That Mean STOP' table which, while useful, adds tokens for behavioral guidance Claude likely understands. The mermaid diagram and some explanatory text could be tightened. | 2 / 3 |
Actionability | Provides fully executable commands and concrete examples throughout - specific MCP tool calls, dbt CLI commands, git commands, and even a complete unit test YAML example. The artifact URL template with placeholders is immediately usable. | 3 / 3 |
Workflow Clarity | Clear 4-step workflow with explicit decision points, validation checkpoints, and feedback loops. The mermaid diagram visualizes the process, and each step has clear branching logic based on error type and whether root cause is found. | 3 / 3 |
Progressive Disclosure | Well-structured with clear sections, a quick reference table at the end, and appropriate external reference to the investigation template. Content is organized for scanning with tables and code blocks, without unnecessary nesting. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |