asciinema-recorder

asciinema-recorder

为使用 asciinema 录制 Claude Code 会话生成可直接复制的命令。根据工作区和日期时间动态创建文件名。

平台：macOS、Linux（需要 asciinema CLI）

持续演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数有所变化，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 开始新的终端录制会话
• 创建演示或文档录制
• 录制 Claude Code 会话，以便审核或分享
• 生成特定于工作区的录制文件名

---

为什么使用此技能？

此技能会生成可直接复制的录制命令，包含：

• 根据工作区动态生成的文件名
• 用于确保唯一性的日期时间戳
• 保存到项目的 tmp/ 文件夹（已加入 gitignore）

---

要求

组件	必需	安装方式
asciinema CLI	是	brew install asciinema

---

工作流阶段

阶段 0：预检

目的：确认已安装 asciinema。

# Check asciinema CLI
which asciinema && asciinema --version

如果未安装 asciinema，请使用 AskUserQuestion：

• question: "未找到 asciinema。你希望如何继续？" header: "设置" multiSelect: false options:
  • label: "安装 asciinema（推荐）" description: "运行：brew install asciinema（macOS）或 apt install asciinema（Linux）"
  • label: "显示手动安装说明" description: "显示适用于所有平台的安装命令"
  • label: "取消" description: "退出且不录制"

根据所选项：

• “安装 asciinema” → 根据操作系统运行相应的安装命令：

  # macOS
  brew install asciinema
  
  # Linux (apt)
  sudo apt install asciinema
  
  # Linux (pip)
  pip install asciinema
  

  然后继续阶段 1.0。

• “显示手动安装说明” → 显示上述命令，然后退出技能。

• “取消” → 退出技能，不执行任何操作。

---

阶段 1.0：录制位置

目的：让用户选择录制文件的保存位置。

使用 AskUserQuestion：

• question: "录制文件应保存到哪里？" header: "位置" multiSelect: false options:
  • label: "$PWD/tmp/（推荐）" description: "项目 tmp 目录（已加入 gitignore）"
  • label: "~/asciinema/" description: "全局录制文件目录"
  • label: "自定义路径" description: "指定自己的目录"

根据所选项：

• “$PWD/tmp/” → 设置 OUTPUT_DIR="$PWD/tmp"
• “~/asciinema/” → 设置 OUTPUT_DIR="$HOME/asciinema"，如果目录不存在则创建：mkdir -p ~/asciinema
• “自定义路径” → 将用户在“其他”输入中提供的值用作 OUTPUT_DIR

---

阶段 1.1：录制选项

目的：让用户配置录制行为。

使用 AskUserQuestion：

• question: "你想使用哪些录制选项？" header: "选项" multiSelect: true options:
  • label: "添加标题/描述" description: "在录制元数据中包含会话标题（-t 标志）"
  • label: "禁用空闲时间限制" description: "保留完整的暂停时间，而不是最多 2 秒（--idle-time-limit 0）"
  • label: "静默模式" description: "不显示 asciinema 状态消息（-q 标志）"

根据所选项构建命令标志：

• “添加标题” → 继续提问以选择标题，并添加 -t "title" 标志
• “禁用空闲时间限制” → 添加 --idle-time-limit 0 标志
• “静默模式” → 添加 -q 标志

如果选择了“添加标题”，请继续询问：

• question: "请输入此录制的标题：" header: "标题" multiSelect: false options:
  • label: "使用工作区名称" description: "标题：${WORKSPACE}"
  • label: "使用工作区名称 + 日期时间" description: "标题：${WORKSPACE} ${DATETIME}"
  • label: "自定义标题" description: "输入自己的标题"

根据所选标题：

• “使用工作区名称” → 设置 TITLE="${WORKSPACE}"
• “使用工作区名称 + 日期时间” → 设置 TITLE="${WORKSPACE} ${DATETIME}"
• “自定义标题” → 将用户在“其他”输入中提供的值用作 TITLE

---

阶段 1.2：检测上下文并生成命令

目的：生成可直接复制粘贴的录制命令。

步骤 1.2.1：检测工作区

从 $PWD 提取工作区名称：

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
WORKSPACE=$(basename "$PWD")
echo "Workspace: $WORKSPACE"
SKILL_SCRIPT_EOF

步骤 1.2.2：生成日期时间

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
DATETIME=$(date +%Y-%m-%d_%H-%M)
echo "Datetime: $DATETIME"
SKILL_SCRIPT_EOF_2

步骤 1.2.3：确保输出目录存在

创建阶段 1.0 中选定的输出目录：

mkdir -p "${OUTPUT_DIR}"

步骤 1.2.4：构建命令

使用以下内容构建录制命令：

• 阶段 1.0 中的 OUTPUT_DIR（位置选择）
• 阶段 1.1 中的标志（选项选择）
• 如果选择了“添加标题”，则使用 TITLE

# Base command
CMD="asciinema rec"

# Add flags from Phase 1.1 options
# (Claude builds this based on user selections)

# Final command format:
asciinema rec ${FLAGS} "${OUTPUT_DIR}/${WORKSPACE}_${DATETIME}.cast"

输出示例：

# Default (no options selected):
asciinema rec /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast

# With title + quiet mode:
asciinema rec -t "my-app Demo" -q /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast

# With all options:
asciinema rec -t "my-app 2025-12-21 14:30" -q --idle-time-limit 0 ~/asciinema/my-app_2025-12-21_14-30.cast

---

阶段 2：用户指引

目的：逐步说明录制工作流。

显示以下说明：

## Recording Instructions

1. **Exit Claude Code** - Type `exit` or press `Ctrl+D`
2. **Copy the command** shown above
3. **Paste and run** in your terminal (starts a recorded shell)
4. **Run `claude`** to start Claude Code inside the recording
5. Work normally - everything is captured
6. **Exit Claude Code** - Type `exit` or press `Ctrl+D`
7. **Exit the recording shell** - Type `exit` or press `Ctrl+D` again

Your recording will be saved to:
`$PWD/tmp/{workspace}_{datetime}.cast`

---

阶段 3：补充信息

目的：提供录制后的实用提示。

## Tips

- **Environment variable**: `ASCIINEMA_REC=1` is set during recording
- **Playback**: Use `asciinema-player` skill or `asciinema play file.cast`
- **Upload (optional)**: `asciinema upload file.cast` (requires account)
- **Markers**: Add `asciinema marker` during recording for navigation points

---

TodoWrite 任务模板

模板：录制 Claude Code 会话

1. [Preflight] Check asciinema CLI installed
2. [Preflight] Offer installation if missing
3. [Context] Detect current workspace from $PWD
4. [Context] Generate datetime slug
5. [Context] Ensure tmp/ directory exists
6. [Command] Construct full recording command
7. [Guidance] Display step-by-step instructions
8. [Guidance] Show additional tips (playback, upload)
9. Verify against Skill Quality Checklist

---

变更后检查清单

修改此技能后：

1. 命令生成仍使用 $PWD（没有硬编码路径）
2. 指引步骤仍然清晰且与平台无关
3. TodoWrite 模板与实际工作流相符
4. README.md 条目仍准确无误
5. 使用 quick_validate.py 验证

---

CLI 选项参考

选项	标志	描述
标题	-t	录制标题（用于 asciinema.org）
静默	-q	禁止显示状态消息
追加	-a	追加到现有录制内容

---

故障排除

“无法在 Claude Code 内录制”

原因：asciinema 必须包装程序运行，而不能从程序内部启动。

解决方法：先退出 Claude Code，然后运行生成的命令。

“录制文件过大”

原因：长时间会话会生成较大的文件。

解决方法：

• 使用 asciinema upload 在线存储，而不是本地存储
• 将长会话拆分成较短的录制内容

“回放时输出乱码”

原因：终端尺寸不匹配。

解决方法：回放时使用 -r 标志调整终端尺寸。

---

参考文档

• asciinema CLI 文档
• asciinema 标记

执行后复盘

此技能完成后，在结束任务前进行复盘：

0. 确认位置。 — 找到此 SKILL.md 的规范路径后再进行编辑。
1. 哪里失败了？ — 修复导致失败的指引。
2. 哪些地方的效果超出预期？ — 将其提升为推荐做法。
3. 有哪些内容已不一致？ — 修复任何与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。 — 添加演进日志条目，记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。