skills-docs

技能文档系统

人类可读的网页文档与 LLM Agent 使用内容的唯一事实来源。

架构

skills/skills/{skill-name}/
  SKILL.md                    # Overview + quick start (LLM entry point)
  references/
    {name}.md                 # Reference, tutorial, how-to, or explanation

一个来源对应两个构建目标：

• 网页文档：Telecine 直接读取 skills/skills/，使用 MDX 渲染，并根据约定映射组件
• LLM 技能：generate-skills.ts 会移除仅供人类阅读的元数据，将 API 元数据转换为说明文字，并输出到 skills/skills-generated/（Git 忽略的构建产物）

编写工作流

1. 编辑 skills/skills/ 中的源文件
2. 预览网页——Telecine 直接读取源文件，无需构建
3. 生成 LLM 文件：npx tsx scripts/generate-skills.ts
4. 推送到技能远程仓库：./scripts/push-skills [--branch name]

只有在发布到 LLM 可使用的仓库时才需要执行步骤 3–4。开发期间，网页预览会立即验证更改。

切勿编辑 skills/skills-generated/——每次构建都会覆盖其中的内容。

Frontmatter 速查

SKILL.md 文件

字段	必需	生成后保留
name	是	是
description	是	是
license	否	是
metadata（author、version）	否	是

参考文件

字段	必需	生成后保留	用途
title	是	是（作为 name）	显示名称
description	是	是	简要说明
type	是	否	reference | tutorial | how-to | explanation
nav	否	否	树形侧边栏：parent、priority、related
topic	否	否	按主题分组的侧边栏类别
order	否	否	主题分组内的排序顺序
track	否	否	学习路径标识符
track_step	否	否	在学习路径中的位置
track_title	否	否	学习路径导航的显示标题
prerequisites	否	否	必读参考资料
next_steps	否	否	建议阅读的后续参考资料
api	否	转换为说明文字	结构化 API 元数据
sections	否	否	拆分为多个网页

完整字段说明请参阅 frontmatter.md。

关键限制

YAML 解析器限制

生成脚本使用了一个手写 YAML 解析器（scripts/generate-skills.ts），仅支持：

• 顶层标量字段（key: value）
• 一层对象嵌套（key:\n subkey: value）
• 4 个空格缩进的对象数组（ - name: value）
• 数组项内 6 个或更多空格缩进的对象属性

不支持（会静默地产生错误输出）：

• 多行字符串（| 或 > 块标量）
• 内联流式序列（[a, b, c]）
• YAML 注释
• 超过 3 层的嵌套
• 带引号的键

更改 frontmatter 后，务必在本地测试生成：

npx tsx scripts/generate-skills.ts
# Inspect skills/skills-generated/ to verify output

sections 与标题的关联

sections frontmatter 通过 heading 字段引用 Markdown 的 H2 标题。两者必须完全匹配。如果重命名 H2 标题，请更新对应的 sections[].heading。

sections:
  - slug: tutorial
    heading: Video Tutorial    # Must match "## Video Tutorial" in body

导航父级路径

nav.parent 使用以 / 分隔的路径（斜线两侧带空格）来构建侧边栏树：

nav:
  parent: "Elements / Media"   # Creates: Elements > Media > this page

父级路径拼写错误会导致节点被静默地孤立。创建新路径前，请先检查现有参考资料中使用的路径。

渲染约定

Web 渲染器会检测 Markdown 模式，并将其升级为交互式组件。有关编写详情，请参阅 conventions.md。

模式	Web 渲染效果	LLM 输出
```html live	交互式预览 + 胶片条	纯代码块
```mermaid	渲染后的 Mermaid 图表	纯代码块
> **Note:** ...	蓝色提示框	标准引用块
> **Warning:** ...	金色提示框	标准引用块
属性/类型/描述表格	增强型 PropertyDoc 样式	标准表格
教程中的 ### Step N:	步骤指示器样式	标准标题
[references/X.md](references/X.md)	React Router 链接	相对链接
api frontmatter	H1 后的卡片式 ApiReference	H1 后的散文列表

生成转换

generate-skills.ts 对每个源文件的处理方式：

• title → 在输出 frontmatter 中变为 name
• description、license、metadata → 保留
• nav、track、track_*、prerequisites、next_steps、type、topic、order、sections → 移除
• api → 转换为散文并注入 H1 后：

## Attributes
- **src** (string) (required) - URL or path to video source
- **volume** (number, default: 1.0) - Audio volume

## Properties
- **sourceIn** (string) - Absolute start time

## Methods
- **play()** - Start playback
  - Returns: void

## Functions
- **createRender(client, payload)** - Create a new render job
  - Returns: CreateRenderResult

Markdown 正文保持不变。

API 元数据类型

api frontmatter 支持四种子键，分别对应不同的 API 表面类型：

• attributes：HTML 元素属性（例如，<ef-video src="...">）

  • 适用于：自定义元素、Web 组件
  • 字段：name、type、required、default、description、values

• properties：React 组件属性（例如，<Preview className="...">）

  • 适用于：React 组件、TypeScript 接口
  • 字段：name、type、required、default、description、values

• methods：对象或元素的实例方法（例如，element.play()）

  • 适用于：实例上存在的方法、DOM API
  • 字段：name、signature、description、returns

• functions：独立导出的函数（例如，createRender(client, payload)）

  • 适用于：SDK 函数、实用函数、顶层导出
  • 字段：name、signature、description、returns

这四种类型在 Web 上都会渲染为卡片网格，并转换为缩进的散文列表，供 LLM 使用。

关键文件位置

技能内容

• skills/skills/ — 源文件（编辑这些文件）
• skills/skills-generated/ — 构建产物（切勿编辑，已被 gitignore 忽略）
• skills/BUILD.md — 构建流程文档

构建流水线

• scripts/generate-skills.ts — 生成脚本
• scripts/push-skills — 生成并推送到 skills 远程仓库

Web 渲染器（telecine）

• telecine/services/web/app/utils/skills.server.ts — 加载、构建导航、提取章节
• telecine/services/web/app/utils/skills-mdx-components.tsx — 基于约定的 MDX 组件
• telecine/services/web/app/routes/skills/reference-detail.tsx — 参考页面
• telecine/services/web/app/routes/skills/skill-detail.tsx — 技能概览页面 + 侧边栏树
• telecine/services/web/app/components/skills/ApiReference.tsx — API 参考卡片
• telecine/services/web/app/components/skills/OnThisPage.tsx — 根据 H2/H3 自动生成的目录

旧版文档（内容迁移来源）

• telecine/services/web/app/content/docs/ — 用于提取内容的 MDX 文件
• telecine/services/web/app/components/docs/ — 旧版组件（Demonstration、PropertyDoc）

修改渲染器时

基于约定的渲染逻辑位于 skills-mdx-components.tsx 中：

• SkillsPreBlock — 通过 data-meta 属性检测 html live（由 remarkCodeMeta 插件设置）
• LiveDemo — 使用 @editframe/react 中的 Preview/FitScale/FocusOverlay/Filmstrip 渲染原始 HTML
• SkillsTable — 检测 Attribute/Type/Description 列标题，以应用增强样式
• SkillsBlockquote — 检测 Note/Warning 前缀，以应用提示框样式
• getSkillsMDXComponents(skillName, api?) — 返回完整的组件映射；提供 api 时，会包装 H1 以注入 ApiReference

skill-detail.tsx 和 reference-detail.tsx 都使用共享的组件映射。

导航在 skills.server.ts 中构建：

• getSkillNavTree() — 根据 nav.parent 路径构建树
• getSkillNav() — 根据 topic 字段构建主题分组
• 类型排序：tutorial → how-to → explanation → reference

内容指南

长度目标

类型	目标	重点
reference	60-100 行	属性、基本用法、常见模式
tutorial	约 90 行	使用 html live 演示逐步讲解，简介尽量简短
how-to	20-40 行	单一任务，只写操作，不写理由
explanation	60-80 行	深入讲解概念，不含代码/配置

写作原则

每篇文档只采用一种模式。 每个文件都应符合一种 type。如果内容属于另一种模式，应链接到对应文档，而不是直接纳入。教程不讲解架构。参考文档不包含理由。操作指南不讲授概念。

不要在多个文件中重复内容。 如果某个概念已在一篇参考文档中讲解，应从其他文档链接到它。如果同一文档中有两句话含义相同，请删去其中一句。

使用中立、技术性的语言。 描述平台限制和结果，而非规定性命令或比较性批评：

• “原生播放需要下载完整文件”，而非“必须下载整个文件”
• “直接播放文件存在以下限制”，而非“传统工作流速度很慢”
• 为绝对表述添加限定：“通常在几秒内”，而非“立即”

着重说明效果，而非实现方式。 解释用户会看到什么，而不是内部机制。“播放器具有响应性，并会逐步加载”，而非“后端会对文件进行分段”。

展示胜于描述。 使用 html live 代码块进行演示。教程的每个步骤和操作指南中的每个解决方案都应配有可运行的演示。参考文档应展示基本用法，而不只是列出属性。

使用真实素材。 演示素材请使用 https://assets.editframe.com/ 中的 URL（例如 bars-n-tone.mp4）。