system-drawings
A skill that lets any coding agent turn a system into an explorable set of three-dimensional technical drawings, in the manner of 1970s IBM and NASA documentation: a white sheet, black line-drawn solids, uppercase lettering, reference designators and a title block.
Readers do not scroll through a page. They:
- see the whole system first: every component and how the components talk;
- orbit, zoom and drag parts around to understand the arrangement;
- click a part for its data sheet (function, rationale, parameters, sources);
- open a subsystem into its own sheet, like going from the car to the engine to one cylinder;
- trace a request step by step as a marker travels the connections and a caption explains each step.
The output is one self-contained HTML file with no dependencies.
Examples
| Example | Sheets | Shows |
|---|
examples/automobile | 3 | Car → engine → one cylinder; traces for accelerating, starting, valve timing, and the four strokes |
examples/causal-delta | 9 | A research system for repairing regressions in fine-tuned models: a 52-plate decoder stack, live adapter dials, a concept figure, 11 traces |
examples/deep-space-1 | 9 | NASA's Deep Space 1: 78 components, 14 traces, spacecraft → ion propulsion → NSTAR mechanism, with NASA/JPL references |
Open any example's index.html directly in a browser.
Deep Space 1 demonstration
Watch the 38-second video (MP4, 5.4 MB, silent). It demonstrates orbit controls, subsystem navigation, the ion-acceleration trace and a sourced component data sheet. The example guide explains the sources and schematic limitations.
How it works
The agent writes content (drawing.json: sheets, parts, links, traces). The bundled engine renders it. Scripts keep the result honest:
S=skills/system-drawings
python3 $S/scripts/validate_drawing.py drawing.json # structure, sheet tree, spacing
python3 $S/scripts/build_drawing.py drawing.json -o out/index.html # single self-contained file
python3 $S/scripts/inspect_drawing.py out/index.html --out out/inspection # headless Chrome screenshots + layout audit
The full method is in skills/system-drawings/SKILL.md. Its references cover the design principles, the content schema, layout rules and verification.
Install
Agents that read ~/.agents/skills:
git clone [email protected]:3xC1ibR/system-drawings.git
ln -s "$PWD/system-drawings/skills/system-drawings" ~/.agents/skills/system-drawings
Claude Code: add this repository as a plugin marketplace (.claude-plugin/marketplace.json), or symlink the skill directory into ~/.claude/skills/.
Codex: the plugin manifest is .codex-plugin/plugin.json.
Requirements: Python 3.9+ (standard library only). inspect_drawing.py needs Chrome or Chromium; set CHROME_PATH if it is not found automatically.
Tests
python3 tests/run_tests.py # validation, build determinism, stale-example and negative checks
python3 tests/run_tests.py --render # also renders every example in headless Chrome
License
MIT
