preview-md

MD File Browser Preview

After finishing MD files that need review, such as solutions/plans, open a GitHub-style preview in the browser.

Trigger Conditions

When you (Claude) complete the creation or major modification of the following types of MD files,this skill must be triggered：

Solution design documents (docs/specs/**/*.md）
Development plan documents (docs/plans/**/*.md）
Any MD file the user explicitly requests to preview

Non-skippable principle: When the above trigger conditions are met, Step 1 must be executed to ask the user whether to preview. Claude must not decide on its own to skip for any reason (such as "pure backend document", "simple content", "does not involve UI", etc.). Whether to preview is decided by the user, not by Claude.

Scenarios that do not trigger :

Non- .md files: Files in other formats such as HTML, JSON, YAML do not go through this skill (HTML prototypes are opened directly with the open command)
Non-review files such as memory files, CLAUDE.md, README.md, etc.
Minor modifications to MD files (such as fixing typos, updating status markers)

Execution Flow

Step 1: Ask the user

After the MD file is written, ask the user:

文件已创建：<文件路径>
要在浏览器中打开预览吗？

Step 2: Open the preview after user confirmation

After the user confirms, execute:

node ~/.claude/skills/preview-md/scripts/preview-md.mjs <md-file-absolute-path>

Step 3: Wait for feedback

After the preview opens, wait for the user's review feedback, and modify the document content based on the feedback.

Notes

The script is located at ~/.claude/skills/preview-md/scripts/preview-md.mjs
The script generates a temporary HTML file and opens it with the default browser
Rendering features: GitHub Markdown CSS + fixed left sidebar table of contents (h1-h4) + scroll highlighting + smooth jumping

Extended syntax: terminal / flow code blocks

preview-md provides two kinds oflightweight diagram code blockson top of standard Markdown, designed specifically for scenarios where you "don't want to invoke the diagram skill but still want more visual impact than plain text". Producers (writing / deep-research, etc.) should output according to the conventions in this section.

```terminal — Terminal Window

Use when showing command-line operations, CLI output, installation/startup steps. Renders as a macOS-style terminal window (red/yellow/green dots + title bar).

When to use：

Showing a command execution (single or multiple)
Showing an example of command output
Setup steps in development guides/quick starts

When not to use：

A single command with no special formatting → just use a regular ```bash is fine
Pure code snippets (non-shell context) → use the code block for the corresponding language

Syntax: The first line may optionally be $ title as the window title, and the rest is the content.

```terminal
$ 快速开始
npm install
npm run dev
# 服务启动在 http://localhost:3000
```

```flow — Lightweight Flowchart

Use when showing processes, decision trees, or step sequences. Faster than invoking the diagram skill and closer to the main text, suitable forsimple to medium complexitylinear/branching flows.

When to Use：

"Execution Steps" Illustration in the Solution
Decision tree (including ？/? nodes are automatically highlighted in decision style)
Workflow Stage Chaining

When Not to Use：

Complex multi-branch merging and directed graphs → call the diagram skill to draw a real flowchart
Time-sequence interactions (multiple roles) → call the diagram skill to draw a sequence diagram

Syntax：

Form	Syntax	Rendering
Vertical Trunk	One node per line,`↓` on its own line as the connector	Trunk pills centered in a column, ↓ aligned with the trunk
Horizontal Flow	Within one line, use `→` to separate multiple nodes	Tiled horizontal pill chain
Mixed Horizontal and Vertical	Trunk is vertical; a certain line embeds `→ 分支`	Trunk runs down the middle column, branches extend to the right
Decision Node	Node text contains `？` or `?`	Yellow pill with border
Annotation	Append after the node `（xxx）`	Gray annotation text attached to the right side of the node

Example：

```flow
task-manager
↓
task-start（对焦 + 方案）
↓
task-execute → 编码 → 调试
↓
需求完成？→ task-finish → 标 done
```

Design Principles：

Do not write long sentences in a flow block; keep each node within 10 characters, and put overly long information in the body text
→ extension is only used to attach 1-3 branch nodes; any more should be split into multiple lines or switched to diagram
One flow block expresses one complete small process; do not cram multiple unrelated processes into the same block