You are submitting a single week of English reading quiz content to zxkane/english-weekly-quiz, a kid-facing site that publishes a new KET/PET quiz every Sunday. The site is purely static — your JSON file + optional audio/image files + a PR are the entire publishing mechanism.
The repo's CONTRIBUTING.md is the source of truth, but this skill
already encodes its rules so you don't have to re-read it for every
submission.
When to use this skill
Trigger on user requests like:
- "submit this week's quiz"
- "publish the weekly quiz with these essays"
- "open a quiz PR for week 21"
- "here are the paragraphs, can you make the quiz?"
- anything that involves the english-weekly-quiz repo and a new week of content
If the user just wants to understand how submission works (not actually submit), you should still read this skill but stop at the "Quick start" section and explain — don't run the scripts.
Decision tree
Does the user have a clone of zxkane/english-weekly-quiz on disk?
├── Yes → cd into it, branch from main
└── No → git clone https://github.com/zxkane/english-weekly-quiz.git
Does the user already have the JSON file written?
├── Yes → run validation, then PR
└── No → assemble it from their essay + questions, then validate, then PR
Did the user provide an audio file?
├── Yes → drop it under public/audio/<week>/ before validating
└── No → skip audioUrl (the audio control just won't render)
Did the user provide an image?
├── Yes → drop it under public/images/<week>/ before validating
└── No → skip image
Quick start (the 90% case)
The user gives you essay paragraphs + KET/PET questions for an upcoming week. They want a PR. Steps:
-
Identify the week. If the user says "this week" or doesn't specify, compute the ISO week of today's date (or, if today is Sunday and the essays cover the upcoming week, use next week's ISO week — ask if ambiguous). Format:
YYYY-Wwwwith a 2-digit week (e.g.2026-W19). -
Compute the Sunday.
publishedAtMUST be the Sunday of that ISO week — the validator computes the expected Sunday fromweekand fails the build ifpublishedAtdoesn't match. Use the helper that lives next to this SKILL.md:bash <skill-dir>/scripts/iso-sunday.sh 2026-W19 # → 2026-05-10<skill-dir>is wherever your agent runtime installed this skill — e.g.~/.claude/skills/submit-weekly-quiz/,.claude/skills/submit-weekly-quiz/, or${CLAUDE_PLUGIN_ROOT}in Claude Code. If you can't easily resolve the path, just inline the calculation in Python:date.fromisocalendar(year, week, 7). -
Clone or
cdinto the repo:git clone https://github.com/zxkane/english-weekly-quiz.git cd english-weekly-quiz git checkout -b quiz/2026-W19 npm install -
Write the JSON. Start from the template:
cp <skill-dir>/assets/quiz-template.json content/quizzes/2026-W19.jsonThen fill it in. The structure is documented inline below; for the full schema details (every field, every constraint), see
references/contract.md. -
(Optional) Drop in audio / image under
public/audio/<week>/<slug>.<ext>and/orpublic/images/<week>/<slug>.<ext>. Reference them in the JSON with a leading/(e.g./audio/2026-W19/a-day.mp3). See "Audio & images" below for limits. -
Validate locally:
npm run validate-contentFix any reported errors. Don't push a failing JSON — Amplify will reject it and the PR build will go red.
-
Open the PR:
bash <skill-dir>/scripts/open-pr.sh 2026-W19 "A Day at the Beach"Or do it manually with
gh pr create(see "PR conventions" below). -
Stop at PR open. Do not auto-merge. The site is kid-facing; a human reviews before merge. Print the PR URL and step away.
The JSON shape (inline summary)
{
"week": "2026-W19", // ISO week, must equal filename
"publishedAt": "2026-05-10", // YYYY-MM-DD — Sunday of that ISO week
"title": "A Day at the Beach", // 3–120 chars, shown on cards
"level": "KET" | "PET" | "KET/PET",
"tags": ["seaside", "weather"], // optional, ≤ 8 short tags
"essay": {
// Each paragraph is either a plain string OR {text, image?}. The
// object form embeds an illustration right after that paragraph
// (handy when the picture anchors a question). Wrap a key phrase in
// ==double-equals== inside any paragraph text to render it as a
// highlighted <mark>. Keep highlights sparse: 1–2 phrases per essay,
// ideally on a sentence the questions probe.
"paragraphs": [
"Para 1, plain string with a ==key phrase==.",
{
"text": "Para 2 with an inline picture below it.",
"image": {
"src": "/images/2026-W19/diagram.webp",
"alt": "describe what the kid would see",
"caption": "Optional caption."
}
}
],
"audioUrl": "/audio/2026-W19/a-day.mp3", // optional
"audioCredit": "Read by ...", // optional
"image": { // optional hero image (above the essay)
"src": "/images/2026-W19/beach.svg",
"alt": "describe what the kid would see",
"caption": "Optional caption."
},
"vocabulary": [ // optional block — but if you include it, every entry
{ // MUST carry translations.zh (validator enforces).
"word": "spade", // UI adds a 🔊 (pronounce) and 译 (translate) button
"pos": "n.", // per row. The translation stays collapsed until the
"meaning": "...", // kid clicks 译 — reading-comprehension is preserved.
"example": "...",
"translations": { // REQUIRED when this entry is present.
"zh": "铲子" // zh is mandatory; add other BCP-47 codes (ja, ko,
} // es, zh-Hant, ...) freely — schema accepts any key.
}
]
},
"questions": [ // 3–20 questions
{
"id": "q1",
"type": "multiple_choice", // see table below
"prompt": "What colour is Mia’s swimsuit?",
"options": ["red", "yellow", "blue", "green"],
"answer": "yellow",
"skill": "reading_comprehension", // optional tag
"ketPetPoint": "locate specific information", // optional teaching tag
"explanation": "Paragraph 1 says: 'Mia is wearing a yellow swimsuit'..."
}
]
}
Question types — the rules the validator enforces
type |
options |
answer |
acceptableAnswers |
|---|---|---|---|
multiple_choice |
required, 2–6 strings | must be one of options |
ignored |
true_false |
ignored | "true" or "false" (lowercase, string) |
ignored |
fill_blank |
ignored | the expected word/phrase | optional alternates (case-insensitive) |
For fill_blank, the comparison is case-insensitive and whitespace-
collapsed. Use acceptableAnswers for spelling variants (e.g.
["sandcastle", "sand castle", "sand-castle"]).
Vocabulary block — translations.zh is required
The vocabulary block itself is optional (a no-vocab week is fine). But
if you include vocabulary, every entry MUST have a non-empty
translations.zh — the audience consists of native Chinese speakers, and the "译" (Translate) toggle lets a child reveal a word's meaning when stuck.
"vocabulary": [
{
"word": "incredibly",
"pos": "adv.",
"meaning": "extremely; in a way that is hard to believe",
"example": "Mbappé was incredibly fast.",
"translations": {
"zh": "难以置信地;极其" // REQUIRED
// "ja": "信じられないほど" // any other BCP-47 code is welcome but optional
}
}
]
You're an LLM — produce the Chinese yourself. Don't call an external
translation API. Aim for a short gloss (1–2 short Chinese phrases),
not a paraphrase of the English meaning. Use semicolons to offer 2–3
sense-disambiguating glosses when one Chinese word doesn't capture the
nuance:
| English | Good zh | Bad zh |
|---|---|---|
incredibly |
难以置信地;极其 |
这个词的意思是非常的程度高得让人难以相信 (paraphrase, not gloss) |
defender |
后卫(防守球员) |
防守的人 (too vague — kid doesn't learn the football term) |
tournament |
锦标赛;联赛 |
比赛 (loses the multi-team-competition meaning) |
The validator will fail the build with a clear message if any entry is
missing translations.zh.
Question count: 3–20
The schema enforces this. A typical week is 6–8 questions.
id format: q1, q2, ...
Lowercase q followed by a number. Must be unique within a quiz.
Explanations — the part the validator can't check, but matters
The explanation field is the entire pedagogical payoff. The kid reads
it after submitting answers. A good explanation:
- Cites the paragraph. "Paragraph 2 says..." not just "Read the text."
- Explains why the right answer is right — connect it to a rule or a piece of evidence, not just the right letter.
- Explains why each distractor is wrong when the distractors are plausible (e.g. for true/false where the wrong direction is tempting).
- Aims at a 9–12-year-old. No "thus", no "consequently". Short sentences.
- For grammar questions, names the rule. "We use 'be + verb-ing' (present continuous) to describe what's happening right now."
A weak explanation that "passes" the validator but disappoints kids:
The answer is "yellow".
A good one:
Paragraph 1 says: "Mia is wearing a yellow swimsuit and a big straw hat." Red is the colour of her bucket and green is her spade — those are distractors that appear in the text but describe other things.
If you find yourself writing a one-line explanation, you're underdelivering.
Highlights — ==phrase== inside paragraphs
Wrap a phrase (or short sentence) in ==…== inside any paragraph string
and the renderer turns it into a <mark> with a soft marigold underlay.
Use it to flag the line a question probes — the kid's eye lands there
when they re-read.
"paragraphs": [
"Mbappé was ==incredibly fast==. He could run past defenders as if they were standing still."
]
Guidelines:
- 1–2 highlights per essay total (not per paragraph). Over-highlighting defeats the purpose.
- Highlight the evidence a question targets, not random vocabulary.
Vocabulary lookups belong in the
vocabularyblock. - Highlights are visual only — no tooltip, no note, no behaviour. Just a wash of colour.
- The marker is
==(two equals signs). It nests inside an existing paragraph string; no new field is required and the schema is unchanged except for the new paragraph-object form below.
Inline paragraph images
Any item in paragraphs[] can be either a plain string (the historical
shape) OR an object {text, image?}. The image renders right after that
paragraph, inside the ruled essay body. Use it when the picture belongs
to a specific moment in the story rather than the whole essay.
"paragraphs": [
"First paragraph as a plain string.",
{
"text": "Second paragraph; the picture below illustrates the scene.",
"image": {
"src": "/images/2026-W19/scene.webp",
"alt": "describe what the kid would see",
"caption": "Optional caption."
}
},
"Third paragraph, plain string again."
]
Constraints:
- Same path/extension/cap rules as the top-level
essay.image(/images/<week>/<slug>.<ext>, ≤ 1 MB, validator checks the file exists). - Inline and hero (top-level) images can coexist — hero sits above the essay, inline sits between the relevant paragraphs.
- If you don't need an inline image on a given paragraph, leave it as a
plain string. Don't write
{text: "...", image: null}— the schema rejects it.
Audio & images — both optional
Both essay.audioUrl and essay.image can be left out entirely. The UI
just doesn't render those sections. Don't insert empty strings or
placeholder URLs — that breaks the schema regex.
When you do include them, two URL forms work:
Form 1: file in the repo (preferred)
| Asset | Path | Reference in JSON | Cap | Extensions |
|---|---|---|---|---|
| audio | public/audio/<week>/<slug>.<ext> |
/audio/<week>/<slug>.<ext> |
5 MB | .mp3 .m4a .ogg |
| image | public/images/<week>/<slug>.<ext> |
/images/<week>/<slug>.<ext> |
1 MB | .png .jpg .jpeg .webp .gif .svg |
The <week> segment in the path must equal the quiz's week field. The
slug is lowercase letters/digits/dot/dash/underscore (no spaces).
Validator fails the build if the file is missing or over the cap.
This form is preferred because the asset ships in the same PR as the JSON — review and rollback are atomic, no S3 bucket or CORS to manage.
Form 2: external https:// URL
For when the asset already lives on a CDN you control:
- Must be
https://(http is rejected — browser blocks mixed content) - Must end in one of the allowed extensions above
- Host must serve
Access-Control-Allow-Origin: *(or the app origin)
Vocabulary pronunciation: free, automatic
The site uses the browser's built-in Web Speech API to pronounce each
vocabulary word — there's a 🔊 button next to every entry, served by the
device's speech synthesizer. You don't need to ship audio for
individual words. Just include the vocabulary array.
PR conventions
| Field | Value |
|---|---|
| Branch | quiz/<week> (e.g. quiz/2026-W19) |
| PR title | quiz: <week> <title> (e.g. quiz: 2026-W19 A Day at the Beach) |
| Body | Fill from .github/PULL_REQUEST_TEMPLATE.md (auto-filled by gh pr create) |
| One quiz per PR | Don't bundle multiple weeks |
| Base branch | main |
The PR body should call out which KET/PET points the questions cover — that's what the human reviewer cares about (alongside whether the explanations are good).
Manual gh invocation if you're not using scripts/open-pr.sh:
gh pr create \
--repo zxkane/english-weekly-quiz \
--base main \
--head "quiz/2026-W19" \
--title "quiz: 2026-W19 A Day at the Beach" \
--body-file - <<'EOF'
## Week
2026-W19
## Theme
A day at the beach with grandparents — describes scenes, weather, simple
present continuous, KET wordlist nouns.
## KET/PET points covered
- present continuous for current actions
- prepositions of place (on/under)
- KET vocabulary: swimsuit, spade, sandcastle, seagull
- locating specific information in a short narrative
## Checklist
- [x] File at content/quizzes/2026-W19.json with matching `week` field
- [x] `npm run validate-content` passes locally
- [x] `npm run build` passes locally
- [x] Every question has a kid-friendly `explanation` (not just "see paragraph 2")
- [x] Each `multiple_choice` answer matches one of its `options`
- [x] No real names or sensitive info in the essay
EOF
What the validator catches (and doesn't)
Catches automatically:
- JSON parse errors
- Missing/wrong-typed required fields
weekmismatch with filenamepublishedAtnot equal to the Sunday ofweek- Duplicate question ids
multiple_choice.answernot inoptionstrue_false.answernot"true"/"false"- Missing audio/image file at the path you referenced
- Audio > 5 MB or image > 1 MB
- Question count outside 3–20
- Any vocabulary entry missing a non-empty
translations.zh
Does not catch (you have to be careful):
- Whether the explanation actually teaches anything
- Whether all four MC distractors are reasonable (one absurd option = bad question, but valid JSON)
- Factual errors (the essay says "Friday", question says "Saturday")
- Whether the audio matches the essay paragraphs
- Whether the image is appropriate for the essay
- Whether the KET/PET point you tagged matches the question
Don't
- Don't auto-merge. This is kid-facing content. A human reviews.
- Don't push directly to
main. Always go through a PR. - Don't invent fields. The schema rejects unknown properties (it has
additionalProperties: false). If you think a field would be useful, PR a change tocontent/schema.jsonseparately. - Don't reuse a week filename. If
2026-W19.jsonalready exists incontent/quizzes/, you're submitting a different week or you're editing an existing quiz (ask the user which). - Don't put
http://URLs anywhere (browsers block mixed content). - Don't strip the audio control "manually" by setting
audioUrlto""ornull. Just omit the field entirely.
When things go wrong
If npm run validate-content fails: read the error, fix the JSON, run
again. The validator's messages tell you the exact issue (path, expected
value, actual value).
If npm install fails: check Node version (node --version should be
≥ 20.20). The repo uses Vite 7 which needs a recent Node.
If gh pr create fails with auth errors: the agent needs gh auth login to be done already. Don't try to run that interactively — bail
out and tell the user to authenticate.
If the Amplify build fails after the PR is open: read the build log (linked from the PR), fix the issue, push another commit. Amplify auto-rebuilds.
Files in this skill
assets/quiz-template.json— minimal valid quiz, copy to start fromscripts/iso-sunday.sh—<YYYY-Www>→ Sunday datescripts/open-pr.sh— end-to-end: validate, push, gh pr createreferences/contract.md— full schema details, read if a constraint isn't covered above