CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

maintaining-dbt-documentation

Audits dbt documentation coverage and drafts missing model/column descriptions in the project's own house style, one folder at a time, for human review. Use when documenting undocumented models, backfilling missing YAML descriptions, auditing doc coverage, or keeping schema YAML in sync with model SQL — especially on multi-contributor projects where new models routinely land undocumented.

Quality

87%

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 dbt-labs/dbt-agent-skills

SKILL.md
Quality
Evals
Security

Quality

Content

85%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 skill body: concrete commands, an audited-then-verified workflow with explicit checkpoints and stop conditions, and disciplined scope and safety rules. The only trims available are repeated guardrail phrasing and a slightly tangential catalog note, and the absence of any sample YAML entry is the main actionable gap.

DimensionReasoningScore

Conciseness

The body is dense, operational guidance Claude cannot infer (manifest-based auditing, house-style mirroring, scope discipline), with clear sections. It is not a 5 because guardrails repeat across sections — "never commits or pushes" appears in the intro, workflow step 6, and the mistakes table; "no warehouse needed/needed no warehouse connection" appears twice in step 1 — and the catalog.json digression is slightly tangential. It is above 3 because nearly every token is project-specific know-how rather than padding or concepts Claude already knows.

4 / 5

Actionability

Executable commands are given verbatim ("dbt parse", "python3 <SKILL_BASE_DIR>/audit_coverage.py <folder>", "git diff <folder>", "--manifest <path>") and the drafting steps are concrete (identify grain, resolve every ref()/source(), reuse upstream wording, greenfield fallback recipe). It falls short of 5 because the skill's main output artifact — a drafted YAML entry — is never shown by example, even for the greenfield case where no house style exists to mirror; it is above 3 because everything needed to execute is present and specific.

4 / 5

Workflow Clarity

Six clearly sequenced steps with an explicit validation checkpoint and feedback loop: step 5 requires re-running "dbt parse" ("must be clean before handing back") and re-running the audit to confirm the closed gap, and step 1 has an explicit stop condition ("If the audit shows 0 gaps, report full coverage and stop"). The mistakes table adds a red-flag checklist, matching the top anchor for batch operations with validation.

5 / 5

Progressive Disclosure

A single-file skill, cleanly sectioned (conventions, workflow, untrusted input, scope, mistakes), whose only external dependency (audit_coverage.py) is clearly signaled with full invocation instructions, plus one-level-deep pointers to sibling skills (running-dbt-commands, using-dbt-for-analytics-engineering). No inline content clearly belongs in a separate file, and navigation is easy, so it sits at the top anchor rather than 4.

5 / 5

Total

18

/

20

Passed

Description

88%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, comprehensive capability statement with an explicit 'Use when' clause full of natural trigger phrases, in third person. Its only weaknesses are a few missing common synonyms (dbt docs, schema.yml, column descriptions) and no explicit boundary against the sibling one-off documentation-writing skill.

DimensionReasoningScore

Specificity

"Audits dbt documentation coverage and drafts missing model/column descriptions in the project's own house style, one folder at a time, for human review" names the domain and multiple concrete actions (audit coverage, draft model and column descriptions, hand off for review) that comprehensively cover what the skill does. It is not 4 because no capability is left out; nothing is generic or abstract.

5 / 5

Completeness

It explicitly answers both what ("Audits dbt documentation coverage and drafts missing model/column descriptions... one folder at a time, for human review") and when ("Use when documenting undocumented models, backfilling missing YAML descriptions, auditing doc coverage, or keeping schema YAML in sync with model SQL") with concrete trigger phrases, matching the top anchor exactly.

5 / 5

Trigger Term Quality

"documenting undocumented models", "backfilling missing YAML descriptions", "auditing doc coverage", and "keeping schema YAML in sync with model SQL" are natural phrases a dbt user would say. It is not 5 because common variations such as "dbt docs", "schema.yml", or "column descriptions" are absent; it is above 3 because the keyword set is broad, natural, and multi-word.

4 / 5

Distinctiveness Conflict Risk

The dbt documentation-maintenance niche is clear and the triggers are specific, so overlap with unrelated skills is minimal. It is not 5 because the description does not carve out the boundary with the closely related companion skill for one-off documentation writing (that disambiguation only appears in the body), leaving minor overlap risk with that sibling; it is well above 3 because nothing generic remains.

4 / 5

Total

18

/

20

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 — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

metadata_version

'metadata.version' is missing

Warning

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

13

/

16

Passed

Repository

dbt-labs/dbt-agent-skills

Path

skills/dbt/skills/maintaining-dbt-documentation/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.