Build a skill
Write a Markdown skill that teaches an outside agent to drive your Zeph — with prefab screens it can push.
A skill is one Markdown file, SKILL.md, that teaches an agent a task and how to do it with your Zeph. Scaffold it, write the recipes, carry a few prefab screens, and it installs into Claude Code, Cursor, or Claude Desktop next to their other skills.
You don't build a runtime here. You write instructions the agent reads when it needs them, and hand it screens it can push to the device verbatim.
Scaffold the package
just skill-new my-skillYou get a package: a SKILL.md and a screens/ folder. Names are lowercase letters, digits, and hyphens.
Declare the zeph frontmatter
The frontmatter names the skill, says when an agent should reach for it, and carries a zeph block:
---
name: my-skill
description: One sentence — what this skill does and when an agent should use it.
metadata:
zeph:
device: false
version: 0.1.0
requires: ["zeph-device@^1"]
---device: false marks a domain skill — one that teaches a task. It leans on the base zeph-device skill for the device protocol, which it names in requires.
Write the recipes
The body is plain Markdown: concrete tool-call sequences and the zui trees the task needs. Keep it to the domain — the deploy flow, the report layout, the round trip that matters for your job.
Carry prefab screens
Drop finished zui documents in screens/*.json. The agent pushes them verbatim with push_screen or notify — no composing at runtime, no guessing at fields:
{ "k": "screen", "lyt": 1, "c": [
{ "k": "eyebrow", "t": "BUILD" },
{ "k": "big", "t": "Green" },
{ "k": "gap", "h": 8 },
{ "k": "text", "t": "412 tests passed" }
] }Check, then build the catalog
bun run check:skills # validate the package
just skills-build # render every screen + build the indexThe build renders each screen through the device simulator. A screen that doesn't render on a real board cannot ship.
You don't re-teach the protocol
The base zeph-device skill already teaches the MCP tools, the pushed-UI tree, and the button round trip. Your skill declares requires: ["zeph-device@^1"] and carries only the recipes on top — so it stays short, and the device details it depends on move in one place.
What an app can bring
A device app's package can ship its own skills — the instructions that teach an agent to drive it. They land in the library marked with the app that added them, and install into whichever agent you point them at.
How a skill is trusted
Skills publish as a signed catalog, not loose files. The companion verifies the catalog's index.json against a pinned key before it trusts any entry. Installing copies the SKILL.md and its screens/ into the client's skills directory; nothing runs at install time — the agent reads the file when the task calls for it.