dab-docs-audit

name	dab-docs-audit
description	Audit a Data API builder documentation file for Microsoft Learn compliance, style, accuracy, and information architecture. Checks frontmatter, links, images, code fences, alerts, tabs, voice, and peer consistency.
argument-hint	Provide: file path to audit (or use the active file). Optionally specify focus area: full, style, links, metadata, images, or peer-consistency.
user-invocable	true

DAB Docs Audit

Use this skill to audit one or more Data API builder documentation files against Microsoft Learn publishing requirements, DAB repo conventions, and platform build validation rules. This skill produces a structured findings report grouped by severity.

When to use

• After creating or substantially editing a file.
• Before submitting a PR.
• When reviewing someone else's contribution.
• As a final check after implementing sub-agent review feedback.

Audit checklist

Run every check in this list against each file being audited. Report findings grouped by severity: blocking (will fail build or violate Learn requirements), compliance (should fix before publish), and polish (nice to have).

---

1. YAML frontmatter

Check	Rule
title present	Required. Sentence case. 1–160 characters.
description present	Required. 75–300 characters. Must not start with a brand name.
author present	Required. Must be a valid GitHub username.
ms.author present	Required. Must be a Microsoft alias (without @microsoft.com).
ms.reviewer present	Expected in this repo.
ms.service	Must be data-api-builder.
ms.topic	Must use a Microsoft Learn-valid topic value. For concept articles, use concept-article, not concept. Common values in this repo include concept-article, how-to, quickstart, tutorial, whats-new, reference, landing-page, and faq.
ms.date	Required. Format MM/DD/YYYY. Should reflect the last substantial edit.
# Customer Intent comment	Expected in this repo. Format: As a <role>, I want to <action> so that I can <outcome>.
No extra/unknown fields	Flag unexpected metadata fields.

2. Heading structure

Check	Rule
Sentence case	Only the first word and proper nouns are capitalized.
No skipped levels	## before ###. Never skip from ## to ####.
No gerunds	Use "Configure..." not "Configuring...".
H1 matches title	The # heading should closely match the title frontmatter.
No intro phrases as headings	If a "heading" is really an intro to a code block, use body text with a colon instead.

3. Images

Check	Rule
Standard Markdown syntax	Must use . Flag any :::image blocks (all forms: type="complex", type="content", or otherwise).
Alt text present	Every image must have alt text.
Alt text descriptive	Alt text must be 10–250 characters. Must not be just the filename. Should start with "Diagram showing" or "Screenshot of" and end with a period.
Page-specific media folder	Images must be in media/<page-name>/ subfolder matching the doc filename.
No shared media folders	Each doc must have its own media subfolder.
Files exist	Verify referenced image files exist on disk.

4. Links

Check	Rule
Same-folder links	Use just the filename: sibling-file.md.
Cross-folder links	Use relative paths: ../concept/config/env-function.md.
Microsoft Learn cross-service	Use site-relative paths starting with /: /cli/azure/install-azure-cli.
No absolute Learn URLs	Flag any https://learn.microsoft.com/... links. These should be site-relative.
No locale in paths	Remove /en-us/ from any site-relative links.
External links	Must use full HTTPS URLs.
No "click here"	Link text must be descriptive, not generic.
Bookmark anchors	Anchors must be lowercase, hyphens for spaces, no punctuation.
Link targets exist	For internal links, verify the target .md or .yml file exists.

5. Code blocks

Check	Rule
Language tag present	Every fenced code block must have an explicit language tag.
Correct language tags	DAB CLI → dotnetcli, .NET CLI → dotnetcli, Azure CLI → azurecli, PowerShell → powershell, Bash → bash, JSON → json, YAML → yaml, Dockerfile → dockerfile, plain text → text.
No indented code blocks	Code blocks must use triple backticks, not indentation. Indented code blocks fail build validation.
Unclosed code blocks	Every opening ``` must have a matching closing ```.
Proper indentation under lists	Code blocks inside numbered/bulleted lists must be indented 4 spaces to align with the list item.

6. Alerts

Check	Rule
Correct syntax	Must use > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING].
No bold-text alerts	Flag > **Warning** or similar — use the proper alert syntax.
No custom alert types	Only NOTE, TIP, IMPORTANT, and WARNING are valid.
No stacked alerts	Avoid consecutive alert blocks unless each carries distinct value.

7. Tab groups

Check	Rule
Closed with ---	Every tab group must end with --- on its own line.
Consistent IDs	Tab IDs must be consistent across all tab groups on the same page (e.g., always powershell/bash).
--- not decorative	The --- delimiter must only be used to close tab groups, never as a horizontal rule or separator.

8. Voice and style

Check	Rule
Second person	Use "you" / "your". Flag any "we", "our", "let's", or first person.
Active voice	Flag passive constructions where active alternatives exist.
Present tense	Use present tense unless describing a completed past event.
No "we recommend"	Use "Consider..." or a direct imperative instead.
No marketing language	Flag "revolutionary", "game-changing", "seamless", "best-in-class", etc.
No future promises	Do not promise future features. Use "This feature is in preview."
Terminology	Use "back end" (two words), not "backend". Use "sign in", not "log in".
Concise	Flag unnecessary filler words, redundant phrases, and overly long sentences.

9. Information architecture

Check	Rule
In TOC.yml	The file must have an entry in data-api-builder/TOC.yml.
In folder index.yml	If the folder has a landing page, the file should be listed.
Cross-references exist	The file should be referenced from at least one peer doc or parent overview.
overview.md updated	If the file introduces a new feature or deployment option, check whether overview.md mentions it.

10. Peer consistency

Compare the file against others in the same folder:

Check	Rule
Frontmatter fields	Same fields and format as peers.
Section structure	Same heading order and pattern as peers.
Prerequisites format	Listed consistently with peers.
Intro paragraph	If peers have "This guide shows you how to...", include one.
Clean-up section	If peers have "Clean up resources", include one.
Related content pattern	Match the pattern: bullet list vs. nextstepaction.
Image pattern	If peers use map SVGs or architecture diagrams, include equivalent images.

---

Output format

Structure findings as a table grouped by severity:

## Blocking issues (must fix before publish)

| # | Line(s) | Category | Finding |
|---|---------|----------|---------|
| 1 | 15 | Image | `:::image` syntax used — convert to standard Markdown |

## Compliance issues (should fix)

| # | Line(s) | Category | Finding |
|---|---------|----------|---------|
| 2 | 10 | Frontmatter | `ms.date` is more than 12 months old |

## Polish (nice to have)

| # | Line(s) | Category | Finding |
|---|---------|----------|---------|
| 3 | 42 | Style | Passive voice: "is configured" → "configure" |

## Passed checks

| Category | Result |
|----------|--------|
| Alerts | All valid |
| Tab groups | Properly closed |

Platform build validation rules

These are the most commonly triggered platform validation rules in this repo. Flag any violation as blocking:

Rule ID	What it flags
alt-text-missing	Image without alt text
alt-text-bad-value	Alt text equals the filename
author-missing	Missing author in frontmatter
description-missing	Missing description in frontmatter
code-block-indented	Code block created by indentation instead of triple backticks
code-block-unclosed	Missing closing ```
column-header-missing	Table without column headers
article-toc-connection	.md file not connected to the TOC
docs-link-absolute	Absolute https://learn.microsoft.com/... link used
h1-missing	No H1 heading in the article
ms-topic-invalid	Invalid ms.topic value. Flag ms.topic: concept and replace it with ms.topic: concept-article.

Procedure

1. Read the file being audited and all frontmatter.
2. Run each check in sections 1–10 systematically.
3. Verify links — grep for internal link targets to confirm they exist.
4. Verify images — check that referenced media files exist on disk.
5. Compare against peers — read 1–2 peer files in the same folder for structural comparison.
6. Produce the findings report using the output format above.
7. If fixing: Before editing any .md file, confirm the author identity with a selectable default. Read the existing page frontmatter, offer to keep the current author / ms.author pair, and offer a custom-entry option. If either value is missing, offer author / ms.author pairs from peer files as selectable suggestions and allow a custom entry. Never guess or silently replace author or ms.author. If the user keeps the existing identity, update only ms.date unless other frontmatter must change. Apply edits for blocking and compliance issues. Leave polish items for the author to decide.

Do not make edits unless explicitly asked. The default output is a findings report only.