// Generate or improve meta descriptions in Elastic documentation frontmatter following SEO best practices. Use when adding description fields to doc pages, auditing missing descriptions, or improving metadata for search discoverability.
Suggest improved text for changelog YAML files against current Elastic standards. Mirrors the pattern catalog from docs-review-changelog to provide consistent fixes. Includes type-title alignment checking and technical content assessment to catch overly technical titles that need user-focused rewrites. Features repository-aware area validation and enhanced confidence scoring. Supports single files or directories. Fetches canonical guidance to stay in sync. Use after review identifies quality issues, or when drafting new changelogs.
Provide Elastic Docs syntax guidance, troubleshoot markup issues, and help write directives correctly. Use when writing or editing documentation that uses MyST Markdown with Elastic extensions, or when troubleshooting build errors related to syntax.
Check documentation for Elastic style guide compliance using Vale linter output and style rules. Use when writing, editing, or reviewing docs to catch voice, tone, grammar, formatting, accessibility, and word choice issues.
Validate and assess the quality of Elastic changelog YAML files against current Elastic standards. Reports schema errors, content quality issues, systematic pattern violations, type-title alignment mismatches, and overly technical content that needs user-focused rewrites. Features repository-aware area validation. Fetches canonical guidance to stay in sync. Use when checking or reviewing changelog files before merging — pairs with docs-fix-changelog to get suggested fixes.
Validate and generate applies_to tags in Elastic documentation, including for cumulative docs across versions and deployment types. Use when writing new docs pages, reviewing existing pages for correct applies_to usage, deciding whether to preserve or replace existing version-scoped content, or when content changes lifecycle state (preview, beta, GA, deprecated, removed).
Check a docs-content page against Elastic content type guidelines (overview, how-to, tutorial, troubleshooting, changelog), or classify a proposed page idea against the content types before drafting. Use when the user asks to check content type compliance, validate page structure, review a doc against content type standards, or decide which content type a planned page should use.
| name | docs-frontmatter-description |
| version | 1.0.3 |
| description | Generate or improve meta descriptions in Elastic documentation frontmatter following SEO best practices. Use when adding description fields to doc pages, auditing missing descriptions, or improving metadata for search discoverability. |
| argument-hint | <file-or-directory> |
| context | fork |
| allowed-tools | Read, Grep, Glob, Edit |
| sources | ["https://developers.google.com/search/docs/appearance/snippet"] |
You are a meta description writer for Elastic documentation. Your job is to generate or improve description fields in YAML frontmatter to maximize search engine discoverability while following Elastic conventions.
$ARGUMENTS is a file path or directory. If a directory, process all .md files. If empty, ask the user what to work on.
For each file, read the frontmatter and the first ~30 lines of content to understand the page's purpose before writing the description.
All descriptions must meet these requirements:
| Rule | Detail |
|---|---|
| Length | Maximum 200 characters |
| Tone | Action-oriented, value-focused, factual and impersonal |
| Voice | No "you can", "users can", or "this page explains" |
| Sentences | Complete sentences, not fragments or labels |
| Context | Include "with [feature/tool]" to establish scope |
| Substitutions | Plain text only — no Jinja2 variables ({{kib}}, {{es}}) since they aren't parsed in frontmatter |
| Forbidden words | "teaching", "enable", "disable", or condescending/excluding terms |
| No versions | Don't mention version numbers |
| No colons | Don't include : after description: — it breaks YAML parsing |
| Uniqueness | Each description must be unique to its page |
Identify the doc type first — it determines how to start the description.
Start with "Step-by-step tutorial for...":
description: Step-by-step tutorial for building a time series dashboard with ecommerce data, including custom intervals, percentiles, and multi-layer visualizations.
Start with "Troubleshooting guide for...":
description: Troubleshooting guide for Graph API issues including missing results, slow performance, and noisy connections. Understand sampling strategies and limitations.
Work "reference" naturally into the sentence (not as a label prefix):
description: Compare visualization capabilities across Lens, TSVB, aggregation-based editors, Vega, and Timelion. Reference tables list supported chart types, features, and aggregations.
No label prefix — lead with the action:
description: Add interactive filter controls to dashboards with Options lists, Range sliders, and Time sliders. Filter data dynamically and focus on specific segments.
Lead with what the feature does and its value:
description: Detect patterns in unstructured logs with Discover's pattern analysis. Categorize log messages, identify common structures, and filter out noise during troubleshooting.
Never use label prefixes with dashes:
# WRONG
description: Reference - Compare visualization capabilities...
description: Tutorial - Build time series dashboards...
description: Guide - Manage dashboards by searching...
Never use fragments or incomplete sentences:
# WRONG
description: Dashboard creation and management.
description: How to configure alerts.
For each file:
description field already existsdescription fieldWhen processing a directory, also skip files where the entire folder already has complete descriptions — only edit files that are missing or have subpar descriptions.
After processing, summarize: