SuperAPI AI Directory

submit-weekly-quiz

General & other

View repository

Updated 10-16 12:32

About this skill

Submit a weekly quiz

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:

  1. 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-Www with a 2-digit week (e.g. 2026-W19).

  2. Compute the Sunday. publishedAt MUST be the Sunday of that ISO week — the validator computes the expected Sunday from week and fails the build if publishedAt doesn'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).

  3. Clone or cd into the repo:

    git clone https://github.com/zxkane/english-weekly-quiz.git
    cd english-weekly-quiz
    git checkout -b quiz/2026-W19
    npm install
    
  4. Write the JSON. Start from the template:

    cp <skill-dir>/assets/quiz-template.json content/quizzes/2026-W19.json
    

    Then fill it in. The structure is documented inline below; for the full schema details (every field, every constraint), see references/contract.md.

  5. (Optional) Drop in audio / image under public/audio/<week>/<slug>.<ext> and/or public/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.

  6. Validate locally:

    npm run validate-content
    

    Fix any reported errors. Don't push a failing JSON — Amplify will reject it and the PR build will go red.

  7. 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).

  8. 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 vocabulary block.
  • 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
  • week mismatch with filename
  • publishedAt not equal to the Sunday of week
  • Duplicate question ids
  • multiple_choice.answer not in options
  • true_false.answer not "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 to content/schema.json separately.
  • Don't reuse a week filename. If 2026-W19.json already exists in content/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 audioUrl to "" or null. 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 from
  • scripts/iso-sunday.sh — <YYYY-Www> → Sunday date
  • scripts/open-pr.sh — end-to-end: validate, push, gh pr create
  • references/contract.md — full schema details, read if a constraint isn't covered above