# Skill Explainer

> 为任意 Codex 技能目录生成中文自然语言 Markdown 说明文档。适用于需要解释另一个技能的功能、目录结构、脚本能力，并整理可交给 web-design-engineer 继续生成网页的设计要求时。

- Skill: `xiaozhen-y/skill-explainer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xiaozhen-y/skill-explainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaozhen-y/skill-explainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: XiaoZhen-Y (https://skillmd.com/u/xiaozhen-y)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xiaozhen-y/skill-explainer

---


# 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 网页。

## 快速开始

运行随附生成器，并传入目标技能路径：

```bash
python /path/to/skill-explainer/generate.py /path/to/target-skill
```

默认输出位置：

```text
/path/to/target-skill/explanation.md
```

指定其他输出位置：

```bash
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 或页面代码。文档应清晰、可读、便于直接交给另一个技能继续处理。

必须保留以下章节结构：

1. 技能功能概述
2. 目录结构
3. 目录与文件作用
4. 主要脚本功能
5. 给 web-design-engineer 的网页设计要求
6. 推荐后续流程

## 网页设计要求规则

`skill-explainer` 生成的 Markdown 中必须包含给 `$web-design-engineer` 的固定网页设计要求。当前固定要求为：

- 页面主语言为中文。
- 视觉风格固定为星空 / 深空档案风格。
- 最终 HTML 页面必须有动效，例如星点漂移、轨道线呼吸、卡片进入动效或悬停反馈。
- 必须支持 `prefers-reduced-motion`。
- 页面要展示技能功能、目录结构、脚本功能和使用方式，不得只做视觉装饰。
- 移动端不能横向溢出。
- 不得编造目标技能不存在的能力。

## 中文优先规则

固定文案、章节标题、说明性文字和自动生成摘要都应以中文为主。若目标技能自身的元数据、注释或文档为英文，可以保留原文信息，但必须放在中文语境中呈现，例如“该技能的原始描述为：……”，避免整块文档主文案变成英文。

## 生图规则

本技能默认不创建图片，也不直接生成网页视觉资产。若后续网页设计需要生成式位图图片，必须在 `$web-design-engineer` 阶段通过 Codex 的 image2.0 生图能力生成图片资产。不得在 Markdown 中假装已经完成生图。

## 生成器行为

`generate.py` 会执行以下步骤：

1. 解析并校验目标技能路径。
2. 读取 `SKILL.md`、`.codex` 或 `*.codex` 元数据，提取技能名称和描述。
3. 遍历技能目录，并跳过常见依赖、缓存和生成文件。
4. 用确定性规则为每个顶级目录和文件生成中文说明。
5. 读取 `.py`、`.js`、`.ts`、`.sh`、`.ps1`、`.rb`、`.go`、`.rs` 等脚本类文件，并根据文档字符串、注释、导入、函数和文件名生成简明中文摘要。
6. 生成文本目录树。
7. 将收集结果写入自然语言 Markdown 文档。

## 使用注意

- 优先传入绝对路径。
- 生成器会跳过 `.git`、`node_modules`、`.venv`、`__pycache__`、`dist`、`build`、`explanation.html`、`explanation.md` 等常见无关内容。
- 如果目标技能缺少元数据，生成器会回退到目录名和中文兜底说明。
- 如果用户要求“继续生成网页”，将 `explanation.md` 的完整内容交给 `$web-design-engineer`，由它负责输出 HTML。