ElasticKnown publisherelastic/elastic-docs-skills/skills/authoring/docs-frontmatter-description/SKILL.mddocs-frontmatter-description
Skill72 starsChanged 5 months agoApache-2.0View on GitHub
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.
In this repository26 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- create-skillSkill
- docs-applies-to-taggingSkill
- docs-content-type-checkerSkill
- docs-draft-feature-docsSkill
- docs-page-opening-optimizerSkill
- docs-redirectsSkill
- docs-syntax-helpSkill
- docs-fix-changelogSkill
- docs-kibana-release-notesSkill
- docs-review-changelogSkill
- docs-serverless-changelogSkill
- docs-draft-workflow-docsSkill
- docs-kibana-settingsSkill
- docs-lens-chart-pageSkill
- docs-lens-chart-settingsSkill
- docs-check-contradictionsSkill
- docs-check-kibana-oasSkill
- docs-check-styleSkill
- docs-flag-jargon-skillSkill
- docs-frontmatter-auditSkill
- docs-review-prSkill
- docs-skill-reviewSkill
- docs-validate-code-samplesSkill
- docs-file-issueSkill
- docs-stack-releaseSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 38
All descriptions must meet these requirements:
- Distinctive: line 59
Start with "Step-by-step tutorial for...":
- Distinctive: line 66
Start with "Troubleshooting guide for...":
- Distinctive: line 80
No label prefix — lead with the action:
- Very specific: line 115
Check: if a description field already exists
- Distinctive: line 120
When processing a directory, also skip files where the entire folder already has complete descriptions — only edit files that are missing …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- 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 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.
Inputs
$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.
Constraints
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 |
Content type patterns
Identify the doc type first — it determines how to start the description.
Tutorials
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.Troubleshooting pages
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.Reference pages
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.Standard how-to / procedural pages
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.Overview / explanation pages
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.Anti-patterns
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.Workflow
For each file:
- Read the frontmatter and first ~30 lines of body content
- Identify the doc type (tutorial, how-to, reference, troubleshooting, overview)
- Check if a
descriptionfield already exists - Write or rewrite the description following the constraints and type pattern
- Verify length is ≤ 200 characters
- Edit the frontmatter to add or update the
descriptionfield
When processing a directory, also skip files where the entire folder already has complete descriptions — only edit files that are missing or have subpar descriptions.
Report
After processing, summarize:
- Files updated (with old → new description if rewritten)
- Files skipped (already had good descriptions)
- Files missing descriptions (if any remain)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.