XiaoZhen-Y Skill Explainer
使用本技能解释另一个 Codex 技能，并生成中文自然语言 explanation.md 文档。本技能不再直接输出 HTML 页面；它负责产出结构化 Markdown 内容，随后可由 $web-design-engineer 根据这份 Markdown 生成最终网页。
协作关系
skill-explainer 与 $web-design-engineer 的职责分工如下：
skill-explainer- 输入：一个 Codex 技能目录。
- 功能：解释目标技能的功能、目录结构、脚本能力和网页呈现要求。
- 输出：自然语言 Markdown 文档，默认文件名为
explanation.md。
$web-design-engineer- 输入：由
skill-explainer生成的 Markdown 文档，以及其中的网页设计要求。 - 功能：根据文档内容和页面要求设计并实现网页。
- 输出：HTML 网页。
- 输入：由
快速开始
运行随附生成器，并传入目标技能路径：
python /path/to/skill-explainer/generate.py /path/to/target-skill
默认输出位置：
/path/to/target-skill/explanation.md
指定其他输出位置：
python /path/to/skill-explainer/generate.py /path/to/target-skill --output /path/to/explanation.md
输入与输出
- 输入：一个 Codex 技能目录路径。
- 输出：一个以中文为主的自然语言 Markdown 文件；未指定
--output时命名为explanation.md。 - 文档内容必须包括：
- 目标技能的功能概述。
- 目标技能的目录结构。
- 每个顶级目录和文件的作用说明。
- 主要脚本及其功能摘要。
- 交给
$web-design-engineer的网页设计要求。
Markdown 内容规则
生成结果应保持自然语言文档形态，而不是 HTML 或页面代码。文档应清晰、可读、便于直接交给另一个技能继续处理。
必须保留以下章节结构：
- 技能功能概述
- 目录结构
- 目录与文件作用
- 主要脚本功能
- 给 web-design-engineer 的网页设计要求
- 推荐后续流程
网页设计要求规则
skill-explainer 生成的 Markdown 中必须包含给 $web-design-engineer 的固定网页设计要求。当前固定要求为：
- 页面主语言为中文。
- 视觉风格固定为星空 / 深空档案风格。
- 最终 HTML 页面必须有动效，例如星点漂移、轨道线呼吸、卡片进入动效或悬停反馈。
- 必须支持
prefers-reduced-motion。 - 页面要展示技能功能、目录结构、脚本功能和使用方式，不得只做视觉装饰。
- 移动端不能横向溢出。
- 不得编造目标技能不存在的能力。
中文优先规则
固定文案、章节标题、说明性文字和自动生成摘要都应以中文为主。若目标技能自身的元数据、注释或文档为英文，可以保留原文信息，但必须放在中文语境中呈现，例如“该技能的原始描述为：……”，避免整块文档主文案变成英文。
生图规则
本技能默认不创建图片，也不直接生成网页视觉资产。若后续网页设计需要生成式位图图片，必须在 $web-design-engineer 阶段通过 Codex 的 image2.0 生图能力生成图片资产。不得在 Markdown 中假装已经完成生图。
生成器行为
generate.py 会执行以下步骤：
- 解析并校验目标技能路径。
- 读取
SKILL.md、.codex或*.codex元数据，提取技能名称和描述。 - 遍历技能目录，并跳过常见依赖、缓存和生成文件。
- 用确定性规则为每个顶级目录和文件生成中文说明。
- 读取
.py、.js、.ts、.sh、.ps1、.rb、.go、.rs等脚本类文件，并根据文档字符串、注释、导入、函数和文件名生成简明中文摘要。 - 生成文本目录树。
- 将收集结果写入自然语言 Markdown 文档。
使用注意
- 优先传入绝对路径。
- 生成器会跳过
.git、node_modules、.venv、__pycache__、dist、build、explanation.html、explanation.md等常见无关内容。 - 如果目标技能缺少元数据，生成器会回退到目录名和中文兜底说明。
- 如果用户要求“继续生成网页”，将
explanation.md的完整内容交给$web-design-engineer，由它负责输出 HTML。