# Garden Skills Outline Format Specification: A Complete Guide to Video-Style Web Presentations

> Learn the Garden Skills outline format specification using Markdown. Structure video presentations with chapter segmentation and timing. Get the complete guide.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: api-reference
- Published: 2026-08-29

---

**Garden Skills uses a human-readable Markdown outline ([`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md)) as the single source of truth for structuring video-style web presentations, defining chapter segmentation, step timing, and content density while leaving visual styling to chapter agents.**

The **outline format specification** in the ConardLi/garden-skills repository establishes a structured yet editable development plan for creating cinematic web experiences. This specification, documented in [`skills/web-video-presentation/references/OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/OUTLINE-FORMAT.md), ensures that complex video presentations remain maintainable by separating rhythmic structure from animation implementation.

## Core Components of the Outline Format

A valid [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) file consists of several distinct sections that work together to define the presentation flow. Each section serves a specific purpose in the content pipeline, from high-level metadata to per-step screen instructions.

### Metadata Block

The file opens with a **metadata block** formatted as block quotes for rapid scanning. This section specifies the theme, total duration, and chapter count using Chinese field labels:

```markdown
> **主题**：`my-theme-id` — 我的主题描述
> **总时长**：约 3 分 20 秒（口播 ~250 字/分钟）
> **章节数**：2 章 / 12 步

```

These fields establish the presentation boundaries and inform the chapter agent about content density expectations before processing individual segments.

### Chapter Headings

Each chapter begins with a standardized ATX heading that encodes structural metadata directly in the title. The format follows this strict pattern:

```markdown

## N. <id> — <title>（<S> steps · ~<T>s）

```

For example: `## 1. coldopen — 开场引入（4 steps · ~40s）`. The **chapter ID** must be lower-case and hyphenated (e.g., `coldopen`, `hook`, `data-preview`). This identifier serves triple duty as the React component key, folder name, and audio sub-directory name within the project structure.

### Information Pool

Immediately following the chapter heading, the **information pool** provides a curated bullet list of extracted data points from [`article.md`](https://github.com/ConardLi/garden-skills/blob/main/article.md). This section supplies raw material—such as statistics, citations, and case studies—that the chapter agent references while rendering each step:

```markdown
**信息池**：
- 数字：30% 增长率 —— 来自 article 第 2 段
- 案例：XYZ 产品评测 —— article 第 5 段

```

### Development Plan

The **development plan** section lists each step with estimated duration and screen content description. Steps use the format `- step N (~Ts) — <screen content>`, specifying exactly what appears on screen during that interval:

```markdown
**开发计划**：
- step 1 (~10s) — 大标题 + 背景图
- step 2 (~8s)  — 关键数字弹出
- step 3 (~12s) — 案例引用卡片
- step 4 (~10s) — 章节标题出现

```

### Narration Excerpt

Optional **narration excerpts** illustrate the spoken text accompanying specific steps, formatted as block quotes under the heading `口播节选：`. This bridges the gap between the visual outline and the full [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) source material.

## Formatting Rules and Conventions

The specification enforces strict conventions to ensure compatibility with the automated build pipeline and chapter agents.

### Chapter ID Naming Rules

Valid chapter IDs must adhere to specific character constraints to prevent routing and filesystem errors. According to the specification in [`skills/web-video-presentation/references/OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/OUTLINE-FORMAT.md):

- **Valid**: Lower-case letters, hyphens, and numbers (e.g., `coldopen`, `data-comparison`)
- **Invalid**: Underscores, camelCase, or non-Latin characters (e.g., `cold_open`, `dataComparison`, `数据比较`)

These IDs propagate through the entire system, appearing in file paths like `src/chapters/01-coldopen/` and TypeScript imports.

### Field Conventions Table

The specification documentation includes a reference table defining required metadata fields:

| Field | Required | Description |
|---|---|---|
| 主题 | Yes | Theme identifier and description |
| 总时长 | Yes | Estimated total duration with speech rate context |
| 章节数 | Yes | Total chapters and step count |

## Integration with the Garden Skills Workflow

The [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) file functions as the central hub in a synchronized documentation ecosystem. Changes to the outline require cascading updates to dependent files to maintain build integrity.

### Syncing with script.md and narrations.ts

After editing [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md), developers must ensure alignment with two generated files:

1. **[`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md)**: Contains the full narration script whose beats inform the `(~Ts)` timing estimates in the outline
2. **[`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts)**: Auto-generated TypeScript definitions that validate step counts and timing against the outline structure

The chapter agent consumes the outline array during the build step, transforming Markdown steps into renderable React components.

### The Self-Check Requirement

The specification mandates a **self-check process** before committing changes. This verification ensures that step counts in chapter headings match the development plan, timing totals align with the metadata block, and chapter IDs follow naming conventions. Skipping this validation risks breaking the chapter agent's rendering pipeline.

## Practical Implementation Example

The following minimal example demonstrates a complete chapter definition following the outline format specification:

```markdown

# Video Outline

> **主题**：`my-theme-id` — 我的主题描述
> **总时长**：约 3 分 20 秒（口播 ~250 字/分钟）
> **章节数**：2 章 / 12 步

---

## 1. coldopen — 开场引入（4 steps · ~40s）

**信息池**：
- 数字：30% 增长率 —— 来自 article 第 2 段
- 案例：XYZ 产品评测 —— article 第 5 段

**开发计划**：
- step 1 (~10s) — 大标题 + 背景图
- step 2 (~8s)  — 关键数字弹出
- step 3 (~12s) — 案例引用卡片
- step 4 (~10s) — 章节标题出现

口播节选：
> “在过去的半年里，我们看到惊人的 30% 增长率…”

```

The chapter agent converts this Markdown into a consumable TypeScript array located at [`src/chapters/01-coldopen/outline.ts`](https://github.com/ConardLi/garden-skills/blob/main/src/chapters/01-coldopen/outline.ts):

```typescript
export const outline = [
  { step: 1, duration: 10, content: "大标题 + 背景图" },
  { step: 2, duration: 8,  content: "关键数字弹出" },
  { step: 3, duration: 12, content: "案例引用卡片" },
  { step: 4, duration: 10, content: "章节标题出现" },
];

```

This array drives the runtime rendering engine, with each entry mapping to a full-screen presentation step.

## Summary

- The **outline format specification** defines [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) as a Markdown-based single source of truth for video-style web presentations in Garden Skills.
- **Metadata blocks** use block quotes for theme, duration, and chapter count, while **chapter headings** encode IDs, step counts, and timing in a standardized format.
- The **information pool** provides extracted data references, and the **development plan** lists screen content per step with precise duration estimates.
- Chapter IDs must be lower-case hyphenated strings used across React keys, folder structures, and audio directories.
- The outline must remain synchronized with [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) and [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts), requiring a mandatory self-check before committing changes.

## Frequently Asked Questions

### What is the difference between outline.md and script.md in Garden Skills?

[`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) structures the presentation flow by defining chapters, steps, and timing, while [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) contains the full narration text. The outline references the script for timing estimates and narration excerpts but focuses on screen content density and rhythmic structure rather than verbatim spoken text.

### How do I format a chapter ID correctly in the outline specification?

Chapter IDs must be lower-case, hyphenated strings without underscores or special characters. Valid examples include `coldopen`, `hook`, and `data-comparison` as implemented in the ConardLi/garden-skills repository. These IDs become React component keys, directory names (e.g., `src/chapters/01-coldopen/`), and audio sub-directory identifiers.

### Why does the outline format require a self-check before committing?

The self-check validates that step counts in chapter headings match the development plan lists, ensures timing totals align with metadata blocks, and verifies that chapter IDs follow naming conventions. This prevents build failures in the chapter agent pipeline, which relies on strict structural consistency between the outline, [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md), and auto-generated [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) files.

### Can I edit outline.md after generating narrations.ts?

Yes, but you must regenerate [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) and verify synchronization with [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) afterward. The specification requires that all three files remain in sync because the chapter agent uses the TypeScript definitions to validate runtime rendering against the Markdown outline structure.