Ostraca

Skill

Any object your product needs, in the Ostraca hand.

The Ostraca skill teaches a coding agent to draw a new figure in the same hand as the library: one description file that the engine turns into all six states, or only the ones you need. The agent checks it against the rules, draws contact sheets, looks at them and fixes what it sees before handing it over.

Install

ForRun
You, in every projectnpx skills add ahmedamr-r/ostraca -g
This project onlynpx skills add ahmedamr-r/ostraca
Without the skills CLIDownload ostraca.zip and unzip it into your agent's skills folder

The skills CLI asks which agents to set it up for; add -a claude-code to pick Claude Code alone. npx skills update brings it up to date. The zip holds the same folder the CLI installs. For Claude Code, in every project:

curl -fsSLo ostraca.zip https://skills.ahmedamr.com/ostraca/ostraca.zip && unzip -o ostraca.zip -d ~/.claude/skills

It works in any agent that reads SKILL.md skills, such as Claude Code. The checks and sheets need Node 22 and Google Chrome or Chromium; there is nothing else to install.

Call it

Ask your agent for an illustration, for an empty state, an upload screen, a 404 or anything else in your product, and it reaches for the skill. Or call it by name:

/ostraca coffee cup

Name an object and the agent draws it. Name a moment instead, such as /ostraca something for a fitness app, and it offers two or three objects to pick from.

The options it asks for

Before it draws, the agent asks what you need, in one message, with a default for each. Say "the defaults" and it draws all six states as a figure. Anything your request already said, such as /ostraca coffee cup, empty only, it does not ask again.

OptionChoicesDefault
StatesAll six, or any of idle, empty, loading, success, changed and error. Fewer means less to draw and to check.All six
OutputA figure for your app, or one standalone SVG picture for a design file, a slide or an email, with no stylesheet neededA figure
For a pictureLight, dark or both; the workers on or off; the paper behind it or transparent; the library's colours or your ownBoth, off, transparent, the library's

Steps

  1. Pin the subject, ask for the options

    First, whether the library already has it: then it shows you that figure instead. Otherwise the object, the product moments it serves, how it builds from the bottom, which part changes, and whether it leans or sags when something goes wrong. Then the states, a figure or a picture, and how a picture should look.

  2. Write the description file

    Geometry only: the pieces in build order, the dashed set-out, where the tick and the cloud land, where the workers stand. For fewer states, only the parts those states use. No state code.

  3. Check, draw the sheet, look

    Every state it draws, with the workers on and off, mirrored, at no value and at 0 and 1. A broken rule fails the check. Then light and dark sheets, and a list of questions asked of the pixels.

  4. Hand it over

    The file, or one standalone SVG if you asked for a picture, with the sheets, the choices you might want changed, and what it did not verify.

  5. Revise on request

    Changes go back through the check and the sheets before they come back to you.

The figure it made

Following the skill from outside the repo, an agent drew this coffee cup on its saucer, on a cafe table. It is kept in the skill as a worked example.

Coffee cup, loading, 50 percent
State
The coffee cup from the skill's examples. Use it with define(cup), then like any library figure.
import { define, render } from "ostraca";
import cup from "./coffee-cup.js";

define(cup);
el.innerHTML = render("coffee-cup", { state: "loading", value: 0.4 });

Source

Read the instructions the agent follows in SKILL.md, and the rest of the folder, with the figure contract, the marks and the examples, on GitHub. The skill page in the docs lists what it will not draw.