harlan-zw · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/.gitignore b/.gitignore
@@ -45,3 +45,4 @@ broken-skills.json
 
 # PR Lens writes its previews here. They are rebuilt on demand.
 .pr-lens/
+layers/registry/server/data/skill-demos.json.lock
diff --git a/COPY.md b/COPY.md
@@ -38,6 +38,11 @@ These exact strings. Do not paraphrase them per page.
 | Agents way: prompt | Paste into any agent · Your agent reads the setup steps and picks the path that fits it. | guidance only: the first way in the homepage Agents section, over the setup prompt |
 | Agents way: terminal | From a terminal · Teaches your agent to search and run Skills in every project. | guidance only: the second way, over `npx skilld install skilld --global` |
 | Agents way: MCP | In ChatGPT, Claude, and other MCP apps · Add the server once. Then ask the chat to find a Skill. | guidance only: the third way, over the MCP server URL. Its link, "Setup steps for each app", opens `/developers?setup=mcp` |
+| Home section: demos | See what skills make. · Each demo is one recorded run: the prompt, and what the Agent built with the Skill. | guidance only: the homepage demo section heading and line. The section hides below three demos |
+| Demo stage | Open the demo | guidance only: the homepage demo stage link to the Skill page Demo panel |
+| Demo panel | Demo · You say · Open live demo · Open in a new tab · Run it yourself | guidance only: the Skill page Demo panel. "Show screenshots" replaces "Open live demo" while the live output shows |
+| Demo provenance | {Agent logo} {model}, such as Opus 5.5 | guidance only: the recording line on the Skill page panel and the homepage stage. Screen readers and the title get "Recorded with {agent}, {model}". No date and no GitHub link: the Skill page is where visitors inspect a Skill |
+| Demo outdated | Recorded on an older version of this Skill. | guidance only: under the Demo panel when the Skill moved past the recorded commit |
 | Home section: changes | Keep up with skill changes. | guidance only: the homepage section heading for watching and the digest |
 | Home section: authoring | Write a skill for your project. | guidance only: the homepage section heading for making a Skill |
 | Nav: developers | Developers | guidance only: the header menu trigger, and the group label in the mobile menu. The menu holds the four items below |

diff --git a/GLOSSARY.md b/GLOSSARY.md
@@ -14,6 +14,7 @@ Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). Th
 | Artifact | skilld.dev API | Skill commit 1—1 Artifact | not shown |
 | source status | lockfile, skilld.dev API | Artifact 1—1 source status | "Verified", "Unverified", "Local" |
 | run | skilld CLI | Skill 1—1 run command | "run" |
+| demo | Skill page, homepage | Skill 1—N demo | "demo" |
 | install | skilld CLI | Skill 1—1 install command | "install" |
 | fork | Agent, Skill page | Skill 1—N local copy | "fork" |
 | lockfile | skilld CLI | project 1—1 lockfile | "lockfile" |
@@ -83,6 +84,16 @@ Collisions
 
 **Never:** try, preview, use once, ephemeral.
 
+### demo
+
+**Is:** one recorded run of a Skill: a fixed prompt, the output an Agent made with the Skill, and how it was recorded (Agent, model, Skill commit, date). A human approves each one before it ships.
+
+**Use for:** the Demo panel on the Skill page, the homepage demo section, and "live demo" for the sandboxed output page.
+
+**Never:** preview, example output, showcase, sample. "Preview" is already a banned synonym for run.
+
+**Rule:** a demo shows the Agent's output, never the Skill author's work. It always names how it was recorded.
+
 ### install
 
 **Is:** `skilld install`. Skill files land in the project and the lockfile records them. The opt-in second step.
@@ -314,6 +325,7 @@ Existing route paths, table names, and protocol fields keep their identifiers.
 | follow | watch | One Loop 2 verb |
 | sync (user-facing) | import (stars), "Checked GitHub {ago}" (freshness) | Internal jargon; say what happened |
 | use once, try, preview | run ("run once off" in pitch copy) | One name for the transient path |
+| showcase, sample, example output | demo | One name for a recorded run |
 | add (CLI verb) | run or install | v2 grammar |
 | popular, install count | starred, stars | Installs never rank or trust |
 | verified safe, secure, scanned | name the exact check | An attestation cannot guarantee safety |
Original file line number	Diff line number	Diff line change
Expand Up		@@ -45,3 +45,4 @@ broken-skills.json

		# PR Lens writes its previews here. They are rebuilt on demand.
		.pr-lens/
		layers/registry/server/data/skill-demos.json.lock