dab-docs-audit

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.

Ir para a instalação

Repositório: MicrosoftDocs/data-api-builder-docs
Última atividade na origem: 23 de junho de 2026 às 14:51
Idioma detectado do SKILL.md: inglês
Estrelas: 8
Forks: 27

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.

npx skills add https://github.com/MicrosoftDocs/data-api-builder-docs --skill dab-docs-audit

O comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.

Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

SKILL.md

Instruções da origem · Visualização somente leitura

Voltar à pesquisa Voltar à instalação

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

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.

Check	Rule
Standard Markdown syntax	Must use `![alt text](path)`. 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.

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.

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.

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.

dab-docs-audit

Opções de instalação

Revise os arquivos de origem

DAB Docs Audit

When to use

Audit checklist

1. YAML frontmatter

DAB Docs Audit

When to use

Audit checklist

1. YAML frontmatter

2. Heading structure

3. Images

4. Links

5. Code blocks

6. Alerts

7. Tab groups

8. Voice and style

9. Information architecture

10. Peer consistency

Output format

Platform build validation rules

Procedure

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.

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.

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.

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.

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`.

dab-docs-audit

Informações da origem

Opções de instalação

Revise os arquivos de origem

Mais deste repositório

Mais deste repositório

DAB Docs Audit

When to use

Audit checklist

1. YAML frontmatter

DAB Docs Audit

When to use

Audit checklist

1. YAML frontmatter

2. Heading structure

3. Images

4. Links

5. Code blocks

6. Alerts

7. Tab groups

8. Voice and style

9. Information architecture

10. Peer consistency

Output format

Platform build validation rules

Procedure