Create FlowGram Component Docs — 字节跳动 FlowGram 物料组件文档工作流 Skill 技能

技能简介

Create FlowGram Component Docs 是字节跳动官方维护的物料组件文档全流程助手，专门解决「FlowGram 组件从源代码到 MDX 文档、从中文稿到英文稿」链路上的规范与一致性问题。它给 Claude / Codex / Claude Code 提供一套标准化作业流：先勘察源文件，再按 React.lazy + FreeFormMetaStoryBuilder 规范产出 Story 示例，再生成包含 demo / API 表 / 源码走读 / 依赖说明的 MDX，最后支持中英双语对照。Skill 由 bytedance 官方账号发布，质量分 81 分（银级），审计状态 complete，ISSUES 0、REQ 0，安装策略 allowed。

核心能力

1. 源文件勘察：定位 FlowGram 物料组件的源文件、相关导出、hooks、依赖项，避免凭空写文档。
2. Story 规范生成：按项目要求用 React.lazy + FreeFormMetaStoryBuilder 包装器生成 Story 组件，保证懒加载与项目框架一致。
3. MDX 文档骨架：生成包含 demo、API 参考表、源码走读、依赖说明的 MDX 页面，并配截图命名与存储路径规范。
4. 截图嵌入规范：统一截图命名、存储路径、引用语法，避免文档站点路径错乱。
5. 中英双语对照：基于已通过审定的中文稿生成英文版，保留代码块、命令、路径、链接不翻译，杜绝「代码被机翻」事故。
6. 清单式审稿：提供 checklist，覆盖 Story 行为 / 示例 / 链接 / Mermaid 图 / 术语一致性。

安装配置

1. 命令行安装：npx skillstore add bytedance/material-component-doc，需 npx 与 Node.js 18+。
2. 仓库准备：把本 Skill 安装到 FlowGram 仓库的 .claude/skills/material-component-doc 路径，确保能访问组件源目录。
3. 截图目录约定：在文档站点预先约定截图目录结构（如 apps/docs/public/screens/material/），避免命名漂移。
4. 双语流程开关：仅当中文稿已经过 PM / 研发审定后，才能启用英文翻译流程。

使用步骤

1. 启动文档任务：使用 Start a component document 模板，告诉 Claude 要文档化的 FlowGram 组件名，先勘察源文件并询问示例范围。
2. 生成 Story 示例：用 Create Story examples 模板产出 BasicStory 与至少一个进阶场景，严格遵守 React.lazy 与 FreeFormMetaStoryBuilder 包装规范。
3. 撰写 MDX 草稿：按 demo → API 表 → 源码走读 → 依赖 → 截图占位的顺序填充，禁止直接 import 物料组件而跳过 React.lazy。
4. 清单式审稿：使用 Review an MDX draft 模板逐项核对 demo、API、源码走读、依赖、截图、链接格式，补齐缺项。
5. 双语对照翻译：中文稿通过审定后，使用 Translate approved documentation 模板，保留所有代码块、命令、路径、外部链接原样。

适用场景

• 新组件文档化：把 FlowGram 组件源目录一次性产出完整 MDX 页面，覆盖 demo、API、源码、依赖四个层次。
• Story 示例标准化：规范团队内 Story 命名、懒加载、包装器、类型注解写法，避免十个组件十种风格。
• 中英双语发布：把已审定的中文组件文档翻译成英文版，对外站 / 海外开发者发布。
• 审稿 checklist：大型组件上线前用本 Skill 做最后一道审稿，降低「文档不全 / 链接断 / 截图缺失」导致的用户投诉。

适用人群

• FlowGram 组件作者：写组件时同步产文档，避免「文档欠债」累积到发布前才补。
• 前端文档维护者：负责文档站点日常更新，把 Story 与 MDX 工作流标准化。
• 国际化负责人：在双语文档流程上需要明确的「中文先审 → 英文后译」交接点。
• 组件库 Tech Lead：把组件发布流程固化为 checklist，提升团队整体质量水位。

工作原理

Skill 把「组件文档化」拆成 5 个可校验阶段，每阶段对应一个 prompt 模板与一段 checklist。源文件勘察阶段通过 Claude 的 file tools 读取仓库真实结构，Story 生成阶段强制套用项目级 React.lazy 包装，MDX 阶段输出符合 docs site 渲染规范的字段，翻译阶段严格区分内容文本与代码 / 命令 / 路径并按规则保留。审计报告确认所有静态告警均为 Markdown / 代码 fence / Mermaid 图导致的误报，不存在 prompt 注入、数据外泄、隐式执行钩子或恶意文件系统行为。

官方链接

• Skillstore 页面：https://skillstore.io/skills/bytedance-material-component-doc
• 源码仓库：https://github.com/bytedance/flowgram.ai/tree/main/.claude/skills/material-component-doc
• Manifest：https://skillstore.io/api/skills/bytedance-material-component-doc/manifest
• 安装命令：npx skillstore add bytedance/material-component-doc