name: frontmatter-description description: 'Check and optimize MetaDescription frontmatter fields in VS Code documentation. Use when auditing, adding, or improving page descriptions for SEO and discoverability. Apply this when making content changes to markdown articles.'

Frontmatter Description

Check and optimize MetaDescription frontmatter fields in markdown documentation files. Produces actionable fixes for descriptions that violate the rules below.

When to Use

• Adding or editing a documentation page and need to write a MetaDescription.
• Auditing existing pages for SEO or discoverability improvements.
• Asked to check, review, or optimize frontmatter descriptions.
• Editing content articles and want to ensure the MetaDescription reflects the updated content.

Rules

Every MetaDescription value must satisfy all of the following:

Procedure

1. Identify target files

Determine which files to check:

• If given specific files, use those.
• If asked to audit a folder (e.g., docs/copilot/), find all .md files in that folder recursively.
• Skip files that have no YAML frontmatter (e.g., README.md files without --- delimiters).

2. Extract and validate

For each file, read the YAML frontmatter and check the MetaDescription field:

1. Missing — Flag if MetaDescription is absent.
2. Length — Flag if the value exceeds 160 characters. Report the current length.
3. Voice — Flag if it contains "you can", "users can", "this page explains", or similar reader-addressing phrases.
4. Tone — Flag if the description is a fragment, a label, or passive rather than action-oriented.
5. Context — Flag if the description does not mention the relevant feature or tool.
6. Forbidden words — Flag any occurrence of "teaching", "enable", "disable", or condescending terms.
7. Colons — Flag any : character in the value.
8. Versions — Flag any version numbers (e.g., "v1.90", "VS Code 1.90").
9. Plain text — Flag Jinja2 variables ({{...}}), HTML tags, or Markdown formatting.

3. Report findings

Present results as a table:

| File | Issue | Current value | Suggested fix |
|------|-------|---------------|---------------|

• Group by file path.
• For each issue, provide the current MetaDescription and a rewritten suggestion that passes all rules.
• If a description passes all checks, omit it from the table (or mark it as passing if the user asked for a full report).

4. Apply fixes (when asked)

• Edit the MetaDescription value in the YAML frontmatter.
• Do not change any other frontmatter fields.
• Do not alter the page body content.
• Verify the fix passes all rules before applying.

Examples

Good descriptions:

• Get AI-powered inline suggestions from GitHub Copilot in VS Code, including ghost text completions and next edit suggestions.
• Configure and manage extensions in Visual Studio Code to customize your development environment.
• Debug Python applications in Visual Studio Code with breakpoints, variable inspection, and integrated terminal output.

Bad descriptions and why: