ai-handout-studio
AGENTS.md1 starsChanged 42 days agoMITView on GitHub
A tool that turns AI-authored JSON into a finished handout: a 1280x720 slide deck (deck.json) or an HTML document (document.json), edited on screen and exported to PDF, PNG, HTML or PPTX. Scripts are defined in package.json. Before finishing a change, run: Run pnpm exec playwright install chromium once before the export tests. When you change mods/, also run pnpm test:mod (it needs Claude Code 2.1.287 or later and skips without it; CI doesn't have it).
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pull-requestSkill
- studio-setupSkill
- studio-uninstallSkill
- ai-handout-studioSkill
- question-sheetSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Run pnpm exec playwright install chromium once before the export tests.
- Very specific: line 28
After changing anything under design/ (JSON, CSS, figure/) or a sample generator (app/server/design-samples.ts, sheet-sample.ts, …
- Very specific: line 36
Write functionally: const, early returns, map.
- Distinctive: line 45
Don't put the name of an existing commercial product into code, UI strings, identifiers or template descriptions.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md 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.
Files
AI Handout Studio
A tool that turns AI-authored JSON into a finished handout: a 1280x720 slide deck (deck.json) or an HTML document (document.json), edited on screen and exported to PDF, PNG, HTML or PPTX.
Commands
Scripts are defined in package.json. Before finishing a change, run:
pnpm typecheck && pnpm test && pnpm test:skills && pnpm lint && pnpm build && pnpm test:exportRun pnpm exec playwright install chromium once before the export tests. When you change mods/, also run pnpm test:mod (it needs Claude Code 2.1.287 or later and skips without it; CI doesn't have it).
Where to make a change
- Repository skills (
studio-setup,studio-uninstall,pull-request) live in.agents/skills/;.claude/skills/holds relative symlinks to them for Claude Code, which doesn't read.agents/skills. - Per-harness differences (config folder, shared-instructions file, CLI form) are written only in
scripts/harnesses.mjs; doctor and the AI panel read it. - The API under
app/server/is loaded when Vite reads its config; restart the dev server after editing it. - Question-sheet markup is built in
app/server/sheet-render.ts(it draws both the built-in sample and a saved sheet). Sample content lives insheet-sample.ts, its English text insheet-sample.en.ts. Only a saved sheet also ships a client script,sheet-client.ts, that moves between questions — editing it changes the CSP hash automatically. - Handout (document) markup is built in
app/server/document-render.ts(sample, on-screen preview and export all go through it). Sample content lives indocument-sample.ts, its English text indocument-sample.en.ts. A slide template's English sample issample.en.jsonnext to itssample.json;design/templates/README.mdhas the rules. - The schema's source of truth is
app/src/schema/; types are derived from Zod, not written by hand. After changing it, runpnpm schema:exportto regenerateskills/ai-handout-studio/*.schema.json. mods/handout-watchis a Claude Code mod (a plugin of function hooks) that shows the handouts made in the current conversation above the prompt. Setup section 9 offers it as a symlink at~/.claude/skills/handout-watch, which Claude Code loads in place ashandout-watch@skills-dir; the mod finds the clone by resolving that link. Claude Code writes the mod's types to.claude-plugin/types/when it loads it (git-ignored);pnpm test:modtype-checks only once they exist.- There are two skills:
skills/ai-handout-studio(handout authoring) andskills/question-sheet(question sheets). The question-sheet skill has no copy of the design system — it reads this repository'sdesign/distdirectly (skills/question-sheet/scripts/design.mjs). - Diagrams come from the
diagram-skilldependency, a separate public repository (GentaAmeku/diagram-skill) pinned by tag inpackage.json. The studio calls it only through its command (app/server/diagram.ts), never by importing its code. To change the generator, release a new tag there and bump the version here. - Setup and uninstall are game books:
scripts/doctor.mjsreturns the next section ofSETUP.md, or ofUNINSTALL.mdwith--uninstall, so keep its section numbers in step with both languages (doctor --checklistreads the section titles from their## N. …headings). When setup starts putting something new outside the clone, add its removal toUNINSTALL.mdanddoctor --uninstalltoo. Setup is run again after updates, so a new optional item it offers must bemissinguntil it is installed or declined (record the decline inworkspace/profile.jsonwith anask/declinedsetting, likemods.claude) — awarnalone never brings a finished setup back to it. scripts/dev-sync.mjskeeps dependencies anddesign/distin step with the checkout.pnpm devandai-handout-studio open/restartrun it before starting the server, and the git hooks thatprepareinstalls run it aftergit pull, restarting a running server when it rebuilt something. It compares a fingerprint of the inputs with the one saved innode_modules/.cache/ai-handout-studio/:pnpm-lock.yamlfor dependencies; fordesign/dist,design/(minusdist/andsamples/) and the code reachable by relative imports fromapp/server/design-build.ts. If design build starts reading a file outside those, add it toDESIGN_ENTRIES.- After changing anything under
design/(JSON, CSS,figure/) or a sample generator (app/server/design-samples.ts,sheet-sample.ts,sheet-render.ts), runpnpm design:build(orai-handout-studio design build) to rebuilddesign/dist/anddesign/samples/. Tests fail against a stale build.
Pull requests
Open a pull request by following .agents/skills/pull-request/SKILL.md: run the checks above, take before/after screenshots when the screen changes, and write the body in the three sections of .github/pull_request_template.md.
Style
- Write functionally:
const, early returns,map. Avoidlet,switch,class. - Color, spacing, font size and corner radius live only in
design/tokens.jsonand a theme (design/themes/). CSS underdesign/is a build output ofpnpm design:build— don't hand-edit it, and don't write a hex color into a block component ordesign/slide.css.
Template names
This applies to every kind of template (slide, sheet and document). A template's identifier is a single lowercase English word (e.g. lumen, prism, cobalt). A new slide template takes a proper noun drawn from light, material or tool imagery — never a descriptive or purpose-based name. Its display name (label) is always English: the identifier with the first letter capitalized, including the built-in default ("Default"). The schema rejects a label that isn't English. When you rename or remove a template, add the old name to TEMPLATE_RENAMES in app/server/template-renames.ts so saved handouts move to the new one.
Don't leak product names
Don't put the name of an existing commercial product into code, UI strings, identifiers or template descriptions.
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
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.

