Agents

How the skill works

The skill is a folder, blueprint-deck/, with a SKILL.md that tells the agent what to do, and the files it needs. Installed, it sits in your agent’s skills folder (e.g. ~/.claude/skills/blueprint-deck/SKILL.md, or inside the plugin); in the repository it lives at plugins/blueprint-deck/skills/blueprint-deck/.

file	what it is
SKILL.md	the instructions: modes, steps, rules
blueprint-deck.html	the engine with an empty data block; copied for every new diagram
reference/spec.md	the JSON format (Diagram format)
reference/style-guide.md	content, structure, viewpoint, layout and tour rules (Style guide)
reference/icons.md, reference/lucide-a-l.json, reference/lucide-m-z.json	the icon names, and every Lucide icon for extras
templates/diagram.config.yaml	the annotated config (Configuring)
templates/example.json	a finished example
tools/check.mjs	an optional command-line check (needs Node 18+, nothing to install)

The agent never writes HTML, CSS or JavaScript. It copies the engine, replaces the placeholder data block ({ "blueprintDeck": "empty" }) with the JSON it wrote, and never touches anything below the BD-ENGINE line. That keeps every deck consistent, keeps the agent’s work small, and makes the editor possible.

What it does on a first run:

1. Find the config: the path you gave, else diagrams/diagram.config.yaml, else diagram.config.yaml, or the config pasted into the prompt (it saves it first).
2. Read the sources the config lists, minus exclude; for big repos it may delegate reading to sub-agents. With derive_status_from it reads manifests to see what actually runs. With branding.website it takes the logo, colours and product name from your site.
3. Propose the structure (when workflow.confirm_structure is on): 5 to 9 areas, personas and their paths, the tabs, and the tour as one line per step. You correct it; it continues.
4. Write the content following the spec and the style guide. Every box and area gets sources.
5. Put it into the file and check it: with Node, node tools/check.mjs; with a browser tool, it opens the file, walks every tab, tour step, persona and sheet, and fixes what doesn’t fit. Without either it tells you to press E → Check.
6. Report: the output path, the structure and tour, conflicts and gaps, what it took from your website and what it could not verify. The details go into extraction-report.md.

Modes

The agent picks the mode from what you ask:

mode	when	what it does
generate	the first time, or /blueprint-deck <config>	the full run above
change	any change request on an existing file (“move X”, “add a persona”, “step 7 should …”, “lighter theme”)	edits the data block, re-checks, says what changed
update	the sources changed	re-reads the sources, changes only what changed, keeps manual edits and "locked": true boxes
upgrade	you want the newest engine in an existing file	copies the new engine and moves the old data block into it
init	no config exists yet	copies the template config, fills in what it can infer, asks you about audience, viewpoint and the tour story

Change requests are the normal way to iterate. Lasting preferences (“always say Acme Group”, “no moving dots”) are also written into the config so a later update keeps them.

Claude Code

Install the plugin from your terminal, in one command (Claude Code 2.1.275 or later):

claude plugin install blueprint-deck --marketplace lukasvecerka23/blueprint-deck-kit

Or from inside Claude Code:

/plugin install blueprint-deck --marketplace lukasvecerka23/blueprint-deck-kit

On older versions: /plugin marketplace add lukasvecerka23/blueprint-deck-kit, then /plugin install blueprint-deck@blueprint-deck-kit. The command is /blueprint-deck (the full name /blueprint-deck:blueprint-deck works too). To get updates automatically, turn on auto-update for the blueprint-deck-kit marketplace under /plugin → Marketplaces, or run claude plugin update blueprint-deck@blueprint-deck-kit. Install it one way only (plugin or script), otherwise Claude Code lists the skill twice.

Or with the script, for Claude Code only (the default command also finds Claude Code by itself):

curl -fsSL https://blueprintdeck.dev/install.sh | sh -s -- --agent claude

The skill lands in ~/.claude/skills/blueprint-deck; use --project to put it into the repository’s .claude/skills/ so the whole team gets it.

Start a new session in your project folder (a codebase or a folder of docs), then either paste the prompt from the configurator or use the slash command:

/blueprint-deck
/blueprint-deck diagrams/diagram.config.yaml

Claude Code also picks the skill on its own when you ask for “an interactive diagram of this repo” or “a blueprint of the platform for the board meeting”.

Codex

This repository is a plugin marketplace for Codex. In your terminal, add it and install the plugin:

codex plugin marketplace add lukasvecerka23/blueprint-deck-kit && codex plugin add blueprint-deck@blueprint-deck-kit

Updates come through the marketplace: codex plugin marketplace upgrade. Codex shares its plugins with the ChatGPT desktop app, so Blueprint Deck shows up there too (see Chat apps).

Without plugins, Codex’s own skill installer installs the skill from inside Codex:

$skill-installer install https://github.com/lukasvecerka23/blueprint-deck-kit/tree/main/plugins/blueprint-deck/skills/blueprint-deck

It installs the skill as it is on main into ~/.codex/skills/blueprint-deck and doesn’t update it later; the install script does both (--agent codex).

Start a new Codex session in your project folder and paste the prompt from the configurator, or ask:

Use the blueprint-deck skill to make a diagram of this repo from diagrams/diagram.config.yaml.

Gemini CLI

Gemini CLI has its own skill installer:

gemini skills install https://github.com/lukasvecerka23/blueprint-deck-kit --path plugins/blueprint-deck/skills/blueprint-deck

Or the script, into ~/.gemini/skills (Gemini CLI also reads ~/.agents/skills):

curl -fsSL https://blueprintdeck.dev/install.sh | sh -s -- --agent gemini

Check with /skills list in a Gemini CLI session, then ask for a Blueprint Deck in your project folder.

Chat apps: Claude, ChatGPT, Gemini

The chat apps and Claude’s desktop app need no terminal and no repository: you attach your docs to a chat. Most take the skill as a zip upload, once:

app	how
Claude (web and desktop app; paid plans)	Customize → Skills, upload blueprint-deck-skill.zip, turn it on. Code execution must be on (Settings → Capabilities), because the skill works with files.
ChatGPT on the web (paid plans)	Plugins → Skills → Create → Upload from your computer, the same zip. ChatGPT scans it before you can use it.
ChatGPT desktop app	It takes plugins, not uploads: install the Codex plugin (the app shares Codex’s plugins), or in the app Plugins → add the marketplace lukasvecerka23/blueprint-deck-kit, then install Blueprint Deck.
Gemini (web and desktop app)	Customize → Skills (some accounts: Settings → Skills), upload blueprint-deck-skill-gemini.zip: the same skill without the optional Node tools, which the Gemini app doesn’t accept.

Don’t unzip the files: they already have the shape the apps expect (one blueprint-deck/ folder with SKILL.md inside). Then start a chat, attach your docs (Markdown, PDF, text) or paste links, and ask: “Make a Blueprint Deck of these docs for our executives”. The skill asks for what it can’t tell from the files, then gives you the HTML file to download.

Share it as a link (Claude): after the deck is made, ask “Publish the deck as an artifact so I can share a link.” Claude puts it into an artifact and gives you a link anyone can open, without hosting anything. The deck works inside the artifact (tour, tabs, panels, switching diagrams, the PDF); your browser just can’t keep edits there, so edit the downloaded file and publish it again. Publishing makes the deck public to anyone with the link.

Differences from a coding agent: it only sees what you attach, not a whole repository, so it suits a handful of documents better than a large codebase. To change a deck later, attach the HTML file again and say what to change, or press E in the file. To update the skill, delete it and upload the newer zip.

Other agents (the install script)

Agents that support Agent Skills find the skill in their skills folder: --agent agents installs into the shared ~/.agents/skills, and --dir <path> into any folder. For an agent without skill support, put the folder somewhere it can read and start with:

Read blueprint-deck/SKILL.md and follow it. SKILL_DIR is the folder that file is in.
Then make a Blueprint Deck from diagrams/diagram.config.yaml.

Tips

• Keep workflow.confirm_structure: true for the first run. Most of a deck’s quality comes from the areas and their names, and correcting an outline is cheaper than correcting 30 boxes.
• Point sources.include at the docs that matter for this audience; less noise gives a clearer map.
• Write what the last version got wrong into comments. The agent treats every comment and note as an instruction.
• Big repos: agents with sub-agents read in parallel and hand back structured facts, which keeps the main context free.

Updating

When the skill runs, it asks GitHub for the latest release and tells you when a newer version is out (it never updates anything by itself). How to update depends on how you installed it:

installed with	to update
the Claude Code plugin	claude plugin update blueprint-deck@blueprint-deck-kit, or auto-update under /plugin → Marketplaces
the Codex / ChatGPT desktop plugin	codex plugin marketplace upgrade, or update it in the Plugins Directory
a zip upload (Claude, ChatGPT on the web, Gemini)	delete the skill and upload the newer zip
the install script, Codex’s skill installer or Gemini CLI	run the install script again: it replaces the skill and says which version it replaced

What changed is in the changelog. To install a specific release with the script:

curl -fsSL https://blueprintdeck.dev/install.sh | sh -s -- --version 2.1.0

In PowerShell:

$installer = irm "https://blueprintdeck.dev/install.ps1"
& ([scriptblock]::Create($installer)) -Version 2.1.0

Every release and its files are on GitHub Releases.

Diagrams you already made keep working: each file carries its own engine. To give a file the new features, ask your agent to upgrade it (or run node tools/insert.mjs --upgrade diagrams/index.html). The content stays as it is. The editor shows a file’s engine version under E → Diagram → This file.