From 91f9154fbd90e454144a02481199d3568e21994c Mon Sep 17 00:00:00 2001
From: "ray.mond" <ray.luo@nyu.edu>
Date: Wed, 8 Apr 2026 17:31:15 -0400
Subject: [PATCH] Add display json specs

---
 DISPLAY.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |   6 ++-
 2 files changed, 143 insertions(+), 2 deletions(-)
 create mode 100644 DISPLAY.md

diff --git a/DISPLAY.md b/DISPLAY.md
new file mode 100644
index 0000000..2fdcd29
--- /dev/null
+++ b/DISPLAY.md
@@ -0,0 +1,139 @@
+# DISPLAY.json Specification
+
+**Spec Version:** 0.1.0
+
+## Overview
+
+`DISPLAY.json` is a presentation metadata file for agent skills. It lives alongside `SKILL.md` in a skill's root directory and describes how the skill should appear in a UI — icon, cover image, tags, and integration badges.
+
+To see examples of how `DISPLAY.json` data gets used to present skills, see https://www.zo.computer/skills (with both [image](https://www.zo.computer/skills/minecraft-server) and [video](https://www.zo.computer/skills/manim-composer) examples)
+
+`DISPLAY.json` is strictly a **display layer**. It does not duplicate or override anything in `SKILL.md`, which remains the source of truth for a skill's identity and behavior.
+
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | Identity + behavior — what the skill is, what it does, how to run it |
+| `DISPLAY.json` | Presentation — how to render the skill in a UI |
+
+## Schema
+
+```jsonc
+{
+  "specVersion": "0.1.0",
+  "icon": "globe",
+  "image": "assets/cover.png",
+  "video": "assets/demo.mp4",
+  "tags": ["social", "automation"],
+  "integrations": ["x", "linkedin"]
+}
+```
+
+All fields are optional. A skill with no `DISPLAY.json` or an empty `{}` still works — it just gets default rendering.
+
+## Fields
+
+### `specVersion`
+
+- **Type:** `string`
+- **Format:** [Semantic Versioning 2.0.0](https://semver.org/)
+- **Description:** The version of this spec the file conforms to.
+
+```json
+"specVersion": "0.1.0"
+```
+
+### `icon`
+
+- **Type:** `string`
+- **Description:** Icon name for the skill in compact views (lists, cards). Use a [Lucide](https://lucide.dev/icons) icon name or a logo name from [Iconify](https://icon-sets.iconify.design/). Plain lowercase name — no prefixes, no file extensions.
+
+```json
+"icon": "globe"
+```
+
+```json
+"icon": "x"
+```
+
+### `image`
+
+- **Type:** `string`
+- **Description:** Cover image for the skill card. Relative path within the skill folder or an absolute URL.
+- **Allowed formats:** PNG, JPEG, WebP.
+- **Recommended:** 16:9 aspect ratio, minimum 800×450.
+
+```json
+"image": "assets/cover.png"
+```
+
+```json
+"image": "https://example.com/skills/my-skill/cover.jpg"
+```
+
+### `video`
+
+- **Type:** `string`
+- **Description:** Short demo or preview video. Relative path or absolute URL. When both `video` and `image` are present, `image` serves as the poster frame / fallback.
+- **Allowed formats:** MP4, WebM.
+- **Recommended:** 16:9 aspect ratio, 5–15 seconds.
+
+```json
+"video": "assets/demo.mp4"
+```
+
+### `tags`
+
+- **Type:** `string[]`
+- **Description:** Freeform tags for filtering and search. Lowercase, short, descriptive.
+
+```json
+"tags": ["social", "automation", "posting"]
+```
+
+### `integrations`
+
+- **Type:** `string[]`
+- **Description:** External services this skill interacts with. Used to show service badges alongside the skill. Plain lowercase slugs using the service's common name.
+
+```json
+"integrations": ["x", "linkedin", "gmail"]
+```
+
+## File placement
+
+```
+my-skill/
+├── SKILL.md          # Identity + behavior
+├── DISPLAY.json      # Presentation metadata (this spec)
+├── assets/
+│   ├── cover.png     # Referenced by "image"
+│   └── demo.mp4      # Referenced by "video"
+├── scripts/
+│   └── run.py
+└── references/
+    └── api-notes.md
+```
+
+## Example
+
+A minimal `DISPLAY.json`:
+
+```json
+{
+  "icon": "send",
+  "tags": ["social"]
+}
+```
+
+A fuller example:
+
+```json
+{
+  "specVersion": "0.1.0",
+  "icon": "globe",
+  "image": "assets/cover.png",
+  "video": "assets/demo.mp4",
+  "tags": ["social", "automation", "posting"],
+  "integrations": ["x", "linkedin"]
+}
+```
diff --git a/README.md b/README.md
index f4552a5..7f17f96 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,9 @@ Inside Zo, you can browse all the skills in this registry and install them for y
 If it's your own skill
 
 1. Add a new skill to the `Community` folder
-2. Run `bun validate` 
-3. Make a pull request
+2. Add a `DISPLAY.json` alongside your `SKILL.md` for UI presentation metadata (icon, tags, integrations, etc.) — see the [DISPLAY.json spec](DISPLAY.md)
+3. Run `bun validate` 
+4. Make a pull request
 
 If it's a skill you found, look it up in the [Agent Skills Registry](https://skills.sh)
 
@@ -35,6 +36,7 @@ slug="bird"; dest="Skills"; manifest_url="https://raw.githubusercontent.com/zoco
 - Skills live under `Zo/`, `External/`, or `Community/`, each containing a required `SKILL.md`.
 - Allowed subdirectories: `assets/`, `references/`, `scripts/`.
 - `SKILL.md` frontmatter must include `name`, `description`, and `metadata.author`.
+- `DISPLAY.json` alongside `SKILL.md` provides presentation metadata (icon, image, video, tags, integrations). See the [spec](DISPLAY.md) for the full schema.
 
 ## External Skills