skills-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Documentation System

技能文档系统

Single source of truth for both human-readable web docs and LLM agent consumption.

供人类可读网页文档和LLM Agent使用的单一可信数据源。

Architecture

架构

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

Two build targets from one source:

Web docs: Telecine reads
```
skills/skills/
```
directly, renders with MDX + convention-based component mapping
LLM skills:
```
generate-skills.ts
```
strips human-only metadata, converts API metadata to prose, outputs to
```
skills/skills-generated/
```
(gitignored build artifact)

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 metadata转换为散文式文本，输出到
```
skills/skills-generated/
```
目录（该目录为Git忽略的构建产物）

Authoring Workflow

编写工作流

Edit source files in
```
skills/skills/
```
Preview on web — telecine reads source directly, no build step needed
Generate LLM files:
```
npx tsx scripts/generate-skills.ts
```
Push to skills remote:
```
./scripts/push-skills [--branch name]
```

Steps 3-4 only needed when publishing to the LLM-consumable repository. During development, web preview validates changes immediately.

Never edit
skills/skills-generated/
— overwritten on every build.

编辑
```
skills/skills/
```
目录下的源文件
网页预览 — Telecine直接读取源文件，无需构建步骤
生成LLM文件：
```
npx tsx scripts/generate-skills.ts
```
推送至技能远程仓库：
```
./scripts/push-skills [--branch name]
```

仅在发布至LLM可消费的仓库时需要执行步骤3-4。开发期间，网页预览可即时验证更改。

请勿编辑
skills/skills-generated/
目录 — 每次构建都会覆盖该目录内容。

Frontmatter Quick Reference

Frontmatter快速参考

SKILL.md files

SKILL.md 文件

Field	Required	Survives generation
`name`	yes	yes
`description`	yes	yes
`license`	no	yes
`metadata` ( `author` , `version` )	no	yes

字段	必填	保留至生成产物
`name`	是	是
`description`	是	是
`license`	否	是
`metadata` （ `author` 、 `version` ）	否	是

Reference files

参考文件

Field	Required	Survives generation	Purpose
`title`	yes	yes (as `name` )	Display name
`description`	yes	yes	Brief description
`type`	yes	no	`reference` \| `tutorial` \| `how-to` \| `explanation`
`nav`	no	no	Tree sidebar: `parent` , `priority` , `related`
`topic`	no	no	Topic-grouped sidebar category
`order`	no	no	Sort order within topic group
`track`	no	no	Learning path identifier
`track_step`	no	no	Position in learning path
`track_title`	no	no	Display title for track nav
`prerequisites`	no	no	Required reading references
`next_steps`	no	no	Suggested next references
`api`	no	converted to prose	Structured API metadata
`sections`	no	no	Split into multiple web pages

For complete field documentation, see frontmatter.md.

字段	必填	保留至生成产物	用途
`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。

Critical Constraints

关键限制

YAML Parser Limitations

YAML解析器限制

The generation script uses a hand-rolled YAML parser (

scripts/generate-skills.ts

) that supports only:

Top-level scalar fields (
```
key: value
```
)
One level of object nesting (
```
key:\n  subkey: value
```
)
Arrays of objects at 4-space indent (
```
    - name: value
```
)
Object properties at 6+ space indent within array items

Not supported (silently produces wrong output):

Multi-line strings (
```
|
```
or
```
>
```
block scalars)
Flow sequences inline (
```
[a, b, c]
```
)
YAML comments
Nesting deeper than 3 levels
Quoted keys

Always test generation locally after frontmatter changes:

bash

npx tsx scripts/generate-skills.ts

生成脚本使用自定义YAML解析器（

scripts/generate-skills.ts

），仅支持：

顶级标量字段（
```
key: value
```
）
一级对象嵌套（
```
key:\n  subkey: value
```
）
4空格缩进的对象数组（
```
    - name: value
```
）
数组项内6+空格缩进的对象属性

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

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

修改frontmatter后务必在本地测试生成结果：

bash

npx tsx scripts/generate-skills.ts

Inspect skills/skills-generated/ to verify output

检查skills/skills-generated/目录以验证输出

undefined

undefined

Sections-Heading Coupling

章节与标题的耦合

The

sections

frontmatter references markdown H2 headings via the

heading

field. The match must be exact. If you rename an H2, update the corresponding

sections[].heading

yaml

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

sections

frontmatter通过

heading

字段关联Markdown H2标题，匹配必须完全一致。如果重命名H2标题，请更新对应的

sections[].heading

。

yaml

sections:
  - slug: tutorial
    heading: Video Tutorial    # 必须与正文中的"## Video Tutorial"匹配

Nav Parent Paths

导航父路径

nav.parent

uses

-delimited paths (with spaces around slash) to build the sidebar tree:

yaml

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

Misspelling a parent path creates a silently orphaned node. Check existing references for established paths before inventing new ones.

nav.parent

使用

分隔的路径（斜杠两侧带空格）来构建侧边栏树：

yaml

nav:
  parent: "Elements / Media"   # 生成：Elements > Media > 当前页面

父路径拼写错误会导致节点被静默孤立。创建新路径前，请先检查现有参考内容中的已确立路径。

Rendering Conventions

渲染约定

The web renderer detects markdown patterns and upgrades them to interactive components. See conventions.md for authoring details.

Pattern	Web rendering	LLM output
```html live	Interactive preview + filmstrip	Plain code block
```mermaid	Rendered Mermaid diagram	Plain code block
`> Note: ...`	Blue callout box	Standard blockquote
`> Warning: ...`	Gold callout box	Standard blockquote
Attribute/Type/Description table	Enhanced PropertyDoc styling	Standard table
`### Step N:` in tutorials	Step-indicator styling	Standard heading
`[references/X.md](references/X.md)`	React Router link	Relative link
`api` frontmatter	Card-based ApiReference after H1	Prose list after H1

网页渲染器会检测Markdown模式并将其升级为交互式组件。编写细节请查看conventions.md。

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

Generation Transform

生成转换

What

generate-skills.ts

does to each source file:

```
title
```
→ becomes
```
name
```
in output frontmatter
```
description
```
,
```
license
```
,
```
metadata
```
→ preserved

nav

track

track_*

prerequisites

next_steps

type

topic

order

sections

→ stripped

```
api
```
→ converted to prose and injected after H1:

markdown

undefined

generate-skills.ts

对每个源文件执行以下操作：

```
title
```
→ 变为输出frontmatter中的
```
name
```
```
description
```
、
```
license
```
、
```
metadata
```
→ 保留

nav

、

track

、

track_*

、

prerequisites

、

next_steps

、

type

、

topic

、

order

、

sections

→ 剥离

```
api
```
→ 转换为散文式文本并注入到H1标题之后：

markdown

undefined

Attributes

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

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

Properties

sourceIn (string) - Absolute start time

sourceIn (string) - Absolute start time

Methods

play() - Start playback
- Returns: void

play() - Start playback
- Returns: void

Functions

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


Markdown body is preserved unchanged.

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


Markdown正文内容保持不变。

API Metadata Types

API元数据类型

The

api

frontmatter supports four sub-keys for different API surface types:

attributes
: HTML element attributes (e.g.,
```
<ef-video src="...">
```
)
- Use for: Custom elements, web components
- Fields:
```
name
```
  ,
```
type
```
  ,
```
required
```
  ,
```
default
```
  ,
```
description
```
  ,
```
values
```
properties
: React component props (e.g.,
```
<Preview className="...">
```
)
- Use for: React components, TypeScript interfaces
- Fields:
```
name
```
  ,
```
type
```
  ,
```
required
```
  ,
```
default
```
  ,
```
description
```
  ,
```
values
```
methods
: Instance methods on objects or elements (e.g.,
```
element.play()
```
)
- Use for: Methods that exist on instances, DOM APIs
- Fields:
```
name
```
  ,
```
signature
```
  ,
```
description
```
  ,
```
returns
```
functions
: Standalone exported functions (e.g.,
```
createRender(client, payload)
```
)
- Use for: SDK functions, utility functions, top-level exports
- Fields:
```
name
```
  ,
```
signature
```
  ,
```
description
```
  ,
```
returns
```

All four types render as card grids on the web and convert to indented prose lists for LLM consumption.

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
```

这四种类型在网页端会渲染为卡片网格，在LLM消费时会转换为缩进的散文式列表。

Key File Locations

关键文件位置

Skills content

技能内容

```
skills/skills/
```
— source files (edit these)
```
skills/skills-generated/
```
— build artifacts (never edit, gitignored)
```
skills/BUILD.md
```
— build process documentation

```
skills/skills/
```
— 源文件（编辑此目录下的内容）
```
skills/skills-generated/
```
— 构建产物（请勿编辑，已加入Git忽略）
```
skills/BUILD.md
```
— 构建流程文档

Build pipeline

构建流水线

```
scripts/generate-skills.ts
```
— generation script
```
scripts/push-skills
```
— generate + push to skills remote

```
scripts/generate-skills.ts
```
— 生成脚本
```
scripts/push-skills
```
— 生成并推送至技能远程仓库

Web renderer (telecine)

网页渲染器（telecine）

telecine/services/web/app/utils/skills.server.ts

— loading, nav building, section extraction

telecine/services/web/app/utils/skills-mdx-components.tsx

— convention-based MDX components

telecine/services/web/app/routes/skills/reference-detail.tsx

— reference page

telecine/services/web/app/routes/skills/skill-detail.tsx

— skill overview page + sidebar tree

telecine/services/web/app/components/skills/ApiReference.tsx

— API reference cards

telecine/services/web/app/components/skills/OnThisPage.tsx

— auto-generated TOC from H2/H3

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自动生成目录

Legacy docs (content migration source)

旧版文档（内容迁移源）

```
telecine/services/web/app/content/docs/
```
— MDX files to draw content from
```
telecine/services/web/app/components/docs/
```
— legacy components (Demonstration, PropertyDoc)

```
telecine/services/web/app/content/docs/
```
— 待迁移的MDX文件
```
telecine/services/web/app/components/docs/
```
— 旧版组件（Demonstration、PropertyDoc）

When Modifying the Renderer

修改渲染器时的注意事项

The convention-based rendering lives in

skills-mdx-components.tsx

SkillsPreBlock

— detects

html live

via

data-meta

attribute (set by

remarkCodeMeta

plugin)

```
LiveDemo
```
— renders raw HTML inside Preview/FitScale/FocusOverlay/Filmstrip from
```
@editframe/react
```
```
SkillsTable
```
— detects Attribute/Type/Description column headers for enhanced styling
```
SkillsBlockquote
```
— detects Note/Warning prefixes for callout boxes
```
getSkillsMDXComponents(skillName, api?)
```
— returns the full component mapping; when
```
api
```
is provided, wraps H1 to inject ApiReference

Both

skill-detail.tsx

and

reference-detail.tsx

use the shared component mapping.

Navigation is built in

skills.server.ts

```
getSkillNavTree()
```
— builds tree from
```
nav.parent
```
paths
```
getSkillNav()
```
— builds topic groups from
```
topic
```
field
Type ordering: tutorial → how-to → explanation → reference

基于约定的渲染逻辑位于

skills-mdx-components.tsx

中：

SkillsPreBlock

— 通过

data-meta

属性检测

html live

（由

remarkCodeMeta

插件设置）

```
LiveDemo
```
— 使用
```
@editframe/react
```
中的Preview/FitScale/FocusOverlay/Filmstrip渲染原始HTML
```
SkillsTable
```
— 检测属性/类型/描述列标题以应用增强样式
```
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

Content Guidelines

内容指南

Length Targets

篇幅目标

Type	Target	Focus
`reference`	60-100 lines	Attributes, basic usage, common patterns
`tutorial`	~90 lines	Step-by-step with `html live` demos, minimal intro
`how-to`	20-40 lines	Single task, actions only, no rationale
`explanation`	60-80 lines	Conceptual deep-dive, no code/config

类型	目标篇幅	重点
`reference`	60-100行	属性、基础用法、常见模式
`tutorial`	~90行	带 `html live` 演示的分步指南，简介尽量简洁
`how-to`	20-40行	单一任务，仅包含操作步骤，无需原理说明
`explanation`	60-80行	概念深度解析，无代码/配置内容

Writing Principles

写作原则

One mode per document. Each file fits one

type

. If content belongs in another mode, link to it instead of including it. Tutorials don't explain architecture. References don't include rationale. How-tos don't teach concepts.

Don't repeat across files. If a concept is explained in one reference, link to it from others. If a sentence shares meaning with another sentence in the same document, remove one.

Neutral, technical language. Describe platform constraints and outcomes, not prescriptive commands or comparative critiques:

"Native playback requires full file download" not "You must download the entire file"
"Direct file playback presents these constraints" not "Traditional workflows are slow"
Qualify absolutes: "typically within seconds" not "immediately"

Effects over implementation. Explain what the user sees, not internal machinery. "The player is reactive and incremental" not "The backend segments the file."

Show, don't describe. Use

html live

blocks to demonstrate. Every tutorial step and how-to solution should have a working demo. Reference files show basic usage, not just attribute lists.

Real assets. Use URLs from

https://assets.editframe.com/

for demos (e.g.,

bars-n-tone.mp4

单文档单模式。每个文件仅对应一种

type

。如果内容属于其他模式，请链接至对应文档而非包含在内。教程不解释架构，参考文档不包含原理说明，操作指南不教授概念。

避免跨文件重复。如果某个概念已在某份参考文档中解释，其他文档请链接至该文档。如果同一文档内存在语义重复的句子，删除其中一句。

中立、技术化语言。描述平台限制和结果，而非指令性命令或对比批评：

应写“原生播放需要完整下载文件”而非“你必须下载整个文件”
应写“直接文件播放存在以下限制”而非“传统工作流速度缓慢”
绝对表述需限定：“通常在数秒内”而非“立即”

重效果轻实现。解释用户可见的结果，而非内部机制。“播放器具备响应式和增量加载特性”而非“后端会对文件进行分段处理”。

演示优先，避免描述。使用

html live

块进行演示。每个教程步骤和操作指南的解决方案都应包含可运行的演示。参考文档需展示基础用法，而非仅列出属性。

使用真实资源。演示中使用

https://assets.editframe.com/

中的URL（例如：

bars-n-tone.mp4

）。