Submit content to football-english

You are submitting one piece of kid-facing English content to zxkane/football-english. The site is purely static — your JSON + optional audio/image files + a PR are the entire publishing mechanism.

The repo's

CONTRIBUTING.md

and

content/schema.json

are the source of truth, but this skill encodes their rules so you don't have to re-read them every submission.

Step 1 — Pick the kind: weekly quiz or daily reading?

The repo publishes two parallel content kinds. Picking the right one is the most important call you make in this skill — they have different filenames, schemas, URLs, and pedagogical purposes.

Kind	When	File	URL
weekly quiz	Once per ISO week. Essay + 3-20 graded questions. Tests the kid's reading comprehension.	`content/quizzes/<YYYY-Www>.json`	`/quiz/<week>`
daily reading	Irregular cadence (not strictly daily). Essay (120-220 words, 3-4 paragraphs) + TTS audio + image + structured KET/PET points + optional 0-3 small questions. Input-focused — listen, read, learn a point.	`content/dailies/<YYYY-MM-DD>-<slug>.json`	`/daily/<date>-<slug>`

How to decide:

The user says "weekly quiz", "this week's quiz", "open a quiz PR", gives 3+ graded questions, or names an ISO week → weekly quiz.
The user says "daily reading", "today's essay", "add today's reading", "daily article", hands over a short essay focused on a few KET/PET points (grammar, expressions, wordlist), or expects audio + image as the main draw → daily reading.
Ambiguous: ask. The two are not interchangeable; submitting the wrong kind means re-doing the JSON and the PR.

Once you've picked, follow the variant below and load its reference file when you need the exact schema:

Weekly quiz → continue at "Weekly quiz workflow"; load
```
references/weekly.md
```
for the full schema.
Daily reading → continue at "Daily reading workflow"; load
```
references/daily.md
```
for the full schema.

Shared steps (both kinds)

Whichever kind you're submitting, these steps are identical:

Be in a clone of the repo. If the user doesn't have one:

bash

git clone https://github.com/zxkane/football-english.git
cd football-english
npm install

Branch from
main
. Branch name depends on kind (see below).
Write the JSON from the relevant template under
```
assets/
```
.
Drop assets (audio/image) under the kind-specific path. Both are optional for weekly quizzes; image is recommended and audio is strongly encouraged for daily readings since TTS is the whole point.
Validate locally:
```
npm run validate-content
```
— runs against both kinds in the same pass. Don't push if it fails; the Amplify build will reject it anyway.
Open the PR via
```
scripts/open-pr.sh <kind> ...
```
(see below). Stop at PR open. Do not auto-merge — the site is kid-facing and a human reviews every PR.

Weekly quiz workflow

Filename + dates have a tight invariant:

week

field, filename, and

publishedAt

(Sunday of that ISO week) must all agree, or the validator fails the build.

bash

# 1. Identify the ISO week (e.g. 2026-W19) and its Sunday.
bash scripts/iso-sunday.sh 2026-W19   # → 2026-05-10

# 2. Branch.
git checkout -b quiz/2026-W19

# 3. Start the JSON from the template.
cp <skill-dir>/assets/quiz-template.json content/quizzes/2026-W19.json
# Then fill it in. See references/weekly.md for every field's
# constraint, the question-type table, the vocabulary translation rule,
# and the highlight/inline-image syntax.

# 4. Optionally drop assets:
#    - audio: public/audio/2026-W19/<slug>.mp3   (≤ 5 MB)
#    - image: public/images/2026-W19/<slug>.webp (≤ 1 MB)

# 5. Validate, then open the PR.
npm run validate-content
bash <skill-dir>/scripts/open-pr.sh quiz 2026-W19 "A Day at the Beach"

Branch naming:

quiz/<week>

. PR title:

quiz: <week> <title>

. Body auto-generated by

open-pr.sh

from the JSON's tags + KP points.

The 90% case is captured above. For the long tail (when to use a highlight vs. an inline image, fill_blank's

acceptableAnswers

, vocabulary translation rules, audio/image regex patterns), load

references/weekly.md

Daily reading workflow

Filename has a tight invariant: it must equal

<date>-<slug>.json

where

date

and

slug

are the JSON's

date

and

slug

fields.

bash

# 1. Pick the date (today, usually) and a slug. Slug is lowercase,
#    digits, hyphens; 5-60 chars. The whole filename is date-slug.
DATE=2026-05-10
SLUG=mbappe-final-2018

# 2. Branch.
git checkout -b daily/${DATE}-${SLUG}

# 3. Start the JSON from the template.
cp <skill-dir>/assets/daily-template.json content/dailies/${DATE}-${SLUG}.json
# Then fill it in. See references/daily.md for every field's constraint,
# the ketPetPoints[] structure (point + explanation + exampleFromEssay
# + translations.zh), and the optional 0-3 questions block.

# 4. Drop assets — strongly recommended for daily readings since TTS
#    audio + image are the main hook:
#    - audio: public/audio/daily/<date>-<slug>/<slug>.mp3   (≤ 5 MB)
#    - image: public/images/daily/<date>-<slug>/<file>     (≤ 1 MB each)

# 5. Validate, then open the PR.
npm run validate-content
bash <skill-dir>/scripts/open-pr.sh daily ${DATE}-${SLUG} "Mbappé and the 2018 Final"

Branch naming:

daily/<date>-<slug>

. PR title:

daily: <date> <title>

. Body auto-generated by

open-pr.sh

from the JSON's tags + KP points.

The daily-specific fields (

date

slug

ketPetPoints[]

, optional small

questions[0..3]

, asset paths under

public/{audio,images}/daily/

) are documented in

references/daily.md

. Load that when you need exact constraints — the in-skill summary above is intentionally short.

Common rules across both kinds

These apply identically and are why the two kinds share one skill:

Highlights —

==phrase==

inside any paragraph

Wrap a phrase in

==…==

and the renderer makes it a

<mark>

with a soft marigold underlay. Use sparingly: 1-2 highlights per piece, on the sentence the questions / KP points probe. The marker doesn't nest and doesn't cross paragraphs.

Inline paragraph images

Any item in

paragraphs[]

may be a string OR

{text, image?}

. The image renders right after that paragraph. Same path/cap rules as the hero image; the validator checks the file exists.

Vocabulary block —

translations.zh

is required when present

Both kinds support an optional

essay.vocabulary

array. The block itself is optional, but if you include it, every entry MUST carry a non-empty

translations.zh

. The kid-facing audience is Chinese-native and the "译" toggle in the UI is how they unlock meaning when stuck; missing zh breaks that experience and the validator fails the build.

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 for 2-3 sense-disambiguating glosses when one Chinese word doesn't capture the nuance:

English	Good zh	Bad zh
`incredibly`	`难以置信地；极其`	`这个词的意思是非常的程度高得让人难以相信` (paraphrase)
`defender`	`后卫（防守球员）`	`防守的人` (too vague — kid doesn't learn the football term)
`tournament`	`锦标赛；联赛`	`比赛` (loses the multi-team-competition meaning)

Audio & images — two URL forms

Form	Use when	Constraint
Local path under `public/...` (preferred)	Always, when you have the asset on hand	Path must equal what the kind requires (see workflows above); validator checks file exists; audio ≤ 5 MB; image ≤ 1 MB
`https://` URL on a CDN you own	Asset already lives elsewhere	Must be `https://` (http blocked as mixed content); allowed extensions; host must serve `Access-Control-Allow-Origin: *`

Don't insert empty strings or

null

to "hide" audio/image — the schema rejects those. Just omit the field entirely.

Vocabulary pronunciation is free

The site uses the browser's Web Speech API to pronounce each vocabulary word — there's a 🔊 button next to every entry. You don't need to ship audio for individual words. Just include the

vocabulary

array.

Don't auto-merge

Both kinds are kid-facing. A human reviews before merge.

open-pr.sh

stops at PR open by design.

When to load which reference

The two reference files cover the parts that don't fit in this body:

```
references/weekly.md
```
— full weekly-quiz schema: every field's regex/range, question-type rules, fill_blank's
```
acceptableAnswers
```
semantics, audio/image regex patterns, what the validator catches and doesn't.
```
references/daily.md
```
— full daily-reading schema:
```
date
```
/
```
slug
```
rules,
```
ketPetPoints[]
```
structure, the optional small-questions cap, asset paths under
```
public/{audio,images}/daily/
```
.

Read only the one matching the kind you're submitting. They're ~250 lines each, so loading both is wasteful.

When things go wrong

npm run validate-content
fails: read the error — the messages cite the path, expected, and actual. Fix the JSON and re-run.
npm install
fails: check Node ≥ 20.20 (the repo uses Vite 7).
gh pr create
auth error: the runtime needs
```
gh auth login
```
done already. Don't try interactive login; bail out and ask the user.
Amplify build fails after PR opens: read the build log linked from the PR, fix, push another commit. Amplify auto-rebuilds.

Files in this skill

skills/submit-content/
├── SKILL.md                 # this file (entry point + decision tree)
├── README.md                # install instructions for skills.sh
├── assets/
│   ├── quiz-template.json   # weekly-quiz scaffold
│   └── daily-template.json  # daily-reading scaffold
├── scripts/
│   ├── iso-sunday.sh        # YYYY-Www → Sunday date (weekly only)
│   └── open-pr.sh           # parameterized: open-pr.sh <kind> ...
├── references/
│   ├── weekly.md            # full weekly-quiz schema reference
│   └── daily.md             # full daily-reading schema reference
└── evals/
    └── evals.json           # documented test prompts (no auto-runner)

submit-content

NPX Install

Tags

SKILL.md Content

Submit content to football-english

Step 1 — Pick the kind: weekly quiz or daily reading?

Shared steps (both kinds)

Weekly quiz workflow

Daily reading workflow

Common rules across both kinds

Highlights —
`==phrase==`
inside any paragraph

Inline paragraph images

Vocabulary block —
`translations.zh`
is required when present

Audio & images — two URL forms

Vocabulary pronunciation is free

Don't auto-merge

When to load which reference

When things go wrong

Files in this skill