blockpad-documents

A Claude Code skill for creating and editing Blockpad documents — .bpad files: live computational engineering documents that combine word‑processing, units‑aware equations, tables/spreadsheets, 2D drawings, and equation solvers, and that recompute when opened in the Blockpad desktop app.

The skill teaches Claude the .bpad XML format (reverse‑engineered from real Blockpad files and the official docs) so it can generate professional, presentable, accurate calculation documents from a prompt — or convert an existing Word/PDF/text/handwritten calculation into a live Blockpad document.

Generated from a one‑line prompt and opened in Blockpad: live units‑aware equations, Unicode symbols, automatic page numbering, and — further down the report — a labeled contact sketch and a rounded results table.

What it can do

• Engineering calc reports — named inputs, units‑aware <dynexp> equations, cross‑references, demand/capacity checks, headers/footers, numbered headings.
• Tables & spreadsheets — grids with live cell formulas, rounding, centering.
• 2D drawings — free‑body diagrams and section sketches from primitives (lines, arcs, rectangles, dimensions) with <planecontainer> text labels.
• Solver sections — systems of equations and non‑linear root finding.
• Conversion — turn a .docx / PDF / markdown / photo of hand calcs into a live Blockpad document, recomputing and reconciling every value.

Install

This is a user‑level skill for Claude Code.

Option A — drop‑in folder. Copy the skill into your Claude skills directory:

# macOS / Linux
cp -r blockpad-documents ~/.claude/skills/

# Windows (PowerShell)
Copy-Item -Recurse blockpad-documents "$env:USERPROFILE\.claude\skills\"

(Place SKILL.md and its references/, scripts/, assets/ folders inside ~/.claude/skills/blockpad-documents/.)

Option B — packaged file. Install the bundled blockpad-documents.skill through Claude Code's skill install flow.

Then just ask, e.g. "make a Blockpad calc sheet for a simply supported beam…" or "convert this PDF calc into a .bpad file."

Repository layout

Path	What it is
SKILL.md	The skill: workflow, presentation defaults, pitfalls checklist
references/document-structure.md	Document skeleton, reports, headings, styling, page setup, headers/footers, XML escaping & non‑breaking spaces
references/equations-units.md	<dynexp> equations, named values, units discipline, result formatting, fields
references/functions.md	Built‑in function catalog by category
references/tables-spreadsheets.md	Tables and spreadsheet grids
references/drawings.md	2D canvas primitives + <planecontainer> labels
references/solver-scripts.md	Solver sections, step‑by‑step sections, scripts
references/conversion.md	Converting existing documents into .bpad
scripts/validate_bpad.py	Static validator (XML + schema + known‑pitfall lint)
scripts/open_in_blockpad.py	Launch a .bpad in the Blockpad desktop app
assets/template.bpad	Polished starter document
evals/evals.json	Example test prompts used to develop the skill

Validating a generated file

python scripts/validate_bpad.py path/to/file.bpad

Checks XML well‑formedness, the <document> root, frame naming, unescaped formula characters, and a set of verified Blockpad pitfalls (wrong page‑count token, LaTeX‑style Greek that won't render, unit‑on‑rounding‑multiple errors, manual 2*pi on rpm/Hz, and missing non‑breaking spaces around inline elements). It is a static check — open the file in Blockpad for the real visual verification.

Notes

• Built and verified against Blockpad 1.8.x (.bpad schema version="1.8").
• Blockpad recomputes formulas on open, so a correct formula is the source of truth; cached results are for immediate display and self‑checking.
• This project is an independent, unofficial integration and is not affiliated with or endorsed by Blockpad.

License

MIT