以 Weather Reporter 为单一线索重构演讲：Claude Code 五段式 Agentic 教学路径的叙事设计与落地

• 文档
• 教程
• AI 技能

这份学习旅程文档（reports/learning-journey-weather-reporter-redesign.md）记录了 claude-code-best-practice 仓库中演讲材料的一次重要重构方案：从第 7 张幻灯片起，用天气播报员（weather reporter）Agent这一贯穿始终的运行示例，把 Agents、Skills、Context、CLAUDE.md、Commands+Workflow 五大概念串联成一条完整叙事弧。读完本文，你将掌握一套可复用的技术演讲编排方法——如何用一个真实可运行的示例，把五个独立概念组织成"先认识这个人，再理解它会什么、怎么想、守什么规则、如何一键触发"的教学路径，并能对照仓库中已落地的天气系统源码（.claude/agents/、.claude/skills/、.claude/commands/、orchestration-workflow/）验证每一个环节的真实实现。

一、为什么需要一条贯穿始终的叙事弧

仓库的核心定位是"from vibe coding to agentic engineering"（见 README.md 与 CLAUDE.md），演讲需要在有限篇幅内讲清楚五组彼此关联但又各成体系的概念：Agents（专职角色）、Skills（技能）、Context（上下文/工作记忆）、CLAUDE.md（规则手册）、Commands+Workflow（触发与编排）。

旧版演讲的问题在于：每个主题单独成段，听众要反复切换心智模型。重构方案给出的解法是——让天气播报员先出场，再用它的"日常工作"去承载后续所有概念：

先与播报员见面（Agents）→ 理解它掌握什么技能（Skills）→ 理解它能同时记住多少东西（Context）→ 理解它上岗前要读的规则手册（CLAUDE.md）→ 最后看到一条命令如何把这一切串起来（Commands+Workflow）。

这条叙事弧与 TOC 的可见顺序（Agents → Skills → Context → CLAUDE.md → Commands）严格对齐，听众始终带着同一个心智模型，学习负担大幅降低。

二、章节重映射：从六段式到五段式

原文档给出了完整的"当前章节 → 新章节"映射表，这是重构的第一份蓝图：

重排后是否需要删减幻灯片，文档内部做过两次核算：第一次粗略算成 33 张（去掉 Workflow 分节页及 3 张内容页），随后逐段复核得出最终结论：保留全部 37 张，零删减。Workflow 分节页不再承担"第六个 Topic"的职责，而是通过去掉其data-level属性，降级为 Commands 章节内部的一个"章节视觉过渡页"。

需要说明的是：这份文档是重构的规划蓝图，其中 7-37 的页码是方案自洽的规格数字；仓库中当前实际的演讲 HTML（presentation/claude-code-best-practice/index.html）已经过后续迭代（例如现文件末尾的 workflow 幻灯片已位于data-slide="54"、data-slide="55"），因此在实施时应以规划语义为准、与实际 DOM 结构做核对，而不是照搬页码字面值。

三、LEVELS 映射与 journey bar 的取舍

演讲 UI 中有一条"学习旅程进度条"（journey bar），由每张幻灯片上的data-level驱动，等级键与进度百分比一一对应。重构中最大的 UI 决策是Workflow 等级去留：

• 第一版思路：彻底删除workflow键，进度条最高只到commands（83%）。
• 否决理由：结尾章节进度条只填到 83% 而非 100%，收尾观感不佳。
• 最终决策：commands（83%）与workflow（100%）两个键全部保留；Commands 分节页挂data-level="commands"，原 Workflow 分节页改挂data-level="workflow"，作为 Commands 章节内部的"高潮过渡页"。这样内容虽然重新排序，但 LEVELS 结构零改动，journey 刻度（ticks）也原样保留。

这一"等级键驱动进度条"的机制在仓库的姊妹演讲 presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html（第 2662-2670 行）中有直接实现佐证：LEVEL_LABELS对象恰好维护了agents、skills、context、claude-md、commands、workflow六个键，updateLevelBadge会在分节页的 h1 上动态追加等级徽标，showSlide则负责刷新进度条与计数。这份源码与文档中"6 个 level 键全部保留、无增删"的簿记结论完全吻合。

四、Slide-by-Slide 内容大纲：五大主题的逐页设计

4.1 前 6 页保持不变，仅更新 TOC 跳转目标

第 1-6 页（标题页、Boris GIF、Vibe→Agentic 过渡、What is Vibe Coding、好/坏 Prompt 对比、TOC）内容不动，但第 6 页 TOC 各行的goToSlide(n)目标必须随新顺序更新：

4.2 Section 1：Agents（slides 7-12）——"The Person"

• Slide 7（分节页，data-level="agents"，Topic 1）：标题 "Agents — The Weather Reporter"，副文案点题："An agent is Claude playing a specific role. Meet the weather reporter — a specialist hired to fetch and report weather data for Dubai."
• Slide 8 "The Restaurant Kitchen"：沿用"普通提示词 = 在陌生厨房里乱喊；Agent = 找到专门的厨师"的类比，把示例统一换成天气播报员，保留"普通提示 vs 天气 Agent"双栏对比卡片。
• Slide 9 "Prompting vs. Agent — Side by Side"：对比表格原样保留（天气示例本身已很贴切）。
• Slide 10 "Agents Get Their Own Brain"：保留 Thariq 的技巧，并把它锚定到天气播报员："the weather reporter works in their own brain — all that web fetching stays out of yours."（播报员在自己的大脑里完成所有抓取，不污染你的上下文。）
• Slide 11 "How to Create Your Own Agent"：保留/agents创建流程，代码块更新为真实的weather-agent.md路径。
• Slide 12 "Agent Config Fields"：保留字段表格，新增一个高亮框展示skills: [weather-fetcher]字段的实际用法。

仓库中的真实实现正是这段大纲的"成品"。.claude/agents/weather-agent.md 展示了该 Agent 的完整 frontmatter：allowedTools只放行Read与Skill（故意不给任何网络工具）、model: sonnet、color: green、maxTurns: 5、permissionMode: acceptEdits、memory: project，并通过skills: - weather-fetcher把技能预载入上下文。其正文用"Execution Contract（不可协商）"明确禁止 Agent 自行调用WebFetch/WebSearch/curl或把技能内容内联执行——这正是第 10 页"Agent 有独立大脑"在工程上的强制手段。各配置字段（name、description、tools、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation、color）的权威说明可参考 CLAUDE.md 的 "Subagent Definition Structure" 一节。

4.3 Section 2：Skills（slides 13-18）——"What the Reporter Knows"

• Slide 13（分节页，data-level="skills"，Topic 2）：标题 "Skills — What the Weather Reporter Knows"，副文案："Our reporter has two: fetch the data, and render it as a card."
• Slide 14 "The Training Manual"：把原来的 "Shayan" 示例替换为天气播报员的两项技能：weather-fetcher（去取温度）和weather-svg-creator（画视觉卡片）。
• Slide 15 "When to Turn Something Into a Skill"：保留 Boris 的技巧，并把这两个技能列为示例。
• Slide 16 "Why Separate Agents and Skills?"：强调 weather-agent = 这个人，weather-fetcher = 它的训练内容。
• Slide 17 "How to Create Your Own Skill"：代码块已展示真实的weather-fetcherSKILL.md 内容，原样保留。
• Slide 18 "Skill Config Fields"：新增注释——user-invocable: false设置在 weather-fetcher 上，因为它是仅供 Agent 内部使用的技能。

实现侧完全对得上。打开 .claude/skills/weather-fetcher/SKILL.md 可以看到：user-invocable: false（从/命令菜单中隐藏，只作为后台知识）、allowed-tools: WebFetch(*)，正文给出 Open-Meteo 的免 API Key 抓取指令与迪拜坐标（latitude 25.2048, longitude 55.2708），支持 Celsius/Fahrenheit 两种单位；而 .claude/skills/weather-svg-creator/SKILL.md 则是标准的独立技能——接收上下文中的温度与单位，按 reference.md 的模板写出 orchestration-workflow/weather.svg 和 orchestration-workflow/output.md。关于技能 frontmatter 的完整字段（name、description、argument-hint、disable-model-invocation、user-invocable、allowed-tools、model、context: fork、agent、hooks），同样可查阅 CLAUDE.md 的 "Skill Definition Structure" 一节。

4.4 Section 3：Context（slides 19-23）——"The Reporter's Brain"

• Slide 19（分节页，data-level="context"，Topic 3）：标题 "Context — The Reporter's Brain"，文案引导："Now that you've met the reporter and know their skills, let's understand what they can actually hold in mind at once."
• Slide 20 "Claude's Brain"：保留context-window.jpeg图示，新增一句与播报员的绑定："When the weather-agent is dispatched, it gets its own fresh brain — and weather-fetcher is pinned into it at startup."（Agent 被派出时获得全新的大脑，weather-fetcher 在启动时就被钉进这个大脑。）
• Slide 21 "What Loads at Session Start"：保留context.jpg，绑定播报员："At startup, Claude knowsaboutweather-fetcher (description only). When the command runs, the full skill content is loaded into the agent's brain."——这是渐进式披露（progressive disclosure）的直观表达：启动时只加载技能描述，命令真正运行时才把完整技能内容装入大脑。
• Slide 22 "Keep the Brain Clear"：保留分支点（branching point）决策表。
• Slide 23 "How to Manage Your Context"：保留/context、/compact、/clear三个管理命令的实操演示。

第 20-21 页引用的两张上下文示意图均存在于仓库中：presentation/assets/concepts/context/context-window.jpeg 与 presentation/assets/concepts/context/context.jpg，重构的资产清单明确标注它们"原样保留、仅随幻灯片重新编号"。

4.5 Section 4：CLAUDE.md（slides 24-29）——"The Pocket Rulebook"

• Slide 24（分节页，data-level="claude-md"，Topic 4）：标题 "CLAUDE.md — The Reporter's Pocket Rulebook"，文案："The reporter consults this at the start of every shift — even though their brain resets overnight."（大脑每天重置，但上岗前仍会翻阅这本口袋规则书。）
• Slide 25 "The Employee Handbook"：改用播报员框架——CLAUDE.md 是播报员开播前必读的规则书："always report in Celsius unless asked, always cite the source."
• Slide 26 "How to Create Your CLAUDE.md"：保留/init一键初始化流程。
• Slide 27 "Grow CLAUDE.md With Every Mistake"：保留 Boris 的建议（每次犯错都把它沉淀进 CLAUDE.md）。
• Slide 28 "What Goes in CLAUDE.md"：保留代码块，新增天气专属规则的注释示例。
• Slide 29 "How CLAUDE.md Loads"：原样保留。

仓库的实践依据充分：仓库根目录的 CLAUDE.md 本身就是这份规则书的一个活样例，其中明确写着"Keep CLAUDE.md under 200 lines per file for reliable adherence"（单文件控制在 200 行以内以保证可靠遵循）——这正是第 25-27 页想传达的工程经验：规则书要短、要随每次错误生长、要在会话开始时加载。此外 .claude/rules/markdown-docs.md 展示了带paths:frontmatter 的规则文件如何"惰性加载"（只在你触碰匹配文件时才载入），与 CLAUDE.md 的"每会话全量加载"形成对比，可作为第 29 页"CLAUDE.md 如何加载"的延伸讲解。

4.6 Section 5：Commands + Workflow（slides 30-36）——"The Trigger"

• Slide 30（分节页，data-level="commands"，Topic 5）：标题 "Commands — The Trigger"，文案精炼概括全链路："One word kicks off the whole chain./weather-orchestrator→ agent → skill → SVG card."
• Slide 31 "Commands — The Entry Point"：保留，已引用 weather-orchestrator。
• Slide 32 "How to Create Your Own Command"：保留，代码块已展示weather-orchestrator.md。
• Slide 33（Workflow 子章节，data-level="workflow"）：章节编号文字从 "Topic 6" 改为 "Putting It All Together"，标题改为 "Workflow — All Five Pieces Together"，文案："Watch the weather reporter example run from one keystroke to SVG card output." 保留data-level="workflow"使进度条填满至 100%。
• Slide 34 "Command → Agent → Skill"：保留代码块流程示意图（已完美贴合示例）。
• Slide 35 "Two Ways Skills Are Used"：保留双栏对比——预载技能（preloaded，作为 Agent 领域知识注入）vs 直接调用（direct invocation，命令通过 Skill 工具即时调用）。
• Slide 36 "How to Wire Your Own Workflow"：保留，本身即以天气工作流为例。
• Slide 37（结束页）：副标题改为 "Five concepts, one running example"，正文同步回指天气播报员叙事弧。

这段高潮在仓库中有完整的"可运行成品"。命令入口 .claude/commands/weather-orchestrator.md 定义了不可协商的执行契约：必须用AskUserQuestion先问用户要 Celsius 还是 Fahrenheit；必须通过 Agent 工具委托weather-agent（subagent_type: weather-agent，model: haiku）；只有拿到数字温度后才允许调用weather-svg-creator；任何一步失败都"fail-closed"（立即停止并向用户报告，绝不擅自 improvisation）。第 35 页讲的"两种技能用法"，在 orchestration-workflow/orchestration-workflow.md 里有系统级阐述：

• Agent Skill（预载）：weather-fetcher在 Agent 启动时以领域知识形式注入上下文，Agent 按其指令执行，不做动态调用；
• Skill（直接调用）：weather-svg-creator由命令通过Skill(skill: "weather-svg-creator")即时调用，在命令上下文里独立执行，直接消费上下文中已有的温度数据。

完整的调用链如下（引自 orchestration-workflow/orchestration-workflow.md 的流程示意图）：

一次真实执行的产物就落在 orchestration-workflow/output.md 中（当前示例输出为 89.3°F，含 SVG 卡片引用），而 orchestration-workflow/weather.svg 即最终视觉卡片。仓库内实际运行的录制 GIF（orchestration-workflow/orchestration-workflow.gif）也被当前演讲的 workflow 幻灯片（presentation/claude-code-best-practice/index.html 中data-slide="55"）用作"端到端运行演示"，与重构方案中"Workflow in action"的设计一脉相承。另外，weather-agent 还配置了memory: project，历史读数会持久化到 .claude/agent-memory/weather-agent/MEMORY.md 与readings.md，这为第 22 页"Keep the Brain Clear"与 Agent 记忆管理提供了真实样例。

五、资产复用清单

重构不需要新增素材，现有资产几乎全部复用：

两张上下文示意图的宿主幻灯片只是从 8/9 重新编号为 20/21，图片本身原地不动——这保证了视觉资产与叙事弧同步迁移时零损耗。

六、簿记影响：三张必须同步的"账本"

重构牵一发动全身，以下三处若不同步更新，跳转与进度显示就会错乱：

1. 新分节页位置与data-level分配

2. 第 6 页 TOC 的goToSlide目标（见 4.1 节表格：Agents 18→7、Skills 24→13、Context 7→19、CLAUDE.md 12→25、Commands 30→30）

3. journey 刻度与 LEVELS 映射——均无需改动：journey tick 轨道自上而下本来的顺序是 Workflow、Commands、Skills、Agents、CLAUDE.md、Context，恰好是叙事弧的倒序（顶部 = 最高层级 = 最后达成），因此不需要动；LEVELS 的 6 个键（context、claude-md、agents、skills、commands、workflow）也一个不增、一个不减。

七、实现路线：单文件 HTML 的七步手术

演讲是一个单一大 HTML 文件（presentation/claude-code-best-practice/index.html），而现有幻灯片顺序与新叙事弧不符，最干净的实现方式是七步顺序执行：

1. 剪切粘贴重排：把各 slide div 按新顺序拼接（7-12 = 原 18-23，13-18 = 原 24-29，19-23 = 原 7-11，24-29 = 原 12-17，30-37 不变）；
2. 顺序重编号：所有data-slide属性按 1、2、3… 依次重排；
3. 更新分节页data-level：按第 6.1 节的分配表逐页校正；
4. 更新分节文案：分节页的章节编号文本与 h1 标题同步替换；
5. 更新 TOC 跳转：第 6 页各行的goToSlide目标按新页码改写；
6. 更新 Workflow 过渡页：原第 33 页的章节编号文本从 "Topic 6" 改为 "Putting It All Together"；
7. 定向内容编辑：按各小节大纲，把需要天气播报员框架化的文案逐处替换。

总页数保持37不变。对照当前 HTML 中goToSlide函数（presentation/claude-code-best-practice/index.html第 2743 行）与data-slide/data-level的既有使用模式，这套手术步骤与现有代码结构完全兼容。

八、歧义与决策记录

文档在收尾处明确给出结论："All ambiguities have been resolved above."——所有悬而未决的问题（Workflow 等级去留、分节页是否降级、页数是否精简、LEVELS 是否改动）都在前文逐项拍板：

• 页数：不删任何幻灯片，37 张全保留；
• Workflow 分节页：保留但摘掉"第六个 Topic"身份，降级为 Commands 章节内的视觉过渡页；
• LEVELS：6 键全保留，workflow（100%）通过挂在过渡页上来兑现进度条满格；
• 实施：按七步法直接推进，无需进一步澄清。

九、这套方法论的复用价值

抛开天气示例本身，这份重构方案示范了一个可迁移到任何技术演讲的编排原则：用一个贯穿始终的、真实可运行的示例，作为所有抽象概念的"锚点"。仓库的做法尤其值得借鉴——它不是虚构一个 demo，而是把示例真正做成了可执行的工程系统（Agent、两个 Skill、一条 Command、一份编排文档、真实输出产物），让演讲的每一页都能指回仓库里的真实文件。当你下次需要讲 Agents/Skills/Context/CLAUDE.md/Commands 这类相互关联的概念时，可以照搬这条路径：先让角色出场 → 再讲它的能力 → 它的记忆 → 它的规则 → 最后用一条命令把全部串起来，并用"story 弧顺序 = TOC 顺序"的约束来校验每张幻灯片的落位，用data-level这类 UI 账本保证跳转与进度展示永远自洽。

• 文档
• 教程
• AI 技能