SKEL — Story Keyframe Extensible Layout

v2.10 | An open storyboard data format

A flat, relational YAML format for encoding visual narratives into machine-readable, validatable story data.

OpenSKELETON — Official Format Site · Genlock Studio — Create with SKEL · SKEL X-Ray — Free Format Viewer

SKEL Ecosystem

| | Product | Purpose | |---|---|---| | Create | Genlock Studio | A first-class desktop studio for authoring storyboards and visual narratives with SKEL as its native story format. | | View | SKEL X-Ray | A free web viewer for opening and inspecting SKEL format files. | | Learn | OpenSKELETON | The official home of the SKEL format, documentation, ecosystem, and releases. |

What Is SKEL?

SKEL (Story Keyframe Extensible Layout) is an open format that represents screenplays, storyboards, and visual narratives as flat, relational data. The native authoring format is YAML (.skel); .skel.json is the JSON export/interchange form of the same data model. Instead of deeply nested trees, SKEL stores acts, scenes, and shots as top-level arrays linked by ID references — like a relational database for stories.

SKEL is the native story format of Genlock Studio, the desktop storyboard studio, and is designed to be read and written by any tool. You can inspect SKEL files without installing a desktop application using the free SKEL X-Ray viewer.

Designed for:

• AI-driven image/video generation pipelines (Flux, Kling, Runway, WAN, etc.)
• Storyboard authoring tools
• Cross-tool interchange between screenplay editors and production software

Spec

| File | Contents | |---|---| | spec/skel-spec.md | Formal specification | | spec/bone-spec.md | BONE data plugin system specification | | spec/muscle-spec.md | MUSCLE behavior plugin system specification | | spec/studio-spec.md | Studio registry (studio.json) — the story bible: characters, environments, props, voices, skins, series | | spec/skel.schema.json | JSON Schema (Draft 7) for validating .skel.json files | | spec/bone.schema.json | JSON Schema for validating .bone.json files | | spec/muscle.schema.json | JSON Schema for validating .muscle.json manifests | | spec/studio.schema.json | JSON Schema for validating studio.json registries | | spec/genlock-studio.schema.json | Genlock 1.0 runtime registry at .genlock/studio.json (distinct from portable studio.json) | | spec/host-profile.schema.json | Machine-readable host storage, version, schema, and conformance declaration | | spec/hook-payload.schema.json | Hook invocation contract (envelope/result shapes for MUSCLE hooks) | | spec/errors.md | Normative validation error catalog (stable codes, severities, RFC 6901 paths) | | spec/MUSCLE_AUTHORING.md | How to write a MUSCLE plugin, step by step | | spec/muscles/ | Example MUSCLE manifests: studio-style-guard, fountain-adapter, continuity-guard | | reference/muscle-host/ | Runnable reference host — discovery, hook invocation, capability-checked patch application | | reference/cli/ | Reference skel CLI — validate / convert / inspect (npx @openskeleton/cli validate story.skel) | | reference/fountain-adapter/ | Working Fountain round-trip adapter (ADR-016 proof) with byte-identical round-trip test | | spec/skel-keyfile.json | Default token dictionary (13 categories, 131 tokens) | | spec/example.skel.json | Complete working example (JSON export form) — "The Last Signal" | | spec/example.skel | The same example in native YAML, annotated — start here to read SKEL | | spec/examples/ | Kitchen-sink example (full asset layer) + episodic pair sharing one studio.json | | spec/bones/ | Starter BONE definitions: flux-dev, runway-gen3, kling-v1, seedance-2, character-reference-sheet, storyboard-grid-9 | | spec/x-genlock.schema.json | Schema for Genlock-owned x-genlock extension data (proposals, frame images) | | spec/GENLOCK_HOST_PROFILE.md | How Genlock Studio maps the neutral spec onto its storage (the model for writing your own host profile) | | profiles/genlock/profile.json | Current machine-readable Genlock implementation profile and conformance status | | spec/MIGRATIONS.md | Every rename and structural change, with migration paths and sunsets | | spec/PACKAGING.md | npm package contents, host integration, vendored-sync transition, and release verification | | spec/audio-map.schema.json | Schema for the audio-map.json sidecar (shot → audio track assignments) | | spec/video-map.schema.json | Schema for the video-map.json sidecar (shot → video takes) | | spec/canvas-layout.schema.json | Schema for the canvas-layout.json sidecar (canvas node positions) | | spec/TOKEN_REFERENCE.md | All valid tokens, defaults, and constraints at a glance | | spec/LLM_INTEGRATION.md | How LLM agents read, edit, and validate SKEL projects | | docs/NEXT-GENERATION-PRODUCTION-ROADMAP.md | Proposed sequence contracts, typed references, take lineage, OTIO, production packages, and the SKEL/BONE/MUSCLE ownership boundary | | spec/ARCHITECTURE.md | System architecture and data flows | | spec/DECISIONS.md | Architecture Decision Records | | spec/CHANGELOG.md | Version history | | spec/OVERVIEW.md | Quick orientation | | tests/conformance/ | Conformance corpus: valid/invalid fixtures with expected error codes | | registry/ | Community registry of public BONE/MUSCLE ids |

Quick Start

Validate a document with the reference CLI:

npx @openskeleton/cli validate story.skel        # or: node reference/cli/skel.mjs validate story.skel
skel validate story.skel --lifecycle export --json --with-sidecars
skel convert story.skel story.skel.json          # YAML ⇄ JSON
skel inspect story.skel                          # structure, cast, coverage at a glance

Get live validation + token autocomplete in VS Code by starting your .skel file with the modeline:

# yaml-language-server: $schema=https://raw.githubusercontent.com/brandflowr/SKELETON-Brandflowr/v2.10.0/spec/skel.schema.json
skel_version: "2.0"

Repo health: npm install && npm run check validates every shipped artifact, runs the conformance corpus, the MUSCLE host demo, and the Fountain round-trip — the same suite as CI.

Conformance

Implementations claim classes — Reader, Writer, Validator, Full Host — defined in spec/skel-spec.md §9, and self-certify against tests/conformance/. Use of the SKEL/BONE/MUSCLE marks is conditioned on conformance (TRADEMARKS.md). Spec changes follow GOVERNANCE.md; security reports follow SECURITY.md.

Plugin System

SKEL has a two-layer plugin system, following the skeleton metaphor:

• BONE (Base Object Narrative Export) — data plugins. A .bone.json file attaches AI generation config, prompt contracts, and pipeline data to SKEL entities. See spec/bone-spec.md and the starter definitions in spec/bones/.
• MUSCLE (Modular User-Scripted Companion Logic Extension) — behavior plugins. A .muscle.json manifest subscribes to named lifecycle hooks (import, validation, prompt assembly, generation, render write-back, export) and returns JSON patches that the host validates and applies atomically. MUSCLEs never touch documents directly. See spec/muscle-spec.md.

.skel is the body layout, .bone files are what attaches to it, .muscle files are what makes it move.

Want to build a plugin? Start with spec/MUSCLE_AUTHORING.md, copy an example from spec/muscles/, and test against the reference host:

cd reference/muscle-host/demo && node run-demo.mjs

License

MIT — see LICENSE.

Copyright © 2025–2026 Brandflowr AI LLC.

SKEL™, BONE™, MUSCLE™, and SPORE™ are trademarks of Brandflowr AI LLC — see TRADEMARKS.md.