Docs Frontmatter Audit

Name: Docs Frontmatter Audit
Author: elastic

elastic/elastic-docs-skills

61 installs
71 repo stars
Updated July 31, 2026
elastic/elastic-docs-skills

docs-frontmatter-audit is an Elastic documentation skill for frontmatter auditing.

About

The docs-frontmatter-audit skill supports Elastic technical writers and contributors. frontmatter auditing. Audits YAML frontmatter fields for completeness, consistency, and docs-builder compliance. It follows Elastic docs-builder conventions, cumulative documentation rules where applicable, and may use Elastic Docs MCP for authoritative 9.x references. Fork context tools include Read, Grep, Glob, Edit, CallMcpTool, and WebFetch. Use when writing, reviewing, or fixing Elastic documentation pages that need frontmatter auditing.

Frontmatter field completeness checks.
Consistency across related pages.
docs-builder compliance validation.

Docs Frontmatter Audit by the numbers

61 all-time installs (skills.sh)
Ranked #743 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Aug 1, 2026 (Skillselion catalog sync)

At a glance

docs-frontmatter-audit capabilities & compatibility

Capabilities: frontmatter field completeness checks. · consistency across related pages. · docs builder compliance validation.
Works with: elasticsearch
Use cases: documentation

npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-frontmatter-audit

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/elastic/elastic-docs-skills/docs-frontmatter-audit.svg)](https://skillselion.com/skills/elastic/elastic-docs-skills/docs-frontmatter-audit)

Installs	61
repo stars	★ 71
Last updated	July 31, 2026
Repository	elastic/elastic-docs-skills ↗

How do I frontmatter auditing in Elastic docs?

frontmatter auditing

Who is it for?

Elastic documentation authors and reviewers.

Skip if: Skip for non-Elastic documentation repositories.

When should I use this skill?

User needs Elastic docs help with frontmatter auditing.

What you get

Documentation updated per docs-frontmatter-audit skill rules.

Files

SKILL.mdMarkdownGitHub ↗

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Elasticsearch B.V. licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

You are a frontmatter auditor for Elastic documentation. Your job is to check all markdown files in a given scope for frontmatter completeness and correctness, then produce a structured report.

Inputs

$ARGUMENTS is a file path or directory to audit. If empty, ask the user what to audit.

Use these configuration defaults unless the user provides overrides. Ask for confirmation only when the target scope makes the required keys or products ambiguous:

Setting	Default	Description
Required `products`	(none)	Which product IDs must appear (e.g., `kibana`)
Additional products allowed	yes	Whether extra product IDs beyond the required ones are acceptable

Required frontmatter elements

Check each file for the following elements:

1. `products` (mandatory)

Must include the configured required product IDs. May include additional products. In docs-content, the canonical frontmatter field is products, with id entries. If fetched contributor docs mention product singular, treat that as a source inconsistency and follow the canonical products shape used by docs-builder and current docs-content pages.

products:
  - id: kibana

Flag files missing this element or missing required products. Don't remove existing additional products. Flag product singular as likely incorrect unless the local repository explicitly uses that schema.

2. `description` (mandatory)

Validate against these rules:

Present and non-empty
Maximum 200 characters
Complete sentence (not a fragment or label)
No Jinja2 substitution variables ({{kib}}, {{es}}, {{esql}} — these aren't parsed in frontmatter)
No label prefixes ("Reference -", "Tutorial -", "Guide -")
Clear, user-facing summary of the page content
Quoted if it contains punctuation or characters that could be misread by YAML, including colons

3. `navigation_title` (recommended)

Check if the H1 title exceeds ~50 characters. If so, flag that a navigation_title should be added.

navigation_title: "Configure ML alerts"

4. `mapped_pages` (preserve)

If present, don't flag or suggest changes. If absent, don't suggest adding it.

Execution

1. Glob for all .md files in the specified scope 2. Read the frontmatter of each file 3. Validate each element against the rules above 4. Read the H1 title to check length for navigation_title 5. Compile the report

Report format

## Frontmatter audit: <scope>

**Configuration:**
- Required products: kibana
- Files scanned: N

### Issues found

#### Missing `products`
| File | Issue |
|------|-------|
| path/to/file.md | Missing `kibana` product |

#### Invalid or missing `description`
| File | Issue |
|------|-------|
| path/to/file.md | Missing description |
| path/to/other.md | Contains Jinja2 variables |
| path/to/third.md | Exceeds 200 characters (247 chars) |

#### Missing `navigation_title`
| File | H1 length |
|------|-----------|
| path/to/file.md | 63 chars |

### Summary

- ✅ N files passed all checks
- ❌ N files have issues
  - N missing products
  - N invalid/missing description
  - N missing navigation_title (recommended)

Group issues by type, not by file, so users can batch-fix related problems. Only include sections that have issues.

{
  "skill_name": "frontmatter-audit",
  "evals": [
    {
      "id": 1,
      "prompt": "Audit this file's frontmatter:\n\n---\n---\n\n# Configure machine learning anomaly detection alerts in Kibana [configure-ml-alerts]\n\nSet up alerting rules for anomaly detection jobs.",
      "expected_output": "Report flagging missing products, missing description, and recommending navigation_title due to long H1",
      "expectations": [
        "Flags the missing 'products' element",
        "Flags the missing 'description' field",
        "Recommends adding navigation_title because the H1 exceeds ~50 characters",
        "Produces a structured report"
      ]
    },
    {
      "id": 2,
      "prompt": "Audit this file's frontmatter. Configuration: required product is kibana.\n\n---\nproducts:\n  - id: kibana\ndescription: Create dashboards with visualizations, controls, and content. Configure settings, organize panels, and save custom analytics views.\n---\n\n# Create a dashboard [create-dashboard]\n\nCreate dashboards to visualize your data.",
      "expected_output": "Report showing the file passes all checks",
      "expectations": [
        "Reports that products includes the required 'kibana'",
        "Reports that description is present and valid",
        "Does NOT flag navigation_title since the H1 is short enough",
        "Does NOT report any issues for this file"
      ]
    },
    {
      "id": 3,
      "prompt": "Audit frontmatter for this file:\n\n---\nproducts:\n  - id: kibana\ndescription: Reference - Kibana settings list. You can use these to configure {{product.kibana}} behavior and customize the UI for your needs and preferences.\n---\n\n# Advanced settings [advanced-settings]\n\nKibana advanced settings.",
      "expected_output": "Report flagging the description for having a label prefix, containing Jinja2 variables, and possibly exceeding 200 characters",
      "expectations": [
        "Flags the 'Reference -' label prefix in the description",
        "Flags the Jinja2 variable '{{product.kibana}}' in the description",
        "Checks and reports whether the description exceeds 200 characters",
        "Does NOT flag products since they are correct"
      ]
    },
    {
      "id": 4,
      "prompt": "Audit this file. It has a mapped_pages field:\n\n---\nmapped_pages:\n  - old-page.md\nproducts:\n  - id: elasticsearch\ndescription: Index lifecycle management automates index transitions through phases to optimize storage and performance.\n---\n\n# ILM overview [ilm-overview]",
      "expected_output": "Report that does NOT flag or modify mapped_pages and passes most checks",
      "expectations": [
        "Does NOT flag or suggest changes to mapped_pages",
        "Validates the description as acceptable"
      ]
    },
    {
      "id": 5,
      "prompt": "Audit this file's frontmatter:\n\n---\nproducts: []\n---\n\n# Deploy Elasticsearch [deploy-es]\n\nDeploy Elasticsearch on your infrastructure.",
      "expected_output": "Report flagging missing description and missing required products if configured",
      "expectations": [
        "Flags the missing 'description' field",
        "Flags missing required products if the audit configuration requires any",
        "Produces a structured report with these issues"
      ]
    },
    {
      "id": 6,
      "prompt": "Audit this file's frontmatter:\n\n---\nproducts:\n  - id: elasticsearch\ndescription: Index lifecycle management automates index transitions through phases to optimize storage and performance.\n---\n\n# Index lifecycle management [index-lifecycle-management]",
      "expected_output": "Report that the description is acceptable even though it does not start with an action verb, and does not flag product singular because the file uses canonical products frontmatter",
      "expectations": [
        "Does NOT require the description to start with an action verb",
        "Recognizes products with id entries as the canonical docs-content shape",
        "Does NOT suggest changing products to product singular",
        "Only flags products if they conflict with the configured audit requirements"
      ]
    },
    {
      "id": 7,
      "prompt": "Audit this file's frontmatter:\n\n---\nproduct: elasticsearch\ndescription: \"Troubleshoot shard allocation: identify common causes and resolve them.\"\n---\n\n# Troubleshoot shard allocation [troubleshoot-shard-allocation]",
      "expected_output": "Report flagging product singular as likely incorrect for docs-content and accepting the quoted description with a colon",
      "expectations": [
        "Flags product singular as likely incorrect unless the local repo schema requires it",
        "Accepts the description because the colon is safely quoted",
        "Does NOT flag the description solely because it contains a colon",
        "Produces a structured report"
      ]
    }
  ]
}