From a9d33af2d5e04e2e4b87429d5b17cc1180cc4d49 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Fri, 6 Mar 2026 16:16:58 -0600
Subject: [PATCH] Wrap examples in `<Card>` components in specification doc

The `####` field headings didn't stand out enough amongst all the code
blocks, making the page hard to scan. Wrapping each field's examples in
a `<Card>` draws a border around them and adds padding, so each
subsection looks more contained instead of bleeding into the next. Also
bolds the example labels within each card.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/specification.mdx | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

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