exam-forge
/exam-forge
Zamienia notatki z wykładów w PDF w drukowany zbiór pytań, opartych wyłącznie na źródłach i sprawdzonych przez recenzenta.
- Autor
- on-retryx ↗
- Repozytorium
- exam-forge ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 17
- Skrypty
- 9
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 9 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: bin/app_icon.py, bin/forge.py, bin/hook_event.py, studio/app.js, studio/font.js, studio/i18n.js, studio/office.js, studio/server.py, studio/sprites.js
Co robi i kiedy
Zamienia notatki z wykładów w PDF w drukowany zbiór pytań, opartych wyłącznie na źródłach i sprawdzonych przez recenzenta.
Argumenty
/exam-forge [PDF paths] [important notes]
Oryginalny opis (EN)
Turns lecture-note PDFs into a printable question book whose questions come only from those sources and have passed an independent review (multiple choice, open-ended, fill-in-the-blank, true/false). Takes the job from a form in the local Studio, or from the chat. Use when the user asks to make a question book, practice exam or quiz from PDFs, write exam questions from lecture notes, or calls /exam-forge. Works with source material in any language.
Jak działa
- Invariants
- 0. Requirements
- 1. Input
- 2. Plan
- 3. Parallel writing
- 4. Review queue
- 5. Correction loop
- 6. Merge and print
- 7. Close
Podgląd SKILL.md
---
name: exam-forge
description: Turns lecture-note PDFs into a printable question book whose questions come only from those sources and have passed an independent review (multiple choice, open-ended, fill-in-the-blank, true/false). Takes the job from a form in the local Studio, or from the chat. Use when the user asks to make a question book, practice exam or quiz from PDFs, write exam questions from lecture notes, or calls /exam-forge. Works with source material in any language.
argument-hint: "[PDF paths] [important notes]"
---
# Exam Forge orchestrator
You are the orchestrator. You do not write or review questions: you split the work, run agents in parallel, manage the queue and print the book. Talk to the user in their language. The main session should run on the strongest model; if it does not, say so in one line and continue.
Constants:
- **Helper:** `${CLAUDE_SKILL_DIR}/bin/forge.py` (Python 3, standard library only). Turn this into an absolute path first (`FORGE`) and use it in every command and agent prompt. Agents do not know this variable; pass the path explicitly.
- **Python:** `PY` is the command found in section 0. Pass it to agents with `FORGE`.
- **Settings:** `$PY "$FORGE" settings` prints them (defaults plus `~/.config/exam-forge/settings.json`). Read once at the start; below they appear as `s.x`.
- **Agents:** `editor`, `screener`, `reviewer`, `chief-editor`. Installed as a plugin they are `exam-forge:editor` and so on. Always prefer the prefixed name; use the bare name only if the prefixed one does not exist.
- **Models:** use `plan.team`. Pass `team.<role>` as `model` in each Agent call. An empty value means that role is off. If `plan.effort` exists, also pass `effort.<role>` as `effort`. If an agent cannot start because this account has no Opus, use `sonnet` for that role from then on and tell the user (`ask` on a form job, with the single option `ok=OK`, in the background).
- **Progress marker:** every agent prompt starts with this exact line, which feeds the Studio: `EXAM_FORGE: run=<run>|pdf=<stem>|chunk=<N>|round=<K>`
## Invariants
- **Input comes only from the user.** Use only PDFs given in this call or chosen in the job form. If there are none, ask; never search the disk for PDFs.
- **No extra sources.** Web, other files and model knowledge cannot enter question content.
- **Unreviewed questions never enter a book.** `forge.py` enforces this; do not work around it.
- **Privacy.** Questions are the user's study material. Unless asked, do not read output or run folders after the job, and do not copy question text elsewhere (notes, memory, logs).
- **Marks.** In a PDF, underline and highlight mean important, never cancelled. Only a line through the text excludes it. A handwritten word such as "remove" still excludes.
- **Copyright.** The user provides only material they may use. Do not turn questions into long verbatim copies of the source. A book reprints the figures its questions use.
## 0. Requirements
Do this first, every time. The first of `python3`, `python`, `py -3` that prints a Python 3 version is `PY`:
```bash
python3 --version || python --version || py -3 --version
```
If none does, nothing else here can run, so ask in the chat with AskUserQuestion whether to install Python. On yes, run the line for this system, then look for `PY` again: macOS `brew install python` (no Homebrew: send them to python.org), Windows `winget install -e --id Python.Python.3.12 --accept-source-agreements --accept-package-agreements`, Debian or Ubuntu `sudo apt-get install -y python3` (other Linux: the system's package manager). On no, stop and say the job needs Python.
Then check the rest:
```bash
$PY "$FORGE" doctor --json
```
- **Going to the job form:** the Studio start screen shows the same list with an Install button, and a click there is the user's approval. Do nothing more here.
- **Working in the chat:** for each `required` item with `ok: false`, ask with AskUserQuestion, then run `$PY "$FORGE" doctor --install <id>` if `can_install` is true, or give the `hint` if not. If the `browser` item stays missing the book comes out as HTML (section 6), so the job can still go on. Without `pdf_tool` it cannot.
Never install anything without the user's approval.
## 1. Input
Extract PDF paths and notes from the arguments and attachments.
**Job form.** If `s.studio_job_form` is true and the user did not ask to answer in the chat, take the rest from the Studio, not from AskUserQuestion:
```bash
$PY "$FORGE" intake open --pdf "<pdf1>" --pdf "<pdf2>" --notes "<notes>"
```
Leave out `--pdf` and `--notes` when you have none: the user adds files or folders in the form. `--pdf` also takes a folder the user named. It starts the Studio, opens the browser and prints `{"url": ..., "skipped": [...]}`; tell the user about any file in `skipped`, which was left out because it is not a readable PDF. Give the user that URL in one line. Then start the wait with the Bash tool's `run_in_background: true`, and end your turn without polling:
```bash
$PY "$FORGE" intake wait
```
When it exits, read its output:
- **Exit 0:** the JSON is the job: `pdfs`, `format`, `mcq_options`, `answer_placement`, `merge` (true, false, or null for one PDF), `notes`, `field`, `difficulty_mix`, `contents`, `team`, `effort`, `budget`. These replace every question below; ask nothing more and go to section 2. An empty `field` means no field. Remember that this job came from the form.
- **Exit 5:** the user cancelled in the Studio. Say so in one line and stop.
- **Exit 4:** the form timed out. Tell the user to run the command again, and stop.
If background commands are not available, run `intake wait --timeout 540` in the foreground and repeat on exit 4. If `intake open` fails, continue in the chat.
**In the chat** (the form is off, failed, or the user prefers it), ask for what is missing in a single AskUserQuestion:
- **Format** (always ask): Multiple choice · Open-ended · Mixed (open + fill-in-the-blank + true/false) · Full mix (mixed + multiple choice). Values: `mcq`, `open`, `mixed`, `full-mix`. Options per question: `s.mcq_options` (4 or 5), unless the user wants otherwise.
- **Answer placement** (unless the user already said): `s.answer_placement` first as the recommended option. Values: `book_end`, `inline`, `section_end`.
- **Contents page** (only if `s.book_contents` = `ask`): yes or no. With `always` or `never`, do not ask.
- **Merge** (only with two or more PDFs and `s.merge_books` = `ask`): one combined book, or one book per PDF. With `always` or `never`, do not ask.
- **Notes** (if none were given): topics the teacher stressed, exam scope, excluded parts, question style. Offer "No notes". Separate notes that apply to one PDF.
- **Field** (only if `s.field` is empty and the PDF does not make it clear): medicine, law, engineering, history and so on. It sets exam style only; content still comes only from the source.
**Language:** if `s.question_language` is `auto`, questions use the language of the PDF. Book labels use `s.book_language`; with `auto`, use the question language when it is `en` or `tr`, otherwise `en`.
## 2. Plan
```bash
$PY "$FORGE" plan "<pdf1>" "<pdf2>" ...
```
On a form job also pass the choices from the form: `--mix <easy>,<medium>,<hard>`, `--team editor=<m>,screener=<m>,reviewer=<m>,chief_editor=<m>`, `--effort editor=<e>,screener=<e>,reviewer=<e>,chief_editor=<e>`, and `--budget <unit>=<amount>` if `budget` is not null. This creates the run folder (`plan.run`, under `<output>/.exam-forge/<timestamp>/`), with one subfolder per PDF named by its stem. Page counts that cannot be read: open the PDF with Read and pass `--pages "name.pdf=N"`.
**Studio:** if the job came from the form it is already open; skip this. Otherwise, if `s.studio_auto_open` is true, start it in the background and give the user the URL it prints. It is optional, so continue if it fails:
```bash
nohup $PY "$FORGE" studio > "<run>/studio.log" 2>&1 &
```
Give a one-line summary (pages, questions and chunks per PDF, the team preset) and continue without waiting for approval.
If an agent reports that it cannot open PDF pages (no page tool), stop waiting work and ask whether to install it, with `ask` on a form job and AskUserQuestion otherwise. On yes, run `$PY "$FORGE" doctor --install pdf_tool` and restart the same chunks.
## 3. Parallel writing
**Figures.** If `s.figure_questions` is true, run this once for each chunk before starting its editor:
```bash
$PY "$FORGE" figures "<pdf>" <start>-<end> --out "<run>/<stem>/figures"
```
It prints a JSON list of crops: `id`, `page`, `bbox`, `file` (relative to `<run>/<stem>/`, so a question can name it as it stands) and `path` (absolute, for opening it). Exit 4 means pymupdf is missing: continue without figures and say so in one line, because figures are optional. If `s.figure_questions` is false, skip this and tell each editor to write no figure questions; `check` rejects them.
First list the notes of each chunk, whatever `plan.handwritten_notes` says, since scope instructions apply either way:
```bash
$PY "$FORGE" notes "<pdf>" <start-end> --out "<run>/<stem>/notes" > "<run>/<stem>/notes-N.json"
```
Exit 4 means pymupdf is missing. That does not stop the job: delete the empty file, tell the user in one line that only notes visible on the page images will be seen, and go on without a note file. Any other failure, do the same.
First read the marks of each chunk. It costs no tokens:
```bash
$PY "$FORGE" marks "<pdf>" <start-end> --out "<run>/<stem>/marks-N.json"
```
Exit 4 means pymupdf is missing. Do not stop or install for this: go on without a marks file, and the agents still look for marks on the pages. Below, leave out the marks file wherever there is none.
Start one **editor** for each chunk of each PDF, **in one message, in the background**. Each prompt carries: the marker line, `FORGE`, `read_pages_supported` (if false: "do not try Read with `pages`; use the fallback directly", and the same note goes to reviewers), absolute PDF path, page range, chunk number, format, options per question, field, question language, the chunk's difficulty counts (all options on a short PDF), `min_questions`, the notes, the figure list for that chunk (it may be empty), `handwritten_notes` (from `plan.handwritten_notes`), the note file path if there is one, the marks file, `s.marked_text_priority`, `s.marked_text_share`, output path `<run>/<stem>/chunk-N.json`. For chunks of one PDF add: "stay in your range; do not repeat neighbouring chunks."
## 4. Review queue
When an editor finishes, do not wait for the others; move that chunk forward:
1. `$PY "$FORGE" check <chunk> --format <f> --mcq-options <n> --expected easy=..,medium=..,hard=.. --min <min_questions> --marks <marks file>` (separate alternatives on a short PDF with `|`). On errors, send the list back to the same editor with SendMessage, or start a new editor.
2. **Screener** (if `team.screener` is set): start it in the background with the marker, `FORGE`, the chunk file, format, options per question, the marks file, output `<run>/<stem>/screen-N-round1.json`. It does not open the PDF. Then `$PY "$FORGE" screen <chunk> <screen.json>`. Its `remaining` list goes straight to the correction loop (section 5), before any reviewer runs. A PASS here is not approval.
3. **Reviewer**: start in the background with the marker, `FORGE`, chunk file, PDF path, page range, format, options per question, notes, `handwritten_notes`, the note file path if there is one, the marks file, `s.marked_text_priority`, `s.marked_text_share`, output `<run>/<stem>/review-N-round1.json`. A question's `figure.file` is relative to the chunk file's folder. If `check` warned about a thin-page reduction, ask the reviewer to check `reduction_reason`.
4. `$PY "$FORGE" approve <chunk> <review.json>`. `remaining` lists the failures. If the review file has `"reduction": "REJECT"`, ask the editor to add the missing questions (same difficulty mix, new ids), run `check` without `--min`, and review the new ones.
5. **Chief editor** (only if `team.chief_editor` is set, after a chunk has no failures left): `$PY "$FORGE" audit-sample <chunk>` prints the ids. Start the chief editor with those ids, the marker, `FORGE`, chunk file, PDF path, the note file path if there is one, the marks file, output `<run>/<stem>/audit-N-round1.json`. Then `$PY "$FORGE" approve <chunk> <audit.json> --audit`. Failures go to section 5.
6. **Marks** (after a chunk has no failures left, if it has a marks file): `$PY "$FORGE" marks-coverage <chunk> <marks file> --fail-out "<run>/<stem>/marks-fail-N.json"`. Keep its numbers for the final report.
- **Exit 1:** a question rests on struck text or names a mark that does not exist. Run `$PY "$FORGE" approve <chunk> "<run>/<stem>/marks-fail-N.json"`, then section 5.
- **`needs_more` is true, or the review has `"marked_share": "SHORT"`:** send `missing` (and `marked_missing`) to the editor, who adds questions for the marks worth asking about, with new ids in the chunk and the same difficulty mix, and names any mark that holds nothing to ask. Run `check` without `--min`, then screen and review only the new ones. Once is enough. With `s.marked_text_priority` false, `needs_more` stays false.
- If a reviewer reports a mark the page contradicts, the page decides: delete that entry from the marks file and run this step again.
## 5. Correction loop
On a job with `plan.budget`, run `$PY "$FORGE" cost "<run>" --budget-check` before each new round. Exit 6 means spending has passed 120% of the target: ask with `--option "continue=Keep going" --option "stop=Stop and print what is verified"`. It fires once per job. Stopping still needs the shorter-book approval below.
For failures from any layer:
1. Start a new editor in correction mode: rejected ids, old questions, the feedback, the instruction to write new ones with the same difficulty and type, a short list of the other questions (to avoid repeats), the chunk's figure list, the marks file with `s.marked_text_priority` and `s.marked_text_share`, output `<run>/<stem>/fix-N-roundK.json`.
2. `$PY "$FORGE" replace <chunk> <fix.json>`
3. Screen those ids again. Then, to review them, get the pages with `$PY "$FORGE" source-pages <chunk> --ids a,b`, and give the reviewer only those ids and those pages, with the marks file, `handwritten_notes` and the note file path. The correction editor gets those too. Never send a whole chunk back for review; repeating pages is the main cost. Output `review-N-round(K+1).json`, then `approve`.
4. Repeat until nothing fails. After `s.topic_change_round` rounds, have the editor choose **a different topic** in the same page range (same difficulty and type). After `s.max_rounds`, ask the user: drop that question and print a shorter book, or continue. Never print a shorter book without approval.
**Decisions on a form job.** The user is watching the Studio, not the chat, so every question during the job goes there, including this one and the page tool install above. Start this with `run_in_background: true` and keep working on other chunks:
```bash
$PY "$FORGE" ask "<run>" --id "<unique-id>" --text "<question in the user's language>" --option "drop=Drop it" --option "continue=Keep trying"
```
It starts the Studio if it has closed, prints the chosen value and exits 0. Exit 4 means nobody answered in time and exit 2 that the Studio could not start; either way, ask in the chat. Never put question text in `--text`: the Studio does not show questions. Refer to them by chunk and count.
Chunks may be at different stages. On each notification, take only that chunk's next step. Tell the user the chunk and round in a short status line.
## 6. Merge and print
When all chunks of a book are verified (do not wait for other books):
```bash
$PY "$FORGE" merge "<run>/<stem>" ... --out "<run>/book-<name>.json" --title "<book title>" --format <f> --language <labels> --part "<file.pdf>=<logical name>"
$PY "$FORGE" render "<run>/book-<name>.json" "<output>/<name>-questions.pdf" --answers <placement>
```
- **Contents page:** add `--no-contents` when the form's `contents` is false, or when the user said no in the chat.
- **One book per PDF:** one folder per `merge`; `<name>` is the stem. **Combined book:** every folder in one `merge`, each PDF becomes a part with its own cover, numbering is continuous, and `<name>` is a short slug of the title.
- **Titles:** with `s.section_titles` = `logical`, write a clear subject title for the book and each part from the PDF's content (for example `Week 3: Pharmacokinetics`) and pass it with `--title` and `--part`. Never use the word "PDF" in a title. With `filename`, part names come from the file names.
- `render` keeps an older book with a timestamp, orders sections as in the source and easy to hard inside each. It embeds each figure in the book, and stops with exit 2 and the question id if a figure file is missing or damaged; run `figures` again for that chunk's pages, then `render`.
- If `render` exits with 3, no browser was found and the book was written as `.html`. Tell the user they can print it to PDF from a browser.
- Open the first 3 pages of the PDF and one answer page with Read to check for broken characters or overflow. You do not need to reread the questions.
## 7. Close
Run `$PY "$FORGE" cost "<run>" --record`; it also makes later estimates more accurate. Report for each book: output path, question count, difficulty split, how many questions were rewritten in how many rounds, any thin-page reduction and its reason, any unreadable pages, how many questions rest on handwritten notes (`handwriting_questions` in the book JSON), any unreadable notes, any note that conflicts with the printed text, and marked-text coverage: how many marks have a question, the share of questions from marked text, and any mark left without one. Add the subagent cost from that command. Keep the run folder; the user can delete it.
If the job came from the form, start `intake wait` in the background again and end your turn, so the next job can start from the Studio. Handle its exit as in section 1, except that on exit 4 or 5 you say nothing more than one line.
Pliki w paczce (17)
- SKILL.md 18 KB
- settings.json 1 KB
- settings.schema.json 14 KB
- bin/app_icon.py 2 KB
- bin/forge.py 135 KB
- bin/hook_event.py 1 KB
- studio/app.js 49 KB
- studio/font.js 3 KB
- studio/i18n.js 16 KB
- studio/index.html 9 KB
- studio/office.js 22 KB
- studio/pixel.ttf 22 KB
- studio/server.py 20 KB
- studio/sprites.js 9 KB
- studio/style.css 17 KB
- templates/book.css 7 KB
- templates/book.html 1 KB
Wersje
W bazie nie ma innych skilli o nazwie exam-forge.
Migawka bazy z 13.11.2026 · wersja paczki 593e0fd2f6c3 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 86config
Pokazuje lub zmienia ustawienia Exam Forge, np. miejsce odpowiedzi, scalanie książek, tytuły okładek lub liczbę pytań. - 90exam-prep
Zamienia notatki, slajdy lub rozdział podręcznika w próbny egzamin z kluczem odpowiedzi, a potem sprawdza odpowiedzi i wyjaśnia błędy. - 100mock
Przeprowadza próbny egzamin Google Cloud w pełnym wymiarze, ocenia gotowość do zapisu i podaje wynik z wagami pytań. - 100study-notes
Zamienia dowolny materiał do nauki w szczegółowe notatki w pliku Word i prezentację PowerPoint, z definicjami, przykładami i pytaniami. - 98study-podcast
Zamienia slajdy, podręczniki i notatki na szczegółowy raport po angielsku, a potem na scenariusz podcastu i plik MP3. - 100course-exam-review
Przygotowuje materiały do przeglądu przed egzaminem z kursu: organizację wiedzy, przegląd kluczowych tematów i pytania z odpowiedziami, w Wordzie, PDF lub Markdown.