Describe a system in a few lines of JSON, or just ask your AI agent, and penciled draws it the way a person with a pencil would: graphite grain, hatched shading, corners that overshoot. It lays itself out and checks its own work.
npx skills add himanshu13ps/penciledHow it works
One paragraph in, a finished sketch out. In between, the agent writes the diagram, penciled checks how it will actually look, and the agent fixes what the check found.
This is a real run, not a mock-up: Claude followed the skill's instructions on the request above. The JSON and the validator's reports are shown exactly as produced; the files are in docs/replay.
The look
penciled models how a pencil behaves on paper, stroke by stroke. Every close-up below is cropped from a drawing rendered live on this page.
Features
A diagram is nodes, the groups around them and the arrows between them. Shapes carry meaning, so readers know a database from a service at a glance. Open any card to see the JSON behind it.
| Field | Values | Notes |
|---|---|---|
title | text, up to 80 characters | Handwritten at the top of the page |
direction | LR or TB | Main flow for automatic layout |
nodes[].id | letters, digits, _, - | Never drawn; unique across nodes and groups |
nodes[].label | text, up to 60 characters | \n for a line break |
nodes[].sublabel | text | Smaller second line, e.g. the technology |
nodes[].shape | box rounded database queue person cloud document | Default box |
nodes[].shade | none light medium dark | Draws the eye; use on one or two nodes |
nodes[].group | a group id | The outline the node sits inside |
nodes[].position | { x, y } | Optional; give every node one or none |
groups[] | id, label, parent, shade | Dashed outlines; parent nests them |
edges[] | from, to, label, style, arrow | style: solid or dashed; arrow: end, start, both, none |
paper | style, texture, pencil, eraserMarks, seed | See “Make it your own” |
| Limits | 40 nodes, 12 groups, 80 arrows | Readable diagrams stay under about 15 nodes |
The JSON Schema is architecture.schema.json; the full guide is the schema README.
Styles
Paper, ruling and pencil are one line each. A seed gives you a different hand-drawn take on the same diagram, and the same seed always draws it the same way.
Checks
Before drawing, penciled validates the input and lays the diagram out exactly as it will be drawn. Errors mean it can't be drawn as written. Warnings mean it will draw, but probably not the way you want. Every message says what to change, which is how an agent fixes its own diagrams. The messages below are produced live.
| Code | Kind | Meaning |
|---|---|---|
schema | error | A value doesn't match the format, with “did you mean” for typos |
duplicate-id | error | Two nodes or groups share an id |
unknown-node | error | An arrow points at a node that doesn't exist |
edge-to-group | error | An arrow points at a group; arrows connect nodes |
unknown-group | error | A node's group or a group's parent doesn't exist |
group-cycle | error | Groups nest in a loop |
partial-positions | error | Some nodes have a position and some don't |
arrow-crossings | warning | Arrows cross each other |
arrow-through-node | warning | An arrow couldn't be routed around a node |
aspect | warning | The drawing is a long strip; try the other direction |
node-overlap | warning | Two nodes on top of each other |
node-in-other-group | warning | A node drawn inside a group it isn't in |
group-overlap | warning | Two groups that aren't nested overlap |
label-crowded | warning | An arrow label has no clear space |
label-overflow | warning | A label is wider than its node's fixed size |
self-loop | warning | An arrow from a node to itself (not drawn) |
duplicate-edge | warning | The same arrow twice |
empty-group | warning | A group with no nodes (not drawn) |
isolated-node | warning | A node with no arrows in a diagram that has some |
Outputs
All come from the same input and seed, so they match, and the handwriting font is built in. For places that don't show SVG, like chat apps and email, write a PNG: -o diagram.png (it uses Chrome, Edge, Chromium or Brave if you have one installed).
For READMEs, docs sites, wikis and slides. Scales to any size and stays sharp.
penciled diagram.json -o diagram.svgPut it in a README like any image:
Re-render after editing the JSON and the picture in your docs stays current. Keep the seed and it keeps its character.
One offline HTML file with the renderer inside. Try it right here: press Redraw, switch the paper, scroll to zoom, save a PNG or JPG.
penciled diagram.json -o diagram.html
Playground
The real renderer and validator, running in your browser. Nothing is uploaded. Start from an example, change a label, add a node, switch the paper. When you like it, download it as SVG, PNG or JPG.
Gallery
Each drawing is rendered live from its JSON. Under each one is the kind of request you could give your agent to get something like it.
Get it
All free, all offline. The only requirement for the first two is Node.js 18 or later.
Install it as a skill. Your agent learns when to use it and how to write, check and draw the diagram.
npx skills add himanshu13ps/penciledThen ask in your own words:
Clone the repo; there is nothing else to install.
$ git clone \ https://github.com/himanshu13ps/penciled $ cd penciled $ node skills/penciled/src/cli.js \ examples/web-app.json -o web-app.svg
Use -o out.png for a PNG, -o out.html for the viewer, validate to check without drawing, --seed for another take.
Use the playground on this page. Write or paste the JSON, pick a paper and pencil, and download SVG, PNG or JPG. Nothing to install, nothing uploaded.
Open the playgroundThe skills installer asks which agents you use. To choose up front, pass -a; add -g to install for every project instead of the current one.
| Agent | Command | Installs to |
|---|---|---|
| Claude Code | npx skills add himanshu13ps/penciled -a claude-code | .claude/skills/ |
| Cursor | npx skills add himanshu13ps/penciled -a cursor | .agents/skills/ |
| Codex | npx skills add himanshu13ps/penciled -a codex | .agents/skills/ |
| Gemini CLI | npx skills add himanshu13ps/penciled -a gemini-cli | .agents/skills/ |
| GitHub Copilot | npx skills add himanshu13ps/penciled -a github-copilot | .agents/skills/ |
| Others | Over 70 agents are supported; see the full list. | |
FAQ
A folder of instructions (and, here, code) that an AI coding agent such as Claude Code, Cursor or Codex can load when a task calls for it. penciled's skill tells the agent when a hand-drawn diagram fits, how to describe the system, how to read the validator's messages and how to render the result.
No. You can write the JSON yourself and run the command line, or use the playground on this page without installing anything.
Architecture and system diagrams: services, databases, queues, people, external systems, documents, the groups around them and the arrows between them. It isn't for charts of numbers, UI mockups or precise engineering drawings.
A diagram can have up to 40 nodes, 12 groups and 80 arrows. Hand-drawn diagrams read best under about 15 nodes; bigger systems work better as an overview plus a few detail diagrams.
No. penciled runs entirely on your machine, or in your browser on this page. It makes no network requests and collects nothing.
Yes. Layout is automatic by default, but if every node has a position, penciled uses your positions as given. See the event pipeline in the gallery.
Set paper.seed. The same input and seed always produce the same drawing, so you can edit a label and re-render without the whole sketch changing character. In the viewer, save the JSON to keep the seed you liked.
Yes, three ways. In the playground on this page, use the PNG or JPG buttons. In the interactive viewer, use its PNG or JPG button. From the command line, write to a .png file: penciled diagram.json -o diagram.png. That uses Chrome, Edge, Chromium or Brave if one is installed; without one, it tells you so and you can save a PNG from the viewer instead.
Images are twice the drawing's size by default, sharp enough for slides. PNGs keep every detail but run to several megabytes because of the paper grain; JPG is about a tenth of the size.
Edit the JSON and render again; that's the intended way. The SVG is a normal vector file, so you can also open it in a vector editor, though it is made of many small pencil strokes.
Usually 100 to 400 KB for an SVG and about 160 KB for the viewer. PNGs from the command line are twice the drawing's size by default; use --scale 1 for smaller files. The paper grain and the embedded font are most of it. PNGs are larger, often several megabytes, because the paper grain doesn't compress; JPG is about a tenth of the size and fine for sharing.
It's free and open source under the MIT licence. The handwriting font, Caveat, is under the SIL Open Font License.