nexu-io-open-design/docs/skills-protocol.md

Skills Protocol

Parent: spec.md · Siblings: skills-contributing.md · architecture.md · agent-adapters.md · modes.md

Want to ship a skill upstream rather than read the protocol spec? See skills-contributing.md — quick start, merge bar, PR template, common rejections. This file is the what (frontmatter grammar, discovery rules, mode semantics); that file is the how (clone to merged PR).

A Skill is the atomic unit of design capability in OD. We adopt Claude Code's SKILL.md convention verbatim as the base format, then add optional fields for design-specific features (preview type, input schema, slider parameters). A skill written for plain Claude Code runs in OD. An OD skill that doesn't use our extensions runs in plain Claude Code.

Compatibility promise: A skill like guizang-ppt-skill works in OD without modification. It just drops into ~/.claude/skills/ and OD discovers it.

---

1. Base format (unchanged from Claude Code)

Every skill is a directory containing at minimum a SKILL.md:

<skill-root>/
├── SKILL.md              # manifest + workflow instructions
├── assets/               # templates, images, boilerplate the skill writes
│   └── …
└── references/           # knowledge files the skill reads during planning
    ├── components.md
    ├── layouts.md
    └── …

SKILL.md front-matter (YAML):

---
name: magazine-web-ppt
zh_name: "杂志风网页 PPT"
en_name: "Magazine Web PPT"
description: |
  Magazine-style horizontal-swipe web deck.
  Trigger keywords: 杂志风 PPT, magazine deck, swipe slides.
zh_description: "杂志风横向翻页网页 PPT。"
en_description: |
  Magazine-style horizontal-swipe web deck.
  Trigger keywords: 杂志风 PPT, magazine deck, swipe slides.
triggers:
  - "magazine deck"
  - "杂志风 PPT"
  - "horizontal swipe presentation"
---

Body is free-form Markdown that describes the workflow the agent should follow — typically a numbered step list plus principles. This is what guizang-ppt-skill does.

OD reads all of this as-is. No changes required.

2. OD extensions (optional)

Skills can declare additional front-matter fields to unlock OD-specific UI. All fields are optional; absent fields fall back to sensible defaults.

---
name: magazine-web-ppt
description: …
triggers: […]

# --- OD extensions below this line ---

od:
  mode: deck                        # one of: prototype | deck | template | design-system
  preview:
    type: html                      # html | jsx | pptx | markdown
    entry: index.html               # relative path produced by the skill
    reload: debounce-100            # how the preview refreshes
  example_prompt: "Create a magazine-style web deck from my content."
  example_prompt_i18n:
    zh-CN: "用杂志风网页 PPT 模板把我的内容做成横向翻页 deck。"
  design_system:
    requires: true                  # this skill reads the active DESIGN.md
    sections: [color, typography]   # which sections it actually uses (for prompt pruning)
  craft:                            # universal, brand-agnostic craft references
    requires: [typography, color, anti-ai-slop]
  inputs:                           # typed inputs the user can fill in the UI
    - name: title
      type: string
      required: true
    - name: slide_count
      type: integer
      default: 8
      min: 4
      max: 20
    - name: theme
      type: enum
      values: [editorial, minimal, brutalist, dark-glass, warm]
      default: editorial
  parameters:                       # live-tweakable sliders after first generation
    - name: accent_hue
      type: hue                     # hue | spacing | font-scale | opacity
      default: 18
      range: [0, 360]
    - name: section_spacing
      type: spacing
      default: 48
      range: [16, 128]
  outputs:
    primary: index.html
    secondary: [slides.json]        # for PPTX export
  capabilities_required:
    - surgical_edit                 # comment mode needs this
    - file_write
---

2.1 What OD uses each field for

Field	Used by
zh_name / en_name	localized picker title; falls back to name
zh_description / en_description	localized picker description; falls back to description
od.mode	routing (which mode picker the skill shows up under)
od.preview.type	picking the right iframe renderer
od.example_prompt	English fallback starter prompt used by picker CTA
od.example_prompt_i18n	localized starter prompt map (for example zh-CN)
od.design_system.requires	whether to inject DESIGN.md
od.design_system.sections	pruning the injected DESIGN.md to relevant sections only (token savings)
od.craft.requires	which brand-agnostic craft/<slug>.md references to inject (e.g. typography, color, anti-ai-slop); injected between DESIGN.md and the skill body
od.inputs	rendering a typed form in the sidebar instead of only free-text
od.parameters	rendering live sliders that re-prompt on change
od.outputs.primary	which file the iframe loads
od.outputs.secondary	which files export pipelines read (e.g. slides.json for PPTX)
od.capabilities_required	gating: if the active agent lacks surgical edit, comment mode is disabled for this skill

2.2 If a skill omits od: entirely

Defaults:

• mode: inferred from name/description (best-effort keyword match) or "prototype"
• preview.type: sniff for *.html → html, *.jsx → jsx, else "markdown"
• preview.entry: first file matching the sniffed type
• design_system.requires: true if the skill body mentions "design system" or "DESIGN.md"
• inputs, parameters: none (free-text prompt only)

The goal: zero-config compatibility for existing Claude Code skills.

3. Skill discovery & precedence

The daemon's skill registry scans three locations:

Location	Priority	Purpose
./.claude/skills/	1 (highest)	project-private skills, not committed
./skills/	2	project-committed skills
~/.claude/skills/	3	user-global skills

Conflicts by name resolve to the higher-priority version. All locations are watched with chokidar in dev and re-scanned on SIGHUP in production.

Symlink strategy (borrowed from cc-switch)

cc-switch maintains a central skill dir and symlinks it into each agent's expected location (~/.claude/skills/, ~/.codex/skills/, etc.). OD can opt into the same model, but this protocol MUST NOT define Open Design daemon data paths. Read the root AGENTS.md section Daemon data directory contract before changing or documenting any Open Design-owned storage location.

One install → every agent sees the skill. This is optional; users who only use one agent don't need it.

4. Skill types (by mode)

Each mode expects a slightly different skill shape. The required outputs and expected workflow differ.

4.1 prototype-skill

• Purpose: single-screen interactive prototype.
• Preview: html or jsx.
• Primary output: index.html or Prototype.jsx.
• Typical workflow: clarify brief → resolve design tokens → write component tree → write file.
• Example skills: saas-landing, dashboard, login-flow, empty-states.

4.2 deck-skill

• Purpose: multi-slide presentation.
• Preview: html (single-file deck with in-page navigation).
• Primary output: index.html.
• Secondary output: slides.json (for PPTX export).
• Typical workflow: clarify topic + slide count → pick theme → populate slides from layout catalog → self-check against quality rubric.
• Reference implementation: guizang-ppt-skill — fork this for v1.

4.3 template-skill

• Purpose: start from a pre-built artifact; agent only personalizes content, doesn't design from scratch.
• Preview: inherits from the template bundle (html typically).
• Primary output: a populated copy of the template.
• Typical workflow: copy assets/template/ to artifact dir → replace content placeholders → optionally tweak tokens to match design system.
• Why separate from prototype-skill: much faster (no design decisions), higher-quality floor, worse ceiling.

4.4 design-system-skill

• Purpose: produce a DESIGN.md from inputs (brand brief, screenshot, URL).
• Preview: markdown (render the resulting DESIGN.md with a sample-components preview).
• Primary output: DESIGN.md.
• Typical workflow: analyze input → draft 9 sections per awesome-claude-design schema → generate sample component preview → finalize.
• Post-run: OD prompts the user to set this DESIGN.md as the project's active design system.

5. The DESIGN.md as skill context

Every non–design-system skill (modes 1–3) can consume the active DESIGN.md. OD injects it as:

1. System-prompt prefix (required sections only, per od.design_system.sections).
2. File available in CWD named DESIGN.md — skills can Read it directly via their agent.
3. Template variable {{ design_system }} if the skill body references it in Mustache-style.

The 9-section DESIGN.md format is not invented by OD; it's the awesome-claude-design convention, reproduced here for convenience:

# <Brand Name>

## Visual Theme & Atmosphere
## Color Palette & Roles
## Typography Rules
## Component Stylings
## Layout Principles
## Depth & Elevation
## Do's and Don'ts
## Responsive Behavior
## Agent Prompt Guide

Example: docs/examples/DESIGN.sample.md.

5.5 Craft references (craft/)

Some craft knowledge is universal — true regardless of brand. ALL CAPS always needs ≥0.06em letter-spacing; var(--accent) should appear at most 2 times per screen; #6366f1 is always the AI-default tell. These rules don't belong in any one DESIGN.md because they apply across every brand.

OD ships these as a third axis at <projectRoot>/craft/:

craft/
├── README.md
├── typography.md
├── color.md
└── anti-ai-slop.md

A skill opts in by listing the slugs it needs:

od:
  craft:
    requires: [typography, color, anti-ai-slop]

Resolution at compose time:

1. apps/daemon/src/skills.ts reads od.craft.requires from front-matter and surfaces it on the skill record.
2. apps/daemon/src/craft.ts reads each <slug>.md from CRAFT_DIR. Missing files are dropped silently — a skill can forward-reference craft/motion.md before we ship it. See craft/README.md for the canonical slug list and the rationale behind the silent-fallback choice.
3. apps/daemon/src/prompts/system.ts injects the concatenated craft body between the active DESIGN.md and the skill body. Brand tokens in DESIGN.md win on conflict; craft rules cover everything DESIGN.md does not override.

The split keeps DESIGN.md authors free of universal-craft duplication and keeps craft authors free of brand-specific drift.

6. Skill installation

od skill add https://github.com/op7418/guizang-ppt-skill
# → installs into daemon-managed storage; read root AGENTS.md -> "Daemon data directory contract" before documenting paths
# → symlinks into ~/.claude/skills/ (and any other active agent dirs)
# → re-indexes registry

od skill add ./path/to/my-skill
# → symlinks local dir (no copy) into skills registry

od skill list
# → table: name, mode, source, agent compatibility

od skill remove <name>
# → unlinks; does not delete the source

7. Worked example — running guizang-ppt-skill under OD

The skill is unchanged. Here's the full path:

1. User: od skill add https://github.com/op7418/guizang-ppt-skill
2. Registry indexes it. No od: block in front-matter → defaults applied:
   • mode: inferred from body mentioning "PPT" → deck.
   • preview.type: sniffed from assets/template.html → html.
   • preview.entry: index.html (convention).
   • design_system.requires: false (skill body doesn't mention DESIGN.md).
3. User switches to deck mode in the web UI; skill appears in the skill picker.
4. User types "给我做一份杂志风 8 页投资人 PPT".
5. Daemon dispatches to active agent (Claude Code) with:
   • system message: skill's SKILL.md body
   • cwd: daemon-managed artifact workspace. This protocol MUST NOT define daemon data paths; read root AGENTS.md -> Daemon data directory contract before changing or documenting artifact storage.
   • files already placed in cwd: template.html (from skill's assets/)
6. Agent runs its 6-step workflow (clarify → copy template → populate → self-check → preview → refine).
7. OD streams the agent's tool calls as UI events; artifact dir grows.
8. Agent signals done; daemon sets preview iframe to index.html.
9. User clicks "Export PPTX" — export pipeline notices the skill has no slides.json output (the upstream skill doesn't produce one). OD falls back to "print to PDF then page-to-slide PPTX," which is uglier but works. This is a known limitation documented per-skill.

8. Writing a new skill — minimal example

saas-landing-skill/
├── SKILL.md
└── assets/
    └── base.html

---
name: saas-landing
description: |
  Produce a single-page SaaS landing with hero, features, social proof, pricing, CTA.
  Trigger: "saas landing", "marketing page", "product landing".
triggers:
  - "saas landing"
  - "marketing page"
od:
  mode: prototype
  preview:
    type: html
    entry: index.html
  design_system:
    requires: true
    sections: [color, typography, layout, components]
  inputs:
    - name: product_name
      type: string
      required: true
    - name: tagline
      type: string
      required: true
    - name: has_pricing
      type: boolean
      default: true
  parameters:
    - name: hero_density
      type: spacing
      default: 96
      range: [48, 200]
---

# Workflow

1. Read DESIGN.md from cwd. Adopt its color/typography/layout rules.
2. Copy `assets/base.html` to `index.html` in cwd.
3. Fill sections: hero, features (3–6), social proof, pricing (if `has_pricing`), CTA, footer.
4. Inline all CSS. Use system font stack as fallback if DESIGN.md typography fails to load.
5. Respect `hero_density` parameter as the hero section's vertical padding in px.
6. Write `index.html`. Done.

9. Testing skills

A skill ships with optional test inputs that OD uses for CI:

<skill-root>/
└── tests/
    ├── basic.prompt
    ├── basic.expected.manifest.json   # assertions: files produced, preview.type, etc.
    └── basic.expected.regex.txt       # text regex assertions against the primary output

od skill test <name> runs the skill against each case using a cheap model (e.g. Haiku 4.5) and asserts on the manifest + regex. Low-fidelity but catches structural regressions.

10. Open questions

• Skill signing. Can we verify a skill hasn't been tampered with between publish and install? Simplest answer: od skill add records the git commit SHA; reinstall-on-update warns on signature change. Deferred to v1.
• Skill composition. Can a prototype-skill call a deck-skill for a sub-artifact? Not in v1; skills are leaf-level. Composition would require a meta-skill concept, which is speculative.
• Parameter stability. When sliders change, should the agent re-plan or just re-render? Lean: re-render (fast path), with an "also re-plan" button for larger changes.