Skill Directories: Portable Zap Recipe Capabilities

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

All recipe skill directories live under 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 Format

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.

The description field doubles as the tooltip shown in the studio UI and as the text the agent ranks against a user request.

Zap.md Format

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`

Example — 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

The manifest records each skill’s 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

The slug in the tool input must match the 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.

Legacy 0.3.1 Recipes

Core Concepts

Web App

Providers

Agent Framework

Deployment

Reference

Browser Use

Skill Directories: Portable Zap Recipe Capabilities

Directory Structure

SKILL.md Format

Zap.md Format

Skills Manifest

Available Registry Skills

`zap-world-cup-entrance`

`zap-caught-by-the-cam`

Saving a New Skill

​Directory Structure

​SKILL.md Format

​Zap.md Format

​Skills Manifest

​Available Registry Skills

​zap-world-cup-entrance

​zap-caught-by-the-cam

​Saving a New Skill

Directory Structure

SKILL.md Format

Zap.md Format

Skills Manifest

Available Registry Skills

`zap-world-cup-entrance`

`zap-caught-by-the-cam`

Saving a New Skill