Clarify Markdown heading syntax and fix escaped fences in SKILL.md examples

[jkim323]

Summary

Skill-authoring documentation pages do not consistently distinguish literal Markdown heading syntax from the rendered heading hierarchy it creates. Two pages also display and copy nested code fences with backslash escapes instead of ordinary triple-backtick fences.

The escaped-fence defect has a complete current footprint of 16 matching lines in two files:

• docs/contributing/skills.md contains 12 matching lines across the Prerequisites, Quick Start, and Script Reference examples.
• docs/customization/skills.md contains 4 matching lines across SKILL.md Anatomy / Body and Including Reference Materials.

A third page, docs/agents/code-review/language-skills.md, has no escaped fences, but its Checklist Structure example also uses literal ATX heading source without explaining the resulting level 2 and level 4 heading hierarchy.

NVDA correctly announces literal number-sign characters inside code. The accessibility barrier is insufficient explanation of the semantic result, combined with source examples that copy invalid escaped fence text.

Steps to reproduce

1. Build and serve the Docusaurus documentation site.
2. Start NVDA, enable browse mode, and open /hve-core/docs/contributing/skills.
3. Navigate to SKILL.md Content Structure, then read the Prerequisites, Quick Start, and Script Reference examples.
4. Use the code-block copy controls and inspect the nested fences in the copied text.
5. Open /hve-core/docs/customization/skills.
6. Read and copy the examples under SKILL.md Anatomy / Body and Including Reference Materials.
7. Open /hve-core/docs/agents/code-review/language-skills and read the Checklist Structure example.
8. Compare the literal ATX markers announced in each source example with any prose describing the heading levels they create.

Observed behavior

• Source examples are correctly exposed with a code role.
• Source lines inside the examples do not receive heading roles.
• NVDA announces literal ATX markers such as ## and #### as number-sign characters, as expected for code.
• The pages do not consistently explain the heading levels those markers create when used in a SKILL.md file.
• Nested fences in two pages display and copy as escaped text such as backslash-escaped triple backticks.
• The repository already demonstrates the correct longer-outer-fence pattern in docs/contributing/ai-artifacts-common.md.

Expected behavior

Each heading-bearing SKILL.md source example briefly explains the rendered heading hierarchy before the literal source. Screen readers can therefore distinguish the punctuation being read from the semantic structure the example produces.

Nested code fences display and copy as ordinary triple-backtick fences without backslashes. Source examples remain exposed as code, and lines inside those examples do not receive heading roles.

Environment

• Windows 11
• Microsoft Edge 151.0.4129.72
• NVDA 2026.1.1
• NVDA browse mode
• Local Docusaurus production build

Proposed remediation

1. Use an outer backtick fence longer than the nested triple-backtick fences, following the pattern in docs/contributing/ai-artifacts-common.md.
2. Replace all unintended escaped nested fences in docs/contributing/skills.md and docs/customization/skills.md with ordinary triple-backtick fences.
3. Add concise semantic-result prose before heading-bearing SKILL.md examples in docs/contributing/skills.md, docs/customization/skills.md, and docs/agents/code-review/language-skills.md.
4. Preserve the code role for source examples and do not add heading roles to source lines inside code blocks.
5. Add a repository-wide documentation check that rejects unintended backslash-escaped triple-backtick fence lines.

Acceptance criteria

• docs/contributing/skills.md uses valid nested fences in the Prerequisites, Quick Start, and Script Reference examples.
• docs/customization/skills.md uses valid nested fences in the SKILL.md Anatomy / Body and Including Reference Materials examples.
• An exact search under docs/ finds no unintended backslash-escaped triple-backtick fence lines.
• Heading-bearing SKILL.md examples in all three affected skill-authoring pages explain the heading levels their literal ATX markers create.
• Each source example remains exposed with a code role.
• Source lines inside code blocks do not receive heading roles.
• Code-block copy controls return ordinary nested fences without backslashes.
• Markdown validation and the Docusaurus production build pass.
• Manual NVDA verification confirms that explanatory prose makes the intended hierarchy understandable on all three pages.

Accessibility assessment

NVDA announcing literal number-sign characters inside code is expected and is not itself a WCAG failure. This issue tracks documentation clarity and copy correctness discovered during assistive-technology testing. The remediation must preserve access to the literal Markdown source while explaining the semantics it produces.