agentleFS
kellervaterkellervater/homeracker/.claude/skills/grill-my-model/SKILL.md

grill-my-model

Skill553 starsChanged 2 months agoMITView on GitHub

Relentlessly interview the creator of a HomeRacker OpenSCAD model about every design decision, then fold the answers into the model's documentation. Use this skill during planning of a new model, or after a model (or a change to one) is built, to pressure-test the design and produce the most comprehensive yet concise docs possible. USE FOR: grilling a model's parameters/defaults/geometry/print choices, filling gaps a newbie couldn't understand, improving model README / configuration & printing guides / MakerWorld descriptions, rendering missing parameter-config images, and creating or updating a model's decision record (ADR). DO NOT USE FOR: writing the OpenSCAD geometry itself, extracting MakerWorld descriptions from the web (use the makerworld-description skill), or routine version/config/dependency changes.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. kellerlabs/homeracker★ 553100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before asking anything, read everything that already exists for the model:

    line 47
  2. Distinctive:

    Run the interview one question at a time.

    line 68
  3. Distinctive:

    Wait for the answer before moving on.

    line 74
  4. Distinctive:

    When an answer reveals a new branch, push onto the agenda and keep going.

    line 76
  5. Distinctive:

    Only after the relevant branch is resolved, update docs.

    line 119
  6. Distinctive:

    If a parameter configuration that matters for understanding has no illustrating render:

    line 135
  7. Very specific:

    Add the new image to the README 📸 Catalog and, if used there, the MakerWorld description.

    line 142
  8. Distinctive:

    Add the *context the code cannot convey*.

    line 149
  9. Very specific:

    Use HomeRacker emoji section headers and cross-link from the parent index.

    line 150
  10. Distinctive:

    Every parameter has a justified existence, default, and range, or was removed.

    line 173

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

🔥 Grill My Model, homeracker Skill

📌 What

A relentless interview that walks every branch of a model's design tree and challenges each design decision until a newbie could understand why the model is the way it is. The resolved answers are then folded back into the model's documentation (README, configuration/printing guide, MakerWorld description) and, where warranted, a decision record (ADR).

The goal is not to be nice. The goal is the most comprehensive yet concise documentation possible. Ask 10 questions or 100, whatever it takes to leave no unexplained decision behind.

🤔 Why

Models accrete parameters, magic defaults, and geometry tricks whose rationale lives only in the author's head. New users (and future AI agents) then can't tell which knob to turn or why a default is what it is. Grilling surfaces that hidden rationale while it's still recoverable and captures it where people will actually read it.

This skill is the OpenSCAD-model translation of the popular "grill my plan" pattern (e.g. mattpocock/skills grilling): a one-question-at-a-time, recommend-an-answer, explore-before-asking loop.


1. When to Use

SituationWhat the grill produces
Planning a new modelA clear design brief: justified parameters, defaults, scope, print plan, captured in a fresh README + ADR before code exists
After building a model or changing oneGap-filled README, configuration/printing guide, MakerWorld description, refreshed config images, updated/created ADR

It works the same way in both cases: gather context, grill, then act on docs.


2. Gather Context First (do not ask what you can read)

Before asking anything, read everything that already exists for the model:

  1. The model source: models/<name>/**/*.scad (and any lib/ it uses/includes). Enumerate every parameter (Customizer vars, module args), default, and /* [Section] */ grouping.
  2. Existing docs: models/<name>/README.md, any configuration/printing guide, models/<name>/makerworld/DESCRIPTION.md (if published), and parts/renders/*.png.
  3. Existing ADRs: scan docs/decisions/ for an entry about this model.
  4. Repo conventions: README.md (HomeRacker standards: 15 mm base unit, 4 mm lock pins, 2 mm walls, 0.2 mm tolerance) and the markdown instructions.

Rule (from the source pattern): if a question can be answered by exploring the codebase, explore the codebase instead of asking. Only ask the human what the code cannot tell you, intent, trade-offs, target user, and the "why".

Build a checklist of every decision you found. That checklist is your grill agenda.


3. The Grilling Loop

Run the interview one question at a time. Asking several at once is bewildering.

For each question:

  1. State the decision under scrutiny and why it matters.
  2. Give your recommended answer with reasoning (so the user can just confirm).
  3. Wait for the answer before moving on.
  4. Resolve dependencies first: if decision B depends on A, settle A first.
  5. When an answer reveals a new branch, push onto the agenda and keep going.

Stay relentless but constructive. Keep each question tight, no walls of text.


4. What to Grill, Question Catalog

Walk these lenses for the model as a whole and for every single parameter. Skip only what context already answers conclusively.

4.1 Every parameter (ask for each one)

  • Existence: Why does this parameter exist at all? Which concrete user use case does it solve? What breaks if we delete it (YAGNI check)?
  • Value to the user: Does a real user ever change this, or is it an internal constant masquerading as a parameter? Should it be hidden / promoted / removed?
  • Default: Why this default and not another? Is it the most common real-world case? Does it satisfy HomeRacker standards out of the box?
  • Range & step: Are the Customizer [min:step:max] / enum choices justified? What happens at the extremes, does it still print and fit?
  • Name: Does the name spell out intent for a newbie? (See naming conventions in the OpenSCAD instructions, descriptive over abbreviated.)
  • Interactions: Which other parameters does it couple with? Any invalid combinations that need an assert or a doc warning?
  • Units & frame: mm? degrees? Which axis/anchor? Is that obvious from the name/doc?

4.2 The model as a whole

  • Problem: What problem does this model solve, in one sentence a newbie gets?
  • Scope: What is explicitly out of scope, and why?
  • Geometry & build method: Why this construction approach (e.g. BOSL2 vs native, diff vs union, attach vs translate)? What were the alternatives and why rejected?
  • Dimensions: Why these sizes? Which derive from HomeRacker standards vs the target object (jack, drive, panel, etc.)? Cite the source of any magic number.
  • Tolerances & fit: Where is clearance applied and why that much? Print-tested?
  • Print orientation & supports: How is it meant to be printed? Why that orientation? Any multi-part / assembly considerations?
  • Compatibility: How does it mate with the rest of the HomeRacker system?

5. Act on the Documentation

Only after the relevant branch is resolved, update docs. Act on existing docs; create only the crucial README if it is missing.

5.1 Which docs

DocAction
models/<name>/README.mdCreate if missing (crucial). Otherwise update in place. Follow the Model README template in the markdown instructions (What / Why / How / 📸 Catalog / References).
Configuration / printing guideUpdate only if it already exists. Fold in the justified parameters, valid ranges, and print plan.
models/<name>/makerworld/DESCRIPTION.mdUpdate only if it already exists. Reflect resolved rationale and any new config images.
models/README.md (index)Update the model's row if its description/preview changed.

Do not invent new doc files beyond the crucial README. Improve what exists; link to the single source of truth rather than duplicating.

5.2 Missing parameter-config images

If a parameter configuration that matters for understanding has no illustrating render:

  1. Ask the user whether to render it (and at which parameter values).
  2. On confirmation, render with scadm export-png, full F6 renders, BeforeDawn colorscheme (the intentional default). Use a preset or -D var=val overrides:
    • scadm export-png models/<name>/parts/<part>.scad -D 'param=value' --output models/<name>/parts/renders/<name>_<variant>.png
    • or with a preset: scadm export-png <file> -p <presets.json> -P <preset>
  3. Add the new image to the README 📸 Catalog and, if used there, the MakerWorld description. Manually-authored images go to the kellerlabs/assets repo; auto-generated renders stay in parts/renders/.

5.3 Writing quality

  • Be brief, bullet points over prose, < ~100 lines where possible.
  • Add the context the code cannot convey; never restate what the code already says.
  • Use HomeRacker emoji section headers and cross-link from the parent index.

6. Decision Record (ADR) Rules

A model carries one decision record capturing its core design rationale. Apply:

SituationAction
No ADR exists for this modelBuild one from the ground up in docs/decisions/<model>.md capturing the grilled rationale (problem, key parameters/defaults, geometry & build method, alternatives rejected, consequences). Load the decision-records skill for the exact template and index update.
ADR exists but has gapsAdapt the existing ADR, fill the missing context the grill surfaced. Do not create a second record.
Behavior changed significantly (geometry or build method materially different)Create a new ADR that supersedes the old one (per the supersede flow in the decision-records skill).

A single ADR per model is enough unless geometry or building methods change significantly. Routine parameter tweaks update the README/guide, not a new ADR.


7. Completion Criteria

The grill is done when:

  • Every parameter has a justified existence, default, and range, or was removed.
  • A newbie could read the README and understand why, not just how.
  • Configuration/printing guide and MakerWorld description (where they exist) reflect the resolved rationale and any new config images.
  • The model's ADR exists and is current per §6.
  • The parent models/README.md index is consistent.

📚 References

  • humanizer skill: run it over any README/description/ADR text this grill writes or edits, to strip AI tells
  • grill-my-plan skill: the plan-shaped sibling (use it to stress-test a plan before code exists)
  • decision-records skill: ADR template, index, supersede flow
  • makerworld-description skill: MakerWorld DESCRIPTION.md handling
  • Markdown guidelines: Model README template, Catalog rules
  • OpenSCAD guidelines: naming, geometry conventions
  • mattpocock/skills grilling: the upstream "grill my plan" pattern this adapts

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.