---
name: sylvia-workshop-handbook
description: Convert a workshop MASTER source into a polished learner-first, self-contained HTML handbook while preserving technical fidelity, removing trainer-only content, contextualizing resources, and running structural/visual QA before release.
---

# Workshop Handbook Publisher

## Purpose

Turn one authoritative **MASTER** into a polished **learner-facing HTML handbook**.

The handbook is not a transcript, slide deck, or engineering document. It should feel like refined course notes: easy to scan during a workshop, detailed enough to revisit later, and safe for novice learners to follow without the trainer standing beside them.

## Core principle

**One source of truth → learner editorial → handbook structure → interactive HTML → QA → release.**

Do not patch an old handbook when a newer MASTER exists. Regenerate from the current MASTER.

---

## Inputs

Required:
- One authoritative workshop MASTER. Preferred formats: `.docx`, `.md`, `.html`, or `.txt`.

Optional:
- Previous handbook used only as a **visual reference**, never as the content source of truth.
- Brand/style instructions.
- Public links or QR destinations.
- Images that belong in the handbook.

If multiple MASTER-like files exist, identify the newest user-approved/frozen source before publishing.

---

## Outputs

Primary output:
- `Workshop_Handbook.html` — self-contained learner handbook.

Optional internal QA artifacts:
- `editorial_notes.md`
- `removal_log.md`
- `qa_report.md`

Do not expose internal QA artifacts unless the user asks.

---

# Publishing workflow

## 1. Establish the source of truth

Before editing:
1. Identify the user-approved MASTER.
2. Treat its instructional facts, sequence, prompts, code, URLs, terminology, and constraints as authoritative.
3. Do not silently replace MASTER content with general knowledge.
4. If the MASTER conflicts with an older handbook, the MASTER wins.
5. A prior handbook may guide visual style only.

If the user says the MASTER is **frozen**, do not modify it while producing the learner handbook.

---

## 2. Parse trainer-only content semantically

The MASTER may use trainer-only markers.

Supported conventions:
- `[T] text` → trainer-only paragraph/note.
- A standalone `[T]` immediately before a paragraph → the following trainer note is trainer-only.
- `## [T] Heading` → trainer-only section until the next heading of equal or higher level.
- `[T START] ... [T END]` → trainer-only range.

Important: **do not blindly delete everything marked trainer-only.**

For each marked item, classify it as:
- **REMOVE** — speaking cue, internal reminder, timing note, private setup, trainer CV detail that learners do not need.
- **CONVERT** — trainer wording contains reassurance, a conceptual bridge, safety advice, or explanation useful to learners; rewrite it as learner-facing prose.
- **KEEP ELSEWHERE** — content belongs in slides, trainer notes, or another output but not the learner handbook.

Never leave `[T]`, `[T START]`, or `[T END]` visible in the final handbook.

---

## 3. Apply learner-first editorial rules

### Keep
- Learning goals and inquiry questions.
- Learner actions and step-by-step instructions.
- Concepts learners need to understand the workflow.
- Safety checkpoints and recovery steps.
- Public workshop links.
- Required prompts, code, templates, examples, and technical facts.
- Short reassurance that lowers novice anxiety without hiding important constraints.

### Remove or simplify
- Trainer speaking scripts.
- Stage directions such as “reveal this next”.
- Internal timing notes.
- Repeated explanations already obvious from nearby content.
- Full speaker biography unless the user explicitly wants it in the handbook.
- Implementation commentary that does not change learner action.
- Version labels and internal production notes unless explicitly requested.

### Default speaker treatment
If the MASTER contains a full instructor biography, learner handbook defaults to:
- name
- institution/role
- email/contact if intended for sharing

Full CV/awards normally belong in the slide deck, not the handbook.

### Plain-language rule
Whenever a section contains many technical or English terms, add a learner-friendly explanation before the complete technical resource.

Prefer:
- “這份 Prompt 會幫你做什麼？”
- “你真正需要做的是……”
- “先做哪一步？”
- “怎樣算成功？”

Do not require novice learners to understand every implementation term before they can proceed.

---

## 4. Preserve atomic technical content

The following are **atomic resources** unless the user explicitly asks to edit them:
- prompts
- code
- configuration blocks
- exact URLs
- payload schemas
- formulas
- commands

Do not paraphrase inside an atomic resource.
Do not “clean up” code merely for style.
Do not change variable names, endpoints, field names, or workflow contracts without explicit reason.

If a shared code example contains a private or live endpoint, replace it with a clear placeholder such as:
`YOUR_GAS_WEB_APP_URL`
and add a short learner-facing instruction explaining where to insert the learner’s own URL.

---

## 5. Contextualize resources

Do not dump every resource into one giant appendix.

Place each resource where it is first used.

Recommended pattern:
1. **Summary** — what this resource is for.
2. **Expand** — complete original content.
3. **Copy** — one-click copy.
4. **Download** — optional text/code download when useful.

Examples:
- starter/template resources beside the “create” step
- central upgrade prompt beside the planning/AI step
- backend code beside technical setup
- analysis/visualization prompts beside evaluation

At the end, keep a small **Reference / Extension** section only for genuine external sources or resources that have not already appeared contextually.

---

## 6. Build information architecture around the learner journey

Use the workshop’s real instructional sequence rather than the MASTER’s raw document structure when necessary.

A good handbook usually contains:
- Start / title
- Prep
- Warm-up / why
- Core concept
- Practice workflow
- Technical preparation if required
- Step-by-step activity sections
- Testing / safety checkpoints
- Evaluation / reflection
- Production / real use
- Wrap-up
- Reference / extension

Do not invent a new taxonomy if the workshop already has one.

---

## 7. Distinguish conceptual sequence from operational preparation

If a workshop has setup work that must happen earlier for reliability, label it clearly as **Technical Prep** or equivalent.

Do not distort the conceptual framework just because setup happens earlier.

Use a learner-facing bridge such as:
> We are preparing the channel now; the actual learning-data step happens later when the approved evidence is connected.

---

## 8. Design the HTML as a handbook, not a website dashboard

Default visual direction:
- refined editorial course notes
- warm ivory/cream background
- dark forest or charcoal text
- restrained muted accent such as champagne gold or sage
- generous whitespace
- thin dividers
- subtle shadows only
- readable serif headline + highly legible body type

Avoid by default:
- neon palettes
- SaaS/dashboard chrome as the overall page language
- heavy gradients
- glassmorphism
- giant card grids
- slide-like chapter screens
- decorative animation that competes with reading

The handbook should feel calm, professional, and printable even when interactive.

See `references/HANDBOOK_STYLE.md`.

---

## 9. Interaction requirements

When resources are long, use `<details>` / `<summary>` or an equivalent accessible disclosure pattern.

For code and prompts:
- collapsed by default unless immediately needed
- clear resource title and type label
- copy button
- readable code area
- optional download button
- preserve whitespace

For important public destinations:
- provide a normal clickable link
- when useful for multi-device workshops, provide a **Show QR Code** control
- center the QR code when expanded
- QR destination must exactly match the clickable link
- do not rely on an external QR service if the asset can be embedded locally/data-URI

---

## 10. Responsive behavior

The final handbook must work on desktop and mobile.

Recommended:
- desktop: sticky/floating table of contents
- mobile: compact contents drawer/button
- no horizontal page scrolling
- code blocks may scroll horizontally internally
- tables get their own horizontal overflow container
- touch targets large enough for phones/tablets

Do not assume learners use the same screen size as the trainer.

---

## 11. Accessibility basics

Required:
- semantic heading order
- meaningful link text
- buttons are actual `<button>` elements
- visible keyboard focus
- images have useful `alt` text when informative
- sufficient text/background contrast
- disclosure controls can be operated with keyboard
- no information communicated only through color

---

# Content transformation rules

## A. Trainer notes → learner notes

Convert only when the note helps the learner act or understand.

Example:
Trainer note:
> You do not need to explain the whole prompt; tell them to focus on whether the first-round plan makes sense.

Learner version:
> 你不需要先讀懂整份 Prompt。你真正需要判斷的是：AI 第一回合提出的規劃是否符合你的教學需要。

## B. Technical jargon → two-layer explanation

Use:
- first layer: plain-language meaning
- second layer: exact technical resource

Never remove the exact technical layer if learners need it to execute the task.

## C. Repetition

If a concept appears in the narrative and again inside a full prompt/code resource:
- keep the concise explanation in the narrative
- keep the full original resource in the expandable block
- do not duplicate the full resource elsewhere

## D. Alternative path

If learners can complete the activity without the advanced technical path, show that route as a legitimate **Alternative Route**, not a failure state.

---

# Quality gates

The handbook is not finished until all gates pass.

## Content fidelity
- [ ] Current MASTER is the sole content source of truth.
- [ ] No important learner step was removed.
- [ ] Prompts/code/configuration remain exact unless deliberately edited.
- [ ] Public links are preserved correctly.
- [ ] No private/live credential or endpoint is exposed.

## Editorial
- [ ] No trainer markers remain.
- [ ] Trainer-only directions are removed.
- [ ] Useful trainer notes were converted when appropriate.
- [ ] Novice-facing explanations appear before dense technical material.
- [ ] Speaker biography follows the requested output rule.
- [ ] No unnecessary version/internal-production wording is visible.

## Resource architecture
- [ ] Core resources appear where learners use them.
- [ ] Long resources are expandable.
- [ ] Copy controls work.
- [ ] No unnecessary duplicate full resources exist.
- [ ] Final reference section contains only genuine references/extensions.

## HTML structure
- [ ] No duplicate DOM IDs.
- [ ] Every internal anchor target exists.
- [ ] No broken buttons or handlers.
- [ ] No console-breaking JavaScript syntax errors.
- [ ] Mobile layout is usable.
- [ ] Long tables/code do not break the page.

## Regression search
Search final HTML for stale concepts that should have disappeared, for example:
- old workflow names
- deprecated tool dependency
- old deployment location wording
- old version labels
- trainer tags
- placeholder text that should have been replaced

The specific stale-term list must be derived from the current project, not hard-coded forever.

## Visual QA
Open/render the final HTML at minimum:
- desktop widescreen
- narrow/mobile viewport

Check:
- title hierarchy
- clipping/overflow
- code readability
- table readability
- link/QR placement
- collapsed/expanded resource states
- final page ending

If browser rendering is unavailable, perform structural QA and clearly state the visual-QA limitation.

See `references/AUDIT_CHECKLIST.md`.

---

# Release behavior

When the handbook passes QA:
1. Write a clean final HTML file.
2. Do not append internal version notes, generation credits, or legal language unless requested.
3. Return the final file plus a short summary of material changes and QA status.
4. Never claim the MASTER was changed unless it actually was.

---

# What this Skill does NOT do

This Skill does not automatically:
- create the workshop’s slide deck
- rewrite the MASTER
- decide pedagogical content that the MASTER does not support
- redesign prompts/code without permission
- invent missing URLs, credentials, participant data, or technical facts

If the user requests a slide deck, use a separate slide publishing workflow/skill.

---

# Short invocation pattern

A user can say:

> Use Workshop Handbook Publisher on this MASTER. Treat it as frozen. Produce a learner-first self-contained HTML handbook. Remove trainer-only material, preserve prompts/code exactly, contextualize resources, and run the full QA checklist.

If the user provides a prior handbook as visual reference:

> Use the previous handbook only for visual style. The current MASTER is the content source of truth.

---

## 🔒 跨 Agent 執行防漂移鐵律 (Cross-Agent Anti-Drift Protocol)

> **⚡ 適用環境：Google Antigravity、OpenAI Codex CLI、Claude Code、Cursor 等全平台 Agent**

任何 AI Agent 在執行本技能時，**嚴禁依賴各平台大模型的默認輸出習慣自由發揮**，必須 100% 嚴格落實以下防漂移守則：

1. **零自作主張 (Zero Creative Deviation)**：
   - 嚴格沿用本規範定義之排版結構、區塊順序、欄位標籤與樣式。
   - **嚴禁私自「改寫/簡化」架構**（例如擅自將特定 Flex/Grid 佈局改寫為文字列表、將精確卡片改為空泛條列、或將樣式簡化）。
   - **嚴禁自創未經授權的新區塊**（例如擅自新增額外理論講義、發音表或未要求的長篇大論）。
2. **骨架代碼與格式優先 (Template Boilerplate Priority)**：
   - 若本規範提供具體代碼片段（HTML、CSS、JS、Markdown 骨架、卡片容器），必須作為不可變更之「填空基底 (Immutable Slots)」。
   - Agent 的任務僅是將內容精準填入對應的 Slots 容器中，**禁止改動外層容器 class 名稱、DOM 結構與事件綁定機制**。
3. **成品規格不降級 (No Spec Downgrade)**：
   - 嚴禁因 Token 長度限制或內容龐大，而將「圖文並茂互動網頁/雙軌講義」偷工減料降級為「純文字草稿」或「簡短大綱」。
   - 遇長文本時必須完整輸出全課內容或完整分段寫入目標檔案，**絕不省略後半段**。
4. **雙軌/多模態完整性 (Dual-Track Completeness)**：
   - 凡涉及「學生練習版」與「教師紅字解答版」之技能，必須兩套完整產出，答案與詳解必須扎實完整，嚴禁留白。
   - 凡涉及固定卡片數量（如 2 張文法卡片、5 大單字卡片、10 題挖空等），**嚴格維持指定數量，不多不少**。
5. **角色語氣與受眾鎖定 (Persona & Audience Alignment)**：
   - 嚴格維持臺灣高中職英語科專業教師立場，第二人稱「你」或「同學們」具同理心之對話語調，**嚴格杜絕第三人稱論文式說教腔**。

### 🏛️ 線上手冊發布規範鎖定 (Handbook Publisher Standards)
1. **單一自包含 HTML**：內嵌 CSS/JS，支援行動端與桌機響應式閱讀、代碼一鍵複製。
2. **敏感資訊去識別化**：移除講師限定內容與機密標籤，保留 100% 技術保真度。
