diff --git a/docs/specification.mdx b/docs/specification.mdx
index 6286443..32a9e57 100644
--- a/docs/specification.mdx
+++ b/docs/specification.mdx
@@ -23,7 +23,7 @@ The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
 
 ### Frontmatter (required)
 
-```yaml
+```markdown SKILL.md
 ---
 name: skill-name
 description: A description of what this skill does and when to use it.
@@ -32,7 +32,7 @@ description: A description of what this skill does and when to use it.
 
 **With optional fields:**
 
-```yaml
+```markdown SKILL.md
 ---
 name: pdf-processing
 description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
@@ -219,7 +219,7 @@ Keep your main `SKILL.md` under 500 lines. Move detailed reference material to s
 
 When referencing other files in your skill, use relative paths from the skill root:
 
-```markdown
+```markdown SKILL.md
 See [the reference guide](references/REFERENCE.md) for details.
 
 Run the extraction script: