Back to Details

submit-content

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Submit content to football-english

向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.
你将向zxkane/football-english提交一份面向儿童的英语内容。该网站是纯静态的——你的JSON文件+可选的音频/图片文件+一个PR就是完整的发布机制。
仓库的
CONTRIBUTING.md
和
content/schema.json
是权威依据，但本技能已整合其中规则，无需每次提交都重新阅读。

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

步骤1 — 选择内容类型：每周测验还是每日阅读材料？

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.
KindWhenFileURL
weekly quizOnce per ISO week. Essay + 3-20 graded questions. Tests the kid's reading comprehension.
content/quizzes/<YYYY-Www>.json
/quiz/<week>
daily readingIrregular 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.
该仓库发布两种并行内容类型。选择正确的类型是使用本技能最重要的环节——它们的文件名、schema、URL和教学目的均不同。
类型适用场景文件路径URL
每周测验每个ISO周发布一次。文章 + 3-20道分级题目。测试孩子的阅读理解能力。
content/quizzes/<YYYY-Www>.json
/quiz/<week>
每日阅读材料发布周期不固定（非严格每日）。文章（120-220词，3-4段） + TTS音频 + 图片 + 结构化KET/PET知识点 + 可选0-3道小题。以输入为核心——听、读、学习知识点。
content/dailies/<YYYY-MM-DD>-<slug>.json
/daily/<date>-<slug>
判断方法：
  • 用户提到“每周测验”“本周测验”“发起测验PR”，提供3道以上分级题目，或指定ISO周 → 每周测验。
  • 用户提到“每日阅读材料”“今日文章”“添加今日阅读内容”“每日文章”，提供聚焦少量KET/PET知识点（语法、表达、词汇表）的短文，或期望音频+图片作为核心内容 → 每日阅读材料。
  • 情况模糊：询问用户。两种类型不可互换，提交错误类型意味着需要重新编写JSON和PR。
确定类型后，遵循下方对应流程，如需精确schema可加载参考文件：
  • 每周测验 → 继续查看“每周测验工作流”；加载
    references/weekly.md
    获取完整schema。
  • 每日阅读材料 → 继续查看“每日阅读工作流”；加载
    references/daily.md
    获取完整schema。

Shared steps (both kinds)

通用步骤（两种类型均适用）

Whichever kind you're submitting, these steps are identical:
  1. 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
  2. Branch from 
    main
    .     Branch name depends on kind (see below).
  3. Write the JSON from the relevant template under 
    assets/
    .
  4. 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.
  5. 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.
  6. 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.
无论选择哪种类型，以下步骤完全相同：
  1. 确保已克隆仓库。如果用户尚未克隆：
    bash
    git clone https://github.com/zxkane/football-english.git
cd football-english
npm install
  2. 基于
    main
    分支创建新分支    。分支名称取决于内容类型（见下方说明）。
  3. 根据
    assets/
    下的对应模板编写JSON    。
  4. 放置资源文件（音频/图片）到对应类型的路径下。每周测验的两项资源均为可选；每日阅读材料建议提供图片，且强烈建议提供音频，因为TTS是核心功能。
  5. 本地验证：执行
    npm run validate-content
    ——该命令会同时验证两种类型的内容。验证不通过请勿推送，Amplify构建会直接拒绝。
  6. 通过
    scripts/open-pr.sh <kind> ...
    发起PR    （见下方说明）。PR发起后即停止操作。请勿自动合并——该网站面向儿童，所有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
undefined
文件名和日期有严格约束：
week
字段、文件名和
publishedAt
（对应ISO周的周日）必须完全一致，否则验证器会导致构建失败。
bash
undefined

1. Identify the ISO week (e.g. 2026-W19) and its Sunday.

1. 确定ISO周（例如2026-W19）及其对应的周日日期。

bash scripts/iso-sunday.sh 2026-W19 # → 2026-05-10
bash scripts/iso-sunday.sh 2026-W19 # → 2026-05-10

2. Branch.

2. 创建分支。

git checkout -b quiz/2026-W19
git checkout -b quiz/2026-W19

3. Start the JSON from the template.

3. 基于模板创建JSON文件。

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

Then fill it in. See references/weekly.md for every field's

然后填充内容。请查看references/weekly.md了解每个字段的约束、题目类型表、词汇翻译规则，以及高亮/行内图片语法。

constraint, the question-type table, the vocabulary translation rule,

4. 可选放置资源文件：

and the highlight/inline-image syntax.

- 音频：public/audio/2026-W19/<slug>.mp3 （≤ 5 MB）

4. Optionally drop assets:

- 图片：public/images/2026-W19/<slug>.webp （≤ 1 MB）

- audio: public/audio/2026-W19/<slug>.mp3 (≤ 5 MB)

5. 验证内容，然后发起PR。

- 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`](references/weekly.md).
npm run validate-content bash <skill-dir>/scripts/open-pr.sh quiz 2026-W19 "A Day at the Beach"

分支命名规则：`quiz/<week>`。PR标题：`quiz: <week> <title>`。PR正文由`open-pr.sh`自动从JSON的标签和KP知识点生成。

上述步骤覆盖90%的常见场景。对于特殊情况（如何时使用高亮而非行内图片、fill_blank类型题的`acceptableAnswers`语义、词汇翻译规则、音频/图片正则模式），请加载[`references/weekly.md`](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
undefined
文件名有严格约束：必须为
<date>-<slug>.json
，其中
date
和
slug
需与JSON中的
date
和
slug
字段完全一致。
bash
undefined

1. Pick the date (today, usually) and a slug. Slug is lowercase,

1. 选择日期（通常为当日）和slug。slug由小写字母、数字、连字符组成，长度为5-60字符。完整文件名为date-slug。

digits, hyphens; 5-60 chars. The whole filename is date-slug.

—
DATE=2026-05-10 SLUG=mbappe-final-2018
DATE=2026-05-10 SLUG=mbappe-final-2018

2. Branch.

2. 创建分支。

git checkout -b daily/${DATE}-${SLUG}
git checkout -b daily/${DATE}-${SLUG}

3. Start the JSON from the template.

3. 基于模板创建JSON文件。

cp <skill-dir>/assets/daily-template.json content/dailies/${DATE}-${SLUG}.json
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,

然后填充内容。请查看references/daily.md了解每个字段的约束、ketPetPoints[]结构（知识点+解释+文中示例+translations.zh），以及可选的0-3道小题模块。

the ketPetPoints[] structure (point + explanation + exampleFromEssay

4. 放置资源文件——每日阅读材料强烈建议提供，因为TTS音频+图片是核心吸引力：

+ translations.zh), and the optional 0-3 questions block.

- 音频：public/audio/daily/<date>-<slug>/<slug>.mp3 （≤ 5 MB）

4. Drop assets — strongly recommended for daily readings since TTS

- 图片：public/images/daily/<date>-<slug>/<file> （每个≤ 1 MB）

audio + image are the main hook:

5. 验证内容，然后发起PR。

- 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`](references/daily.md). Load
that when you need exact constraints — the in-skill summary above is
intentionally short.
npm run validate-content bash <skill-dir>/scripts/open-pr.sh daily ${DATE}-${SLUG} "Mbappé and the 2018 Final"

分支命名规则：`daily/<date>-<slug>`。PR标题：`daily: <date> <title>`。PR正文由`open-pr.sh`自动从JSON的标签和KP知识点生成。

每日阅读特有的字段（`date`、`slug`、`ketPetPoints[]`、可选的`questions[0..3]`小题、`public/{audio,images}/daily/`下的资源路径）均在[`references/daily.md`](references/daily.md)中有详细说明。如需精确约束请加载该文件——上述技能内的摘要为简化版本。

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.
将短语用
==…==
包裹，渲染器会将其转换为带有柔和金盏花底色的
<mark>
标签。请谨慎使用：每份内容仅使用1-2处高亮，标记在问题/KP知识点对应的句子上。该标记不能嵌套，也不能跨段落使用。

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.
paragraphs[]
中的任意项可以是字符串，也可以是
{text, image?}
对象。图片会在对应段落之后渲染。图片路径和大小限制与主图相同；验证器会检查文件是否存在。

Vocabulary block — 
translations.zh
is required when present

词汇模块 — 若存在则必须包含
translations.zh

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:
EnglishGood zhBad zh
incredibly
难以置信地；极其
这个词的意思是非常的程度高得让人难以相信
(paraphrase)
defender
后卫（防守球员）
防守的人
(too vague — kid doesn't learn the football term)
tournament
锦标赛；联赛
比赛
(loses the multi-team-competition meaning)
两种类型均支持可选的
essay.vocabulary
数组。该模块本身是可选的，但如果添加了该模块，每个条目必须包含非空的
translations.zh
。面向的儿童用户以中文为母语，UI中的“译”按钮是他们遇到生词时获取释义的方式；缺少中文翻译会破坏用户体验，且验证器会导致构建失败。
你是大语言模型——请自行生成中文翻译，无需调用外部翻译API。目标是简短的释义（1-2个中文短语），而非英文
meaning
的意译。当一个中文词汇无法涵盖所有语义时，使用分号分隔2-3个区分语义的释义：
英文优质中文翻译劣质中文翻译
incredibly
难以置信地；极其
这个词的意思是非常的程度高得让人难以相信
（意译）
defender
后卫（防守球员）
防守的人
（过于模糊——孩子无法学到足球术语）
tournament
锦标赛；联赛
比赛
（丢失了多队竞技的含义）

Audio & images — two URL forms

音频与图片 — 两种URL格式

FormUse whenConstraint
Local path under 
public/...
(preferred)		Always, when you have the asset on handPath 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 elsewhereMust 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.
格式适用场景约束
public/...
下的本地路径（推荐）		当你手头有资源文件时路径必须符合对应类型的要求（见上方工作流）；验证器会检查文件是否存在；音频≤5 MB；图片≤1 MB
你拥有的CDN上的
https://
URL		资源已存储在其他位置必须为
https://
（http会被视为混合内容而被阻止）；允许的扩展名；主机必须返回
Access-Control-Allow-Origin: *
请勿插入空字符串或
null
来“隐藏”音频/图片——schema会拒绝此类内容。只需完全省略该字段即可。

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.
该网站使用浏览器的Web Speech API来朗读每个词汇——每个条目旁都有一个🔊按钮。无需为单个词汇提供音频文件，只需包含
vocabulary
数组即可。

Don't auto-merge

请勿自动合并

Both kinds are kid-facing. A human reviews before merge. 
open-pr.sh
stops at PR open by design.
两种类型的内容均面向儿童。合并前必须经过人工审核。
open-pr.sh
设计为PR发起后即停止操作。

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.
两个参考文件涵盖了本技能正文未包含的细节：
  • references/weekly.md
     — 完整的每周测验schema：每个字段的正则/范围约束、题目类型规则、fill_blank类型题的
    acceptableAnswers
    语义、音频/图片正则模式，以及验证器会捕获和不会捕获的内容。
  • references/daily.md
     — 完整的每日阅读schema：
    date
    /
    slug
    规则、
    ketPetPoints[]
    结构、可选小题的数量限制、
    public/{audio,images}/daily/
    下的资源路径。
仅加载与你提交的内容类型匹配的参考文件。每个文件约250行，加载两个会造成不必要的浪费。

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.
  • npm run validate-content
    执行失败：     阅读错误信息——信息会指出路径、预期值和实际值。修复JSON后重新执行。
  • npm install
    执行失败：     检查Node版本是否≥20.20（仓库使用Vite 7）。
  • gh pr create
    认证错误：     运行环境需已完成
    gh auth login
    。请勿尝试交互式登录，直接告知用户。
  • PR发起后Amplify构建失败： 查看PR链接的构建日志，修复问题后推送新的提交。Amplify会自动重新构建。

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)
skills/submit-content/
├── SKILL.md                 # 本文件（入口点+决策树）
├── README.md                # skills.sh的安装说明
├── assets/
│   ├── quiz-template.json   # 每周测验模板
│   └── daily-template.json  # 每日阅读模板
├── scripts/
│   ├── iso-sunday.sh        # 将YYYY-Www转换为周日日期（仅适用于每周测验）
│   └── open-pr.sh           # 参数化脚本：open-pr.sh <kind> ...
├── references/
│   ├── weekly.md            # 完整的每周测验schema参考
│   └── daily.md             # 完整的每日阅读schema参考
└── evals/
    └── evals.json           # 文档化的测试提示（无自动运行器）