diff --git a/docs/specification.mdx b/docs/specification.mdx
index f10f8be..6286443 100644
--- a/docs/specification.mdx
+++ b/docs/specification.mdx
@@ -30,7 +30,7 @@ description: A description of what this skill does and when to use it.
 ---
 ```
 
-With optional fields:
+**With optional fields:**
 
 ```yaml
 ---
@@ -61,7 +61,8 @@ The required `name` field:
 - Must not contain consecutive hyphens (`--`)
 - Must match the parent directory name
 
-Valid examples:
+<Card>
+**Valid examples:**
 ```yaml
 name: pdf-processing
 ```
@@ -72,7 +73,7 @@ name: data-analysis
 name: code-review
 ```
 
-Invalid examples:
+**Invalid examples:**
 ```yaml
 name: PDF-Processing  # uppercase not allowed
 ```
@@ -82,6 +83,7 @@ name: -pdf  # cannot start with hyphen
 ```yaml
 name: pdf--processing  # consecutive hyphens not allowed
 ```
+</Card>
 
 #### `description` field
 
@@ -90,15 +92,17 @@ The required `description` field:
 - Should describe both what the skill does and when to use it
 - Should include specific keywords that help agents identify relevant tasks
 
-Good example:
+<Card>
+**Good example:**
 ```yaml
 description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
 ```
 
-Poor example:
+**Poor example:**
 ```yaml
 description: Helps with PDFs.
 ```
+</Card>
 
 #### `license` field
 
@@ -106,10 +110,12 @@ The optional `license` field:
 - Specifies the license applied to the skill
 - We recommend keeping it short (either the name of a license or the name of a bundled license file)
 
-Example:
+<Card>
+**Example:**
 ```yaml
 license: Proprietary. LICENSE.txt has complete terms
 ```
+</Card>
 
 #### `compatibility` field
 
@@ -118,13 +124,15 @@ The optional `compatibility` field:
 - Should only be included if your skill has specific environment requirements
 - Can indicate intended product, required system packages, network access needs, etc.
 
-Examples:
+<Card>
+**Examples:**
 ```yaml
 compatibility: Designed for Claude Code (or similar products)
 ```
 ```yaml
 compatibility: Requires git, docker, jq, and access to the internet
 ```
+</Card>
 
 <Note>
 Most skills do not need the `compatibility` field.
@@ -137,12 +145,14 @@ The optional `metadata` field:
 - Clients can use this to store additional properties not defined by the Agent Skills spec
 - We recommend making your key names reasonably unique to avoid accidental conflicts
 
-Example:
+<Card>
+**Example:**
 ```yaml
 metadata:
   author: example-org
   version: "1.0"
 ```
+</Card>
 
 #### `allowed-tools` field
 
@@ -150,10 +160,12 @@ The optional `allowed-tools` field:
 - A space-delimited list of tools that are pre-approved to run
 - Experimental. Support for this field may vary between agent implementations
 
-Example:
+<Card>
+**Example:**
 ```yaml
 allowed-tools: Bash(git:*) Bash(jq:*) Read
 ```
+</Card>
 
 ### Body content