# School Awards Ceremony

> Reuse a proven stage-website framework to produce a school recognition / campus ceremony on a big screen. The skill preserves the product framework (motion, navigation, music fade, reveal, layout contract) and only swaps the visual theme, roster data, and music per event. Use for a new or revised ceremony, campus event, grade-transition or entrance ceremony, or any animated stage program where the visual system must stay gorgeous and the page is never static.

- Skill: `wuyue12-tech/school-awards-ceremony` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add wuyue12-tech/school-awards-ceremony`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wuyue12-tech/school-awards-ceremony/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wuyue12-tech (https://skillmd.com/u/wuyue12-tech)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/wuyue12-tech/school-awards-ceremony

---


# School Awards Ceremony

Reuse the preserved product framework; never regenerate the stage page from scratch. Keep `event.json` as the only editable source of truth; generate runtime data, operating documents, and the finished site from it.

## Leading Principle: The Visual System Is First-Class

The value of this framework is the **kinetic experience** a slide deck cannot deliver. Every event must be animated, never a static page. So the visual system is confirmed **before** the roster and program are built, and it is an asset that is preserved and reused, not re-authored.

Read `references/visual-system.md` before any design work. It defines the three hard contracts:

- **Motion contract**: every scene has an entrance + ambient layer, seamless themed transitions, a same-page one-shot reveal (all roster items appear at once, never in batches), and a gathering closing climax. The framework guarantees these; themes provide the visual style only.
- **Layout contract**: the award-title anchor is the **top-left corner**, and every roster/name list uses a fixed framework-level grid (one screen, no scroll). Themes may change color / type / texture but not the layout skeleton.
- **Theme contract**: a theme is a self-contained `themes/<name>/{theme.css,fonts/,images/}`. It owns appearance only; it never owns behavior or layout.

## General Principles (co-creation, not template-copying)

1. **The author decides; the AI proposes.** The author owns the event. The AI offers structures, options, and candidates for the visual system, music, copy, and roster — but the author makes the choice.
2. **When in doubt, ask.** If the AI cannot determine something that would materially change the result, stop and ask the author rather than guessing or borrowing from a previous event. Ask one to a few focused questions.
3. **An explicit author instruction is executed decisively.** Once the author gives a clear instruction, carry it out fully and faithfully; do not quietly swap in a different plan, default, or "improvement".
4. **Reuse method and framework, never content.** The skill reuses the engine, the motion / layout / theme contracts, and the workflow. It never copies the previous event's music, wording, imagery, roster, or theme skin verbatim.
5. **Source real, licensed assets.** Use publicly available free assets (open fonts, CC0 / Mixkit / Pixabay imagery and audio) and record each source + license. Confirm the author's choice before wiring them in.

## What to Preserve vs What to Confirm

The skill preserves the **framework and method**; it never carries an event's content into the next one.

**Preserve and reuse without asking (the reusable assets):**
- Engine behavior: navigation, `M`/`Esc` menu, blackout, fullscreen, music fade-in/out, same-page one-shot reveal (all names at once), scene transitions, the motion contract.
- The layout + motion contract: title anchor top-left, framework-level roster grid, scenes are never static.
- The theme contract and the proven theme skins as swappable visual systems.
- The creation workflow and the component-extension interface.
- **The runtime content overlay**: `site/content.json` is a live-editable file the page reads at load and re-reads during setup. It overrides page text (names, teams, honorees, titles, subtitles, totals) and is preserved across rebuilds. Editing it and refreshing updates the page with no rebuild — the operator owns the content file; `event.json` owns structure.
- **The closing hold rule**: the closing page stays on screen at least `closing_hold_seconds` (default 40) before fading out, so the host isn't cut off and the ending isn't rushed.

**Confirm with the author before adding (do not copy the previous event):**
- **Visual system / theme**: which theme, or build the author's own visual direction (north star, colors, motif). Never reuse a theme blindly.
- **Music**: present candidates, let the author pick (or supply tracks), then wire. Never auto-seed the previous event's tracks.
- **Sound effects**: only add if the author confirms; omit playful / game-style SFX by default.
- **Copy / text**: opening line, thank-you lines, closing lines, award names come from author data. The framework never hard-codes theme-specific copy (e.g. star imagery).
- **Roster / names / media**: per-event and private; never packaged into the skill.

## Building a Theme From a Reference

- The visual system (theme) is derived from the **author's visual reference image** (a screenshot, poster, slide deck, previous event page, or mood board). Ask what to preserve and what to avoid; never invent a theme.
- Build the theme from **publicly available free assets**: open fonts, CC0 / Mixkit / Pixabay imagery and audio, textures. Record each asset's source and license; prefer assets that allow commercial use.
- A theme is not "change a color"; it is a full visual subsystem: colors, typography, background / particle motif, entrance / transition / reveal / closing styles, materials. The framework only triggers them.

## Typography

- Fonts must carry **artistic intent**, especially the title font. Prefer **calligraphy / brush** display type (e.g. 龙藏 LongCang, 指尖的新 Zhi Mang Xing — open-license Google Fonts) over plain Songti / Kaiti for headline scenes.
- Body and operator text keep a clean sans (PingFang / Microsoft YaHei) for distance readability.
- Provide a **reference font** for the author to confirm first; only fine-tune glyph choice, weight, and effect after approval.
- Bundle a licensed local display font when the venue computer may lack system calligraphy faces.

## Workflow

1. **Pick the visual system first.** Confirm the visual north star and one concrete visual reference. Read `references/visual-system.md`. If reusing a preserved theme, select `assets/themes/<name>`; if the event needs a new theme, build a self-contained theme per `assets/themes/THEME-CONTRACT.md`. Tooling must run before any data build; do not use a generic theme as a stand-in.
2. Confirm foundation facts: event title, date, venue, duration, audience, whether the event is a grade-transition or entrance ceremony.
3. Intake the complete segment list in the author's desired order. Accept ordinary language such as “开场—颁奖—学生发言—抽奖—表演—惊喜—谢幕”; do not require program-type names. Read `references/program-intake.md`.
4. Map each segment to an existing component (`type`) whose behavior matches. If the event needs a behavior no component covers, add a component (renderer + data contract + optional music slot + optional asset slots) as an extension; do not rewrite the engine or the motion/navigation experience.
5. Define one event mainline. Give every segment a purpose such as recognition, student presentation, interaction, transition, or closure. Preserve every author-requested segment unless the author agrees to remove or merge it.
6. Record the confirmed event info, program (order preserved), assets (music + media paths), and creative direction (visual system + music decision) in `event.json`. Keep a status `pending` until the author confirms.
7. Import award/roster data with `scripts/import_awards.py`. Stop on count mismatches or duplicate names within one award; never guess or silently repair a name. If an import changes program nodes, ask the author to reconfirm the resulting order.
8. **Wire music.** Assign a track to every confirmed segment's music slot in `assets`, and record sources in `audio/SOURCES.md`. If background music is confirmed, a slot left empty is a build error, not a silent gap.
9. Build with `scripts/build_event.py` — it copies the preserved framework into `site/`, applies the selected theme, injects generated data, and wires media. Then validate with `scripts/validate_event.py`. Treat errors as delivery blockers and warnings as explicit rehearsal decisions.
10. Run the visual QA gate. Render at least three representative scenes, compare them to the reference for composition / color / motif; confirm the page is dynamic (not static), the title anchor is top-left, rosters fit one screen, and scene transitions are smooth. Read `references/visual-system.md` §5.
11. Rehearse navigation, media playback, blackout, menu jumps, the one-shot reveal, and closing. Read `references/qa-checklist.md` for the complete gate.
12. Put final artifacts in `deliverables/`, raw inputs in `materials/`, and retired process files in `archive/`. Keep each event's `event.json`, roster, theme copy, and media in the event project; do not store per-event names, photos, or private media inside the skill.

## Commands

Set the skill path explicitly; do not assume `CODEX_HOME` is configured.

```bash
python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/create_event.py \
  --output /absolute/path/to/new-event \
  --title "学段成长表彰会" --date "2026-09-01" \
  --venue "学校报告厅" --duration-minutes 80

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/import_awards.py \
  --event /absolute/path/to/new-event/event.json \
  --xlsx /absolute/path/to/awards.xlsx

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/build_event.py \
  --event /absolute/path/to/new-event/event.json \
  --theme campus-light   # optional; defaults to event.json visual.theme, then space-gold

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/validate_event.py \
  --event /absolute/path/to/new-event/event.json
```

`create_event.py` scaffolds the event workspace (no runtime site); `build_event.py` copies the preserved `assets/framework/`, applies the selected `assets/themes/<name>/`, injects generated `data.js` / `game-data.js`, wires music, and enforces the `music_scope` rule (e.g. `award_only` requires the award slot and errors if it is empty). `validate_event.py` runs the delivery checks.

If the environment provides a bundled Python runtime, prefer it when the default `python3` is unavailable. The scripts use only the Python standard library.

## Decision Rules

- Preserve confirmed names, counts, award order, and fixed school requirements exactly.
- Let the author decide which segments exist and their order. Translate the list into technical configuration; do not make the author adapt the event to the template.
- Whenever a segment is added, removed, merged, or reordered, set `program_confirmation.status` back to `pending` and ask the author to confirm the complete order again.
- Do not reject an author-requested lottery, surprise, announcement, countdown, or other unfamiliar segment merely because no current renderer exists. Record its intended现场动作 and extend the framework before final build.
- Ask only for missing decisions that materially change the event. Record all other gaps in the QA report.
- Ask the author for a visual-system sample before designing the interface. Accept a screenshot, website, slide deck, poster, previous event page, or other concrete reference; ask what to preserve and what to avoid.
- Ask the author what kind of background music they want before selecting tracks. Accept mood words or reference tracks and confirm whether vocals are allowed; "no background music" is a valid confirmed decision.
- Ask whether simulated rehearsal is needed. If no, run the normal technical and delivery checks without requesting a host script.
- If simulated rehearsal is needed, require a host script supplied by the author. Use it as evidence; do not invent missing host lines, including emergency transitions. Mark gaps and ask whether the author wants help drafting them.
- Use the plain term “突发情况演练”, not “故障注入”. Include it only when the author opts in, and select three to five real high-risk situations rather than creating an exhaustive disaster list.
- Continue roster cleanup and factual flow work while creative direction is pending, but do not present a generic theme or arbitrary music choice as a finished design.
- Keep framework, event data, and media separate. Change the framework only when the requested segment cannot be represented by the existing program types.
- Do not package student names, teacher photos, private media, or one-off event data into this skill.
- For an ordinary awards ceremony, use the general workflow only. For a grade-transition or entrance ceremony, also read `references/entrance-ceremony-rules.md`.
- 屏幕显示的文字与名单以 `site/content.json` 为**现场唯一编辑口**（保存即实时生效，需通过 `打开仪式页面.command` 提供的 http 服务打开）。`event.json` 只作构建配方；改结构/顺序/媒体/主题走 event.json 后重建，改现场文字/名单直接改 content.json。
- Generate an event package before polishing visual details. A polished screen does not compensate for an incorrect roster or an unworkable run of show.

## References

- Read `references/workflow.md` when planning the activity, assigning roles, or defining deliverables.
- Read `references/program-intake.md` before creating or changing the program.
- Read `references/creative-direction.md` before creating the visual system or selecting background music.
- Read `references/rehearsal-simulation.md` before requesting a host script or preparing role-based rehearsal materials.
- Read `references/data-contract.md` before changing `event.json` or adding a program type.
- Read `references/qa-checklist.md` before rehearsal, delivery, or archive handoff.
- Read `references/entrance-ceremony-rules.md` only when the ceremony includes a formal grade transition or identity change.

## Completion Standard

Finish only when the author has confirmed the complete segment list and order, confirmed or explicitly waived the visual reference, confirmed the background-music decision, answered whether simulated rehearsal is needed, the generated site loads, all referenced media exists, award counts reconcile with source data, no unknown program type remains, rehearsal and live-operation sheets are current, and validation returns no errors. When simulation is requested, also require the author-supplied host script, complete selected-role cues, and current simulation documents.