A skill directory is the deployable unit of Zap. It contains everything an agent or creator needs to discover, understand, and run a recipe — the agent-facing description, the executable recipe metadata, and all prompt files. Because the skill directory is self-contained, it can be versioned, shared, and installed without any other context.
Directory Structure
agent/skills/zap-<slug>/
SKILL.md # agent-facing description and trigger phrase
Zap.md # recipe frontmatter + prose creative context
prompts/ # prompt files referenced from steps
initial-frame.md
initial-gen.md
agent/skills/ and follow the zap-<slug> naming convention. The slug must be lowercase alphanumeric with hyphens — it is the identifier passed to run_zap and zap run.
SKILL.md is the entry point the Eve agent reads when deciding whether to use a skill. Its YAML front matter declares a description that the agent uses for skill selection, and the body explains the recipe at a high level and tells the agent which tool to use and when.
Example — zap-world-cup-entrance/SKILL.md:
---
description: World Cup player-entrance highlight reel from a selfie. Load when the user wants a cinematic stadium intro Zap or asks to run world-cup-entrance.
---
# World Cup Entrance Zap
Executable recipe frontmatter lives in sibling `Zap.md`; this Eve skill keeps
the recipe discoverable through progressive disclosure.
Use `run_zap` with slug `world-cup-entrance` for deterministic creator runs.
Use the prompt files in `prompts/` when authoring or revising the recipe.
description field doubles as the tooltip shown in the studio UI and as the text the agent ranks against a user request.
Zap.md carries YAML frontmatter that is the executable recipe definition, followed by a prose body that provides creative direction for the agent and any human reviewing the recipe.
Key frontmatter fields:
| Field | Description |
|---|
zap | Recipe slug — must match the directory name suffix |
version | Integer version for the recipe |
description | Human-readable summary |
inputs | Declared input parameters with type, required, and hint |
defaults | Default provider and aspect ratio |
budget.estimate_usd | Expected cost for a standard run |
budget.cap_usd | Hard spend cap — the agent stops here |
steps | Ordered list of pipeline steps (see concepts/steps) |
output | Final output filename, typically Zap.mp4 |
zap-world-cup-entrance/Zap.md:
---
zap: world-cup-entrance
version: 1
description: World Cup player-entrance highlight reel from a selfie. Use when the user wants a cinematic stadium intro video of themselves.
inputs:
image:
type: image
required: true
hint: clear front-facing selfie
NAME:
type: string
required: true
label: Player name
COUNTRY:
type: string
required: true
label: Country
NO:
type: string
required: true
label: Jersey number
defaults:
provider: gmi
aspect: "16:9"
budget:
estimate_usd: 7.5
cap_usd: 15
steps:
- id: sketch
kind: image.edit
tier: draft
model: fal-ai/flux/dev
provider: fal
inputs: [user.image]
prompt: prompts/initial-frame-a.md
- id: character_sheet
kind: image.edit
tier: final
model: fal-ai/flux/dev
provider: fal
inputs: [sketch]
prompt: prompts/initial-frame-b.md
- id: initial_gen
kind: video.gen
tier: final
candidates: 1
model: seedance-2-0-260128
provider: gmi
duration_s: 15
reference_images: [character_sheet]
prompt: prompts/initial-gen.md
judge:
enabled: true
criteria: [identity_consistency, pacing, prompt_adherence]
rlhf: optional
- id: extend
kind: video.extend
tier: final
model: seedance-2-0-260128
provider: gmi
duration_s: 15
repeat:
min: 0
max: 64
default: 0
extend:
mode: chain
first_frame:
from: prev.last_frame
upscale: 4k
keyframes:
mode: optional
prompt: prompts/extend-gen.md
- id: finalize
kind: stitch
inputs: [initial_gen, extend.*]
stitch:
engine: auto
format: mp4
quality: standard
audio:
mix: keep
output: Zap.mp4
---
# World Cup Entrance
Premium sports-broadcast aesthetic: night stadium, floodlights, tunnel fog,
low-angle hero tracking, broadcast graphics, and confident player-introduction
energy. Face consistency is the acceptance bar; if the judge scores identity
below 0.7, regenerate the character sheet before animating.
Skills Manifest
skills/skills-manifest.json is generated by the zap skills command and tracks the file count and a content hash for each bundled skill. The runtime uses this file to verify skill integrity before a run.
Generate or check the manifest:
# Regenerate the manifest after adding or editing skills
zap skills generate
# Verify that skill files match their recorded hashes
zap skills check
path, skill slug, fileCount, and a SHA-256 hash. If a hash mismatch is detected by zap skills check, the affected skill directory should be treated as dirty and regenerated or restored before running.
Available Registry Skills
The Zap bundled registry ships with two ready-to-use recipe skills. Install either with zap add <name>:
zap-world-cup-entrance
Cinematic World Cup player-entrance highlight reel generated from a selfie. Inputs: a front-facing image, player name, country, and jersey number. Budget estimate: 7.50∗∗,cap:∗∗15. Primary provider: GMI.
zap add zap-world-cup-entrance
zap-caught-by-the-cam
Live-broadcast fan cutaway where the uploaded person is caught by the stadium camera with scoreboard and stats overlays. Inputs: fan photo plus match context (teams, score, period, time, stats). Budget estimate: 4.50∗∗,cap:∗∗10. Primary provider: fal.
zap add zap-caught-by-the-cam
Saving a New Skill
The agent uses the save_zap tool to compile a successful authoring trajectory into a packaged skill. save_zap always requires explicit user approval before writing to disk.
save_zap({ slug: "my-recipe", markdown: "<full Zap.md content>" })
-> writes agent/skills/zap-my-recipe/Zap.md
-> writes agent/skills/zap-my-recipe/SKILL.md
zap: field declared in the frontmatter, or the tool throws a mismatch error.
Run zap validate and zap lint after every recipe edit. validate checks that frontmatter is schema-valid; lint catches common authoring mistakes such as missing prompt files, undefined step references, and budget fields set below provider minimums.
