# Tutorial Generating

> Transform a folder of unnamed screenshots and a rough markdown draft into a polished, illustrated tutorial document. Use when the user has a set of screenshots (e.g., from Snipaste or other tools) with timestamp-based filenames and a brief markdown outline, and wants to produce a complete step-by-step instructional document with images renamed by content and inserted at appropriate positions. Tri…

- **Type:** Skill
- **Install:** `agentstack add skill-opensourceways-agent-skills-tutorial-generating`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [opensourceways](https://agentstack.voostack.com/s/opensourceways)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [opensourceways](https://github.com/opensourceways)
- **Source:** https://github.com/opensourceways/agent-skills/tree/main/skills/operation/content/tutorial-generating

## Install

```sh
agentstack add skill-opensourceways-agent-skills-tutorial-generating
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tutorial Generating

将一组以时间戳命名的截图和一份粗略的 Markdown 草稿，转化为一份完整的、图文并茂的操作指导文档。自动完成截图内容识别、语义化重命名，以及文档结构补全与图片插入。

## Workflow

### 1. 扫描目标文件夹

列出用户指定文件夹中的所有文件，区分图片文件和文档文件：

```bash
# 列出所有文件
ls -la "/"

# 筛选图片文件（支持 png/jpg/jpeg/gif/webp）
find "" -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.webp" \) | sort

# 筛选 Markdown 文件
find "" -maxdepth 1 -type f -name "*.md"
```

**输出**：
- 图片文件列表（按文件名/时间排序）
- Markdown 草稿文件路径
- 文件数量统计

### 2. 识别图片内容（OCR）

使用 macOS 系统自带的 Vision 框架进行 OCR 文字识别，提取每张图片中的关键文字信息。

#### 2.1 编译 OCR 工具

创建并编译一个 Swift 小工具，调用 macOS Vision 框架：

```swift
// ocr_images.swift
import Foundation
import Vision
import AppKit

let args = CommandLine.arguments
guard args.count > 1 else {
    print("Usage: ocr_images ")
    exit(1)
}

let imagePath = args[1]
guard let image = NSImage(contentsOfFile: imagePath),
      let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
    print("ERROR: Cannot load image")
    exit(1)
}

let request = VNRecognizeTextRequest { request, error in
    guard let observations = request.results as? [VNRecognizedTextObservation] else { return }
    for observation in observations {
        if let topCandidate = observation.topCandidates(1).first {
            print(topCandidate.string)
        }
    }
}

request.recognitionLevel = .accurate
request.recognitionLanguages = ["zh-Hans", "en-US"]

let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([request])
```

编译命令：

```bash
swiftc -o ocr_tool ocr_images.swift -framework Vision -framework AppKit
```

#### 2.2 批量 OCR 所有图片

对每张图片执行 OCR，记录识别结果：

```bash
for img in "/"*.png; do
    echo "=== $(basename "$img") ==="
    ./ocr_tool "$img"
    echo "---"
done
```

**关键信息提取**：从 OCR 结果中识别：
- UI 元素（按钮文字、菜单项、对话框标题）
- 关键操作（安装、设置、搜索、选择）
- 上下文信息（应用名称、配置项名称）

### 3. 语义化重命名图片

根据 OCR 识别出的内容，为每张图片生成语义化文件名。

#### 3.1 命名规则

文件名格式：`{序号}-{动作}-{对象}.png`

- **序号**：两位数字，按操作流程顺序排列（`01`、`02`、`03`...）
- **动作**：描述截图中的核心操作（如 `install`、`enable`、`open`、`select`、`create`）
- **对象**：描述操作的目标（如 `copilot-extension`、`agent-skills-setting`）
- 使用英文小写和连字符，不使用空格或中文

**命名示例**：

| OCR 关键内容 | 命名结果 |
|-------------|----------|
| GitHub Copilot 扩展安装页面 | `01-install-copilot-extension.png` |
| 设置搜索 chat.useAgentSkills | `04-enable-agent-skills-setting.png` |
| git clone 命令 | `10-git-clone-agent-skills-repo.png` |
| 资源管理器目录结构 | `11-agent-skills-repo-structure.png` |

#### 3.2 执行批量重命名

使用 Python 脚本进行安全的批量重命名（避免 shell 转义问题）：

```python
import os

base = ""
renames = {
    ".png": ".png",
    ".png": ".png",
    # ...
}

for old, new in renames.items():
    src = os.path.join(base, old)
    dst = os.path.join(base, new)
    if os.path.exists(src):
        os.rename(src, dst)
        print(f"OK: {old} -> {new}")
    else:
        print(f"SKIP: {old} not found")
```

> **注意**：文件夹路径包含空格时，shell 的 heredoc 和链式 `mv` 命令容易出错。推荐使用 Python 脚本文件而非内联命令。

### 4. 阅读并分析 Markdown 草稿

读取用户提供的 Markdown 草稿，理解其结构和意图：

```bash
cat "/instruction.md"
```

**分析要点**：
- 识别文档主题和目标读者
- 提取关键步骤的概要（通常是简短的要点列表）
- 确定步骤之间的逻辑顺序
- 将草稿中的简略描述与 OCR 识别出的截图内容进行对应

### 5. 补全 Markdown 文档

将草稿扩展为完整的操作指导文档，遵循以下结构规范。

#### 5.1 文档结构模板

```markdown
# [文档标题]

[一段简介，说明文档目的和适用对象]

---

## 前置准备

[列出开始操作前需要满足的条件]

### 1. [准备项1]
[详细说明 + 截图]

### 2. [准备项2]
[详细说明 + 截图]

---

## 步骤 N：[步骤标题]

[简要说明本步骤的目的]

### N.1 [子步骤]
[操作说明]

### N.2 [子步骤]
[操作说明]

> **说明/提示：** [补充说明]

---

## 常见问题

| 问题 | 解决方案 |
|------|----------|
| ... | ... |
```

#### 5.2 文档编写原则

- **标题层级**：使用 `#` 到 `####`，层级不超过4级
- **步骤编号**：主步骤使用 "步骤 N"，子步骤使用 "N.1"、"N.2"
- **操作描述**：具体、明确，包含 **UI 路径**（如"点击左下角齿轮图标 → 设置"）
- **关键词加粗**：菜单名、按钮名、配置项用 `**粗体**` 标注
- **代码块**：命令行操作使用 ` ```bash ``` ` 包裹
- **引用提示**：使用 `> **说明：**` 或 `> **注意：**` 添加补充信息
- **分隔线**：主要章节之间使用 `---` 分隔

### 6. 在文档中插入图片

将重命名后的图片以 Markdown 语法插入到文档的对应位置。

#### 6.1 图片插入语法

```markdown

```

#### 6.2 图片放置原则

- **紧跟操作说明之后**：先写文字描述操作步骤，紧接着插入对应截图
- **一图一步**：每个关键操作步骤配一张截图，不堆叠多张
- **描述文字有意义**：`` 中的 alt 文字应准确描述图片内容，方便搜索和无障碍访问
- **按操作流程排列**：图片顺序与步骤顺序严格一致

#### 6.3 图片与步骤对应示例

```markdown
### 2. 安装 GitHub Copilot 扩展

在 VS Code 的扩展市场中搜索 **GitHub Copilot** 并安装：

```

### 7. 最终检查与输出

完成文档后进行以下检查：

#### 7.1 完整性检查
- [ ] 所有截图均已在文档中引用
- [ ] 文档中所有图片引用的文件名与实际文件名一致
- [ ] 无遗漏的操作步骤

#### 7.2 格式检查
- [ ] Markdown 语法正确（标题层级、列表、代码块等）
- [ ] 图片 alt 文字完整且有描述性
- [ ] 表格格式正确
- [ ] 无多余空行或格式错误

#### 7.3 验证图片引用

```bash
# 提取文档中所有图片引用
grep -oP '!\[.*?\]\(\K[^)]+' "/instruction.md"

# 对比实际图片文件
ls "/"*.png

# 检查是否有孤立图片（未被文档引用）或断链引用（文件不存在）
```

## 处理特殊情况

### 文件夹路径含空格
路径含空格时（如 `skill instruction/`），shell 命令容易出错。应对策略：
- 使用 Python 脚本替代 shell 批量操作
- 所有路径用双引号包裹
- 避免 shell heredoc 内使用复杂路径

### 图片无法 OCR
某些截图可能是纯图形、图标或高度风格化的文字，OCR 无法识别。处理方式：
- 结合图片尺寸和时间戳推断在流程中的位置
- 参照草稿中的步骤描述进行人工匹配
- 使用通用描述命名（如 `05-step5-ui-overview.png`）

### 草稿过于简略
如果草稿仅有几个关键词，需要：
1. 优先依赖 OCR 结果理解完整流程
2. 结合工作空间中的相关文件（README、其他文档）补充上下文
3. 按截图的时间顺序还原操作流程
4. 用行业通用的操作指导文档写法补全

### 非 macOS 环境
Vision 框架仅限 macOS。在其他平台上：
- Linux/Windows：安装 `tesseract` 和 `pytesseract`
- 替代方案：`brew install tesseract`（macOS 备选）或使用在线 OCR API

## 注意事项

- OCR 工具编译后的二进制文件和 Python 重命名脚本属于临时文件，完成后应清理
- 重命名前建议备份原始图片，以防命名出错需要回溯
- 文档中图片路径使用相对路径，确保文档和图片在同一目录下可正常显示
- 对于包含敏感信息的截图（如 token、密码），应在文档中提醒脱敏处理

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [opensourceways](https://github.com/opensourceways)
- **Source:** [opensourceways/agent-skills](https://github.com/opensourceways/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-opensourceways-agent-skills-tutorial-generating
- Seller: https://agentstack.voostack.com/s/opensourceways
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.