# Framevideo Registry

> Install and wire registry blocks and components into FrameVideo compositions. Use when running framevideo add, installing a block or component, wiring an installed item into index.html, or working with framevideo.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

- Skill: `chanjing-ai/framevideo-registry` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add chanjing-ai/framevideo-registry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chanjing-ai/framevideo-registry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: chanjing-ai (https://skillmd.com/u/chanjing-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chanjing-ai/framevideo-registry

---


# FrameVideo Registry

## When To Use

Use this skill for:

- **Installing blocks** — `framevideo add <block-name>` to install reusable compositions
- **Installing components** — `framevideo add <component-name>` for effect snippets
- **Wiring blocks** — integrate installed blocks into host composition
- **Merging components** — paste component snippets into existing HTML
- **Registry discovery** — find available blocks/components
- **Configuration** — manage `framevideo.json` registry settings

## Do NOT Use

Avoid this skill for:

- **Example templates** — use `framevideo init --example <name>` instead
- **Writing custom compositions** — use `framevideo` skill
- **Asset preprocessing** — use `framevideo-media`
- **CLI commands (init, render, etc.)** — use `framevideo-cli`

---

## Quick Start

### Install and wire a block

```bash
# 1. Install block
npx framevideo add data-chart

# 2. Wire into host composition (index.html)
<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="5"
  data-track-index="3"
></div>
```

### Install and merge a component

```bash
# 1. Install component
npx framevideo add grain-overlay

# 2. Copy snippet from CLI output
# 3. Paste into your composition HTML
# Component snippets merge directly into HTML (no data-composition-src)
```

---

## Block vs Component

| Type | Description | Install location | How to use |
|------|-------------|------------------|------------|
| **Block** | Standalone sub-composition | `compositions/<name>.html` | Include via `data-composition-src` |
| **Component** | Effect snippet | `compositions/components/<name>.html` | Paste directly into HTML |

---

## When to use this skill

- User mentions `framevideo add`, "block", "component", or `framevideo.json`
- Output from `framevideo add` appears in the session (file paths, clipboard snippet)
- You need to wire an installed item into an existing composition
- You want to discover what's available in the registry

## Quick reference

```bash
framevideo add data-chart              # install a block
framevideo add grain-overlay           # install a component
framevideo add shimmer-sweep --dir .   # target a specific project
framevideo add data-chart --json       # machine-readable output
framevideo add data-chart --no-clipboard  # skip clipboard (CI/headless)
```

After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add `data-composition-id` (must match the block's internal composition ID), `data-start`, and `data-track-index` attributes when wiring blocks.

Note: `framevideo add` only works for blocks and components. For examples, use `framevideo init <dir> --example <name>` instead.

## Install locations

Blocks install to `compositions/<name>.html` by default.
Components install to `compositions/components/<name>.html` by default.

These paths are configurable in `framevideo.json`:

```json
{
  "registry": "https://raw.githubusercontent.com/chanjing/framevideo/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}
```

See [install-locations.md](./references/install-locations.md) for full details.

## Wiring blocks

Blocks are standalone compositions — include them via `data-composition-src` in your host `index.html`:

```html
<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>
```

Key attributes:

- `data-composition-src` — path to the block HTML file
- `data-composition-id` — must match the block's internal ID
- `data-start` — when the block appears in the host timeline (seconds)
- `data-duration` — how long the block plays
- `data-width` / `data-height` — block canvas dimensions
- `data-track-index` — layer ordering (higher = in front)

See [wiring-blocks.md](./references/wiring-blocks.md) for full details.

## Wiring components

Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):

1. Read the installed file (e.g., `compositions/components/grain-overlay.html`)
2. Copy the HTML elements into your composition's `<div data-composition-id="...">`
3. Copy the `<style>` block into your composition's styles
4. Copy any `<script>` content into your composition's script (before your timeline code)
5. If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline

See [wiring-components.md](./references/wiring-components.md) for full details.

## Discovery

Browse available items:

```bash
# Read the registry manifest
curl -s https://raw.githubusercontent.com/chanjing/framevideo/main/registry/registry.json
```

Each item's `registry-item.json` contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.

See [discovery.md](./references/discovery.md) for details on filtering by type and tags.