Skip to content

Put the load-bearing rules in the skill's entry file - #12

Merged
pasqualevitiello merged 5 commits into
mainfrom
skill-entry-rules
Nov 14, 2026
Merged

pasqualevitiello merged 5 commits into
mainfrom
skill-entry-rules

Conversation

@pasqualevitiello

@pasqualevitiello pasqualevitiello commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

SKILL.md was a 570-word router with no numbers in it. It now carries what an agent needs before it opens a reference.

 skills/plotter/SKILL.md
+## Hard rules          # thirteen non-negotiables, each with its reason
+## Numbers             # generated from standard.json by build-standard.py
 ## Choose the workflow
 ## Load the shared references
+## Faults to catch     # the mistakes cold runs actually made
+skills/plotter/scripts/check.py   # rule checker run before every delivery
 ## Finish the requested artifact
+                       # report order: Files, What it shows, Checked, Not checked
-description: 40 words, in Plotter's own vocabulary
+description: what people ask for, and what the skill is not for

The numbers block sits between generated markers, so the entry file cannot drift from standard.json. Text size and case rules come from the catalogue: all 100 drawings use 10 to 12 unit text and none use all-caps or letter-spaced labels.

Evidence

Seven briefs, three fresh Claude Code (Sonnet 5.5) sessions each, on main's skill and on this branch. The 42 drawings were shuffled and scored without knowing which version made them.

main this branch
Defects counted across 21 drawings 11.0 5.0
Drawings with no defect 9 13
Report in the four-part order 0 of 21 20 of 21
Mean report length 290 words 207 words
Deliverables with a stroke width other than 1 4 0
Mean time and cost per run 75 s, $0.32 56 s, $0.26
  • Before: two of three interface-row drawings carried a full chain of dimensions.
    After: none did.
  • Empty search at 240 px was rejected by the maintainer in both versions above: every run drew a magnifying glass on a small canvas with thick strokes, although the catalogue already solves the subject in EMP-06. A second commit adds two hard rules (never the feature’s pictogram; a small size never changes the canvas), a catalogue-index search in the reference step, and the compact-version recipe the website uses.
    After that commit: in 12 fresh runs (this brief four times; notifications, payment methods, and a 404 card at small sizes; a search hero), all 12 searched the catalogue index and opened the matching drawing, none used a pictogram as the main form, and all 10 small-size runs delivered a 560 × 440 drawing plus a compact version with non-scaling strokes.
  • Trigger test (no /plotter, nine prompts, two runs each): the old description loaded the skill in 9 of 10 illustration requests, the new one in 10 of 10; neither loaded it for a chart, a dropdown animation, a Mermaid flowchart, or an icon set.
  • Side effect, fixed: with the numbers in the entry file, agents stopped opening the foundation reference and stopped using data-plotter-role. One added sentence restored it: 7 of 7 check runs read the foundation and 4 of 7 used role tokens.
  • Labels and sparse studies, also rejected by the maintainer: a bicycle whose labels read big and bold, and a magnifying-glass study that was only an outline. The labels were not bold; they inherited the drawing’s 1-unit stroke. A later commit adds scripts/check.py, which the workflow runs before rendering. It fails stroked, bold, oversized, full-ink, all-caps, letter-spaced, italic, or upside-down text, strokes other than 1 unit, gradients, filters, skew, and a wrong canvas, and warns when a drawing is sparser than nine in ten catalogue drawings. Each rule is measured from the catalogue (668 labels: all weight 400, 10 to 12 units, 0.5 to 0.78 ink), and plotter:check fails if the checker rejects any catalogue or grammar drawing.
    After that commit: in 6 fresh runs every session ran the checker (5 to 8 times each) and all 6 deliverables pass it with no errors. One of four magnifier studies was still thin; the workflow now treats the sparse warning as an error for shape studies, and that last change has not been rerun.
  • format:check, typecheck, and plotter:check pass.

Not established: whether the maintainer accepts the new small-placement drawings; they have not been reviewed yet. Also not established: the scoring was done by one judge, and 21 drawings per side is a small sample, so 9 versus 13 clean drawings could be chance. One brief (the bicycle) scored slightly worse on this branch. Reports are still above the 150-word target. Codex was not tested, and the trigger test had no competing skills installed.

Merge Danger

Door: Two-way

Blast Radius: Skill

Every drawing, critique, and animation request reads the entry file, so a bad rule here affects all of them. Reverting the commit restores the previous entry file and download.

🤖 Generated with Claude Code

The entry file was a 570-word router with no numbers in it; the rules
lived in references that cold runs skimmed. It now carries eleven hard
rules with their reasons, the standard's numbers, the faults seen in
cold runs, and a fixed report order.

- The numbers block is generated from standard.json by
  build-standard.py, so the entry file cannot drift from the standard.
- The description lists what people ask for and what the skill is not
  for.
- Text size and case rules come from the catalogue: all 100 drawings
  use 10 to 12 unit text and none use all-caps or letter-spaced labels.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
plotter Ready Ready Preview Nov 14, 2026 11:30am UTC

pasqualevitiello and others added 4 commits November 14, 2026 12:10
A search empty state at 240 px came back as a magnifying glass on a
tiny canvas with thick strokes, in every run, although the catalogue
already solves that subject in EMP-06.

- Hard rule: never the feature's pictogram as the main form.
- Hard rule: a small size never changes the canvas or the language.
  drawing.md gains the compact-version recipe the website already uses:
  same geometry, cropped viewBox, non-scaling strokes, no shrunken text.
- The reference step now searches the catalogue index for the brief's
  subject instead of opening the catalogue only when a code is named.
- Four regression briefs added to evals.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer's line: a large magnifying glass is fine when the
drawing is about how that shape is built, and wrong when it stands in
for a concept such as search. The earlier wording let an object through
whenever construction marks were drawn on it, which is the loophole.
The test is now what the brief is about.

Adds a brief where the object is the subject, so the rule is checked in
both directions.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer rejected two results: a bicycle whose labels read big
and bold, and a magnifying-glass study that was only an outline. The
bold text was not bold at all; it inherited the drawing's 1-unit
stroke. Prose rules had not prevented either.

- Add scripts/check.py. It fails stroked, bold, oversized, full-ink,
  all-caps, letter-spaced, italic, or upside-down text; strokes other
  than 1 unit; gradients, filters, and skew; and a canvas other than
  560 x 440. It warns when a drawing is sparser than nine in ten
  catalogue drawings. --compact checks a compact version.
- Every rule is taken from the catalogue: all 668 labels are weight
  400, 10 to 12 units, at 0.5 to 0.78 ink. plotter:check now fails if
  the checker rejects any catalogue or grammar drawing.
- The drawing workflow runs the checker before rendering, and gains a
  recipe for shape and object studies drawn from TYP-01, GEO-03, and
  EMP-04: axes, generating geometry, construction points, a module,
  dimensions, callouts, one selected region.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@pasqualevitiello
pasqualevitiello merged commit fd3a45a into main Nov 14, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant