Deck Management

Documents

deck-management

Deck Management is an Agent Skill for documents published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

How decks are stored in SQL, how to create/read/update/delete decks. Read before working with deck data.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/templates/slides/.agents/skills/deck-management/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/deck-management, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Deck Management

Decks are stored in the decks SQL table via Drizzle ORM. Each deck row contains the full deck JSON (slides, metadata) in a data TEXT column.

Schema

CREATE TABLE decks (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  data TEXT NOT NULL,       -- Full deck JSON (slides array, metadata)
  created_at TEXT DEFAULT (current_timestamp),
  updated_at TEXT DEFAULT (current_timestamp)
);

Deck JSON Structure

The data column stores a JSON object:

{
  "title": "My Presentation",
  "slides": [
    {
      "id": "slide-1",
      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
      "layout": "title"
    },
    {
      "id": "slide-2",
      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
      "layout": "content"
    }
  ]
}

Each slide has an id, HTML content, and optional layout type.

Reading Decks

From scripts:

# List all decks (metadata only)
pnpm action list-decks

# Get a specific deck with all slides
pnpm action get-deck --id=<deckId>

# See what the user is looking at
pnpm action view-screen

From the API:

GET /api/decks -- list all decks (returns id, title, slide count, timestamps)
GET /api/decks/:id -- get a single deck with full data

Writing Decks

From scripts:

# Use db-exec to insert/update
pnpm action db-exec --sql "INSERT INTO decks (id, title, data) VALUES (?, ?, ?)" --params '["new-id", "Title", "{...}"]'

From the API:

POST /api/decks -- create a new deck
PUT /api/decks/:id -- update an existing deck
DELETE /api/decks/:id -- delete a deck

Important Rules

Always use the API or Drizzle -- never write raw JSON files for deck storage
Deck IDs are stable -- once created, a deck's ID doesn't change
Slide IDs within a deck are stable -- used for referencing specific slides
The data column is the full source of truth -- title is duplicated at the top level for listing queries
SSE events (source: "resources") fire when decks change, keeping the UI in sync