tutorial-updates

チュートリアル更新スキル

VHS テープファイルと Playwright ブラウザースペックを使った GIF 録画で、チュートリアル生成をオーケストレーションします。

使用する場合

• ユーザー向けチュートリアルを生成または更新する場合
• VHS および Playwright のチュートリアル録画を作成する場合

使用しない場合

• ユーザー向けチュートリアルを含まない内部ドキュメントの場合
• API リファレンスドキュメントの場合は、代わりに scribe:doc-generator を使用してください

概要

このスキルは、チュートリアル生成のパイプライン全体を調整します。

1. プロジェクト内のテープファイルとマニフェストを検出します
2. テープのコマンドを検証し、バイナリが最新か確認します
3. バイナリが古い場合は再ビルドし、デモに最新のコードを反映します
4. VHS を使用してターミナルセッションを録画します（scry:vhs-recording）
5. Playwright を使用してブラウザーセッションを録画します（scry:browser-recording）
6. 最適化された GIF を生成します（scry:gif-generation）
7. 複数コンポーネントのチュートリアルを構成します（scry:media-composition）
8. docs/ と book/ 用のデュアルトーン Markdown を生成します

コマンドオプション

/update-tutorial quickstart        # Single tutorial by name
/update-tutorial sync mcp          # Multiple tutorials
/update-tutorial --all             # All tutorials with manifests
/update-tutorial --list            # Show available tutorials
/update-tutorial --scaffold        # Create structure without recording

検証： コマンドが使用可能であることを確認するには、--help フラグを付けて実行します。

必須の進捗項目

進捗管理のため、次の接頭辞を付けて TODO を作成します。

**Verification:** Run the command with `--help` flag to verify availability.
- tutorial-updates:discovery
- tutorial-updates:validation
- tutorial-updates:rebuild
- tutorial-updates:recording
- tutorial-updates:generation
- tutorial-updates:integration

検証： コマンドが使用可能であることを確認するには、--help フラグを付けて実行します。

フェーズ 1：検出（tutorial-updates:discovery）

ステップ 1.1：チュートリアルのアセットを特定する

プロジェクト内のテープファイルとマニフェストを検索します。

# Find manifest files
find . -name "*.manifest.yaml" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find tape files
find . -name "*.tape" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find browser specs
find . -name "*.spec.ts" -path "*/browser/*" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

検証： コマンドが使用可能であることを確認するには、--help フラグを付けて実行します。

ステップ 1.2：マニフェストを解析する

各マニフェストファイルから、次の情報を抽出します。

• チュートリアル名とタイトル
• コンポーネントの一覧（テープファイル、Playwright スペック）
• GIF の出力先パス
• 構成ルール（レイアウト、結合オプション）

マニフェストのスキーマの詳細は modules/manifest-parsing.md を参照してください。

ステップ 1.3：オプションを処理する

オプション	動作
--list	検出したチュートリアルを表示して終了します
--all	検出したすべてのマニフェストを処理します
--scaffold	録画せずにディレクトリ構造と空のファイルを作成します
<names>	指定されたチュートリアルのみを処理します

--list が指定された場合：

**Verification:** Run the command with `--help` flag to verify availability.
Available tutorials:
  quickstart     assets/tapes/quickstart.tape
  sync           assets/tapes/sync.tape (manifest)
  mcp            assets/tapes/mcp.manifest.yaml (terminal + browser)
  skill-debug    assets/tapes/skill-debug.tape

検証： コマンドが使用可能であることを確認するには、--help フラグを付けて実行します。

フェーズ 1.5：検証（tutorial-updates:validation）

重要： 時間のかかる再生成を避けるため、VHS を実行する前にテープのコマンドを検証してください。

テープごとに次の 4 項目を確認します。VHS の構文（Output ディレクティブがあり、引用符の対応が取れていること）、各 Type コマンドの CLI フラグが --help と一致すること、デモデータが存在し入力済みであること、そして失敗、空の出力、ハングを検出するためにタイムアウト付きで各コマンドをローカル実行することです。スクリプトと検証の終了条件は modules/tape-validation.md に記載されています。

検証フラグ

フラグ	動作
--validate-only	GIF を生成せずに検証を実行します
--skip-validation	すばやく再生成するため、検証を省略します

検証に失敗した場合： 直ちに停止してエラーを報告し、VHS による録画を続行しないでください。

フェーズ 1.6：バイナリの再ビルド（tutorial-updates:rebuild）

重要： テープでテストするバイナリが最新のソースコードと一致していることを確認してください。古いバイナリを使うと、誤解を招くデモになります。

ビルドシステム（Cargo または Make）を検出し、バイナリの mtime を Git HEAD と比較します。古い場合は再ビルドし、バイナリが PATH 上にあり、--version を実行できることを確認します。スクリプト、フラグ、再ビルドの終了条件は modules/binary-rebuild.md に記載されています。

再ビルドに失敗した場合： 直ちに停止してビルドエラーを報告し、テープの検証や VHS による録画を続行しないでください。

フェーズ 2：録画（tutorial-updates:recording）

ステップ 2.1：テープコンポーネントを処理する

各テープファイルコンポーネントについて、次の手順を実行します。

1. テープファイルからメタデータ注釈（@step、@docs-brief、@book-detail）を解析します
2. Output ディレクティブがあることを検証します
3. テープファイルのパスを指定して Skill(scry:vhs-recording) を呼び出します
4. GIF の出力が作成されたことを確認します

ステップ 2.2：ブラウザーコンポーネントを処理する

各 Playwright の spec コンポーネントについて、次の手順を実行します。

1. requires フィールドで前提となるコマンド（例：サーバーの起動）を確認します
2. 必要なバックグラウンドプロセスを起動します
3. spec のパスを指定して Skill(scry:browser-recording) を呼び出します
4. バックグラウンドプロセスを停止します
5. WebM を GIF に変換するため、Skill(scry:gif-generation) を呼び出します

ステップ 2.3：複数コンポーネントのチュートリアルを処理する

combine セクションがあるマニフェストについて、次の手順を実行します。

1. すべてのコンポーネントの GIF が存在することを確認します
2. マニフェストを指定して Skill(scry:media-composition) を呼び出します
3. 結合された出力が作成されたことを確認します

フェーズ 3：生成（tutorial-updates:generation）

ステップ 3.1：テープの注釈を解析する

テープファイルからドキュメントの内容を抽出します。

# @step Install skrills
# @docs-brief Install via cargo
# @book-detail The recommended installation method uses cargo...
Type "cargo install skrills"

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。

注釈：

• @step - ステップのタイトル／見出し
• @docs-brief - プロジェクトドキュメント（docs/ ディレクトリ）向けの簡潔なテキスト
• @book-detail - 技術書（book/ ディレクトリ）向けの詳細なテキスト

ステップ 3.2：2 つのトーンの Markdown を生成する

各チュートリアルについて、次の 2 つのバージョンを生成します。

1. プロジェクトドキュメント（docs/tutorials/<name>.md）

   • 簡潔で、行動を促す内容
   • @docs-brief の内容を使用
   • コマンドとすぐに得られる結果に焦点を当てる

2. 技術書（book/src/tutorials/<name>.md）

   • 詳細で、学習に役立つ内容
   • @book-detail の内容を使用
   • 概念とその根拠を説明する

書式の詳細については、modules/markdown-generation.md を参照してください。

ステップ 3.3：README のデモセクションを生成する

README.md のデモセクションを作成または更新します。

## Demos

### Quickstart
![Quickstart demo](assets/gifs/quickstart.gif)
*Install, validate, analyze, and serve in under a minute. [Full tutorial](docs/tutorials/quickstart.md)*

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。

フェーズ 4：統合（tutorial-updates:integration）

ステップ 4.1：すべての出力を確認する

想定されるすべてのファイルが存在することを確認します。

# Check GIF files
for gif in assets/gifs/*.gif; do
  if [[ -f "$gif" ]]; then
    echo "OK: $gif ($(du -h "$gif" | cut -f1))"
  else
    echo "MISSING: $gif"
  fi
done

# Check markdown files
ls -la docs/tutorials/*.md 2>/dev/null
ls -la book/src/tutorials/*.md 2>/dev/null

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。

ステップ 4.2：SUMMARY.md を更新する（書籍）

プロジェクトに mdBook の構成がある場合は、book/src/SUMMARY.md を更新します。

- [Tutorials](./tutorials/README.md)
  - [Quickstart](./tutorials/quickstart.md)
  - [Sync Workflow](./tutorials/sync.md)
  - [MCP Integration](./tutorials/mcp.md)
  - [Skill Debugging](./tutorials/skill-debug.md)

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。

ステップ 4.3：結果を報告する

更新内容を要約します。

**Verification:** Run the command with `--help` flag to verify availability.
Tutorial Update Complete
========================
Tutorials processed: 4
GIFs generated: 5
  - quickstart.gif (1.2MB)
  - sync.gif (980KB)
  - mcp-terminal.gif (1.5MB)
  - mcp-browser.gif (2.1MB)
  - skill-debug.gif (890KB)

Markdown generated:
  - docs/tutorials/ (4 files)
  - book/src/tutorials/ (4 files)

README demo section updated

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。

完了条件

• 指定されたすべてのチュートリアルを処理した（または --all の場合はすべて処理した）
• マニフェストで指定されたパスに GIF ファイルが作成された
• 各チュートリアルについて、2 つのトーンの Markdown が生成された
• README のデモセクションが GIF の埋め込みで更新された
• 書籍の SUMMARY.md が更新された（該当する場合）
• すべての進捗項目が完了した

エラー処理

エラー	解決方法
VHS がインストールされていない	go install github.com/charmbracelet/vhs@latest
Playwright がインストールされていない	npm install -D @playwright/test && npx playwright install chromium
テープファイルに Output がない	Output assets/gifs/<name>.gif ディレクティブを追加します
ブラウザーの spec でサーバーが必要	spec を実行する前にサーバーを起動します
GIF のサイズが大きすぎる	gif-generation の fps/scale を調整します

スキャフォールドモード

--scaffold が指定された場合、記録を行わずに構成を作成します。

1. assets/tapes/ ディレクトリを作成します
2. assets/gifs/ ディレクトリを作成します
3. assets/browser/ ディレクトリを作成します（ブラウザーチュートリアルを予定している場合）
4. メタデータ注釈を含むテープファイルのテンプレートを作成します
5. マニフェストファイルのテンプレートを作成します
6. docs/tutorials/ と book/src/tutorials/ に空の Markdown ファイルを作成します

テープファイルのテンプレート：

# @title: Tutorial Name
# @description: Brief description of the tutorial

Output assets/gifs/tutorial-name.gif
Set FontSize 14
Set Width 1200
Set Height 600
Set Theme "Catppuccin Mocha"

# @step Step 1 Title
# @docs-brief Brief docs text
# @book-detail Extended book text with more context and explanation
Type "command here"
Enter
Sleep 2s

検証： コマンドを --help フラグ付きで実行し、利用できることを確認します。