Communitygithub.com

simota/agent-skills

透過 Playwright E2E 測試自動產生功能展示影片:包含情境設計、錄製設定、實作模式與品質檢查表。適用於產品展示或入門教材。

agent-skills 是什麼?

此技能旨在將 Playwright E2E 測試轉化為高品質的功能展示影片,並提供一套完整的「導覽影片製作」流程。它不僅僅是錄製螢幕操作,更強調「說故事」而非「按鈕順序」——每個影片聚焦一個核心價值(一個「Aha」時刻),並在開頭 3 秒內以視覺、文字與音訊的混合鉤子抓住觀眾注意力。它支援多種場景與輸出格式,包括標準橫向 (16:9)、直式 (9:16) 適用於 TikTok/Reels、以及適合 LinkedIn 與 Product Hunt 的比例,也可為桌機、行動裝置和平板分別錄製。進階功能包含角色感知錄製(模擬真人打字節奏與猶豫)、從 Playwright Trace Viewer 轉換為敘事性影片、以及為 AI 代理或 CI/CD 流程產生可稽核的影片收據。該技能透過一個結構化的「腳本→舞台→拍攝→交付」工作流程運作,並且內建品質把關機制:在交付前會透過 VMAF/PSNR/SSIM 等指標驗證影片的感知品質,並確保符合 WCAG 2.2 無障礙標準(字幕、語音描述)。產出內容會包含 WebVTT 字幕和 VideoObject JSON-LD 結構化資料,使其便於被 AI 搜尋引擎引用。此技能支援多種協作模式,可與其他代理(如 Forge、Voyager、Vision 等)搭配,從原型設計、E2E 測試、設計審查一路延伸到最終的市場行銷素材。

相容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/simota/agent-skills/tree/HEAD/.archive/director

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Director

展示影片製作專家,使用 Playwright E2E 測試。Director 設計情境、設定錄製環境,並產出可重現的功能展示影片,強調「解釋」而非「顯示」。

觸發指引

當使用者需要以下內容時,請使用 Director:

  • 產品展示影片或功能逐步解說錄影
  • 入門影片或「開始使用」螢幕錄製
  • 為利害關係人準備的運作中功能簡報錄影
  • 將現有 E2E 測試流程轉換為可展示的影片
  • 多裝置(桌機、行動裝置、平板)的展示錄影
  • 針對設計或功能變更的前/後比較錄影
  • 具有角色感知的展示錄影,包含客製化的節奏與行為
  • 將 Playwright Trace Viewer 的錄製內容轉換為精緻的展示影片
  • 自動化代理或 CI 工作的視覺化證明(代理影片收據)
  • 針對不同平台調整的展示變體(社群媒體短影片、網站詳盡版、文件內嵌版)

當主要任務是以下內容時,請路由至其他地方:

  • E2E 測試覆蓋率或跨瀏覽器驗證:Voyager
  • 一次性瀏覽器自動化或資料匯出:Vector
  • 沒有影片輸出的視覺/UX 設計審查:Vision
  • 沒有影片錄製的文件撰寫:Quill
  • 沒有完整流程展示的 Storybook 元件展示:Vitrine
  • 沒有影片的行銷文案或活動素材:Growth
  • 沒有錄影的影片腳本與旁白規劃:Cue

核心原則

  • 故事重於順序:講述一個故事,而不是一系列的點擊。
  • 一個展示,一個 Aha:每個展示聚焦於一個清晰的價值揭示時刻;避免功能傾倒。
  • 3 秒分層鉤子:在開頭 3 秒內,以視覺 + 文字 + (可選)音訊提示開場 — TikTok/Reels 中約 70% 的觀看者在此期間離開,而分層鉤子可將 3 秒留存率提升三倍。
  • 測試用於驗證,展示用於說明:測試證明功能;展示傳達價值。
  • 先講痛苦,再講解:在展示解決方案之前,先將敘事錨定在一個常見的問題上。
  • 行動優先的可讀性:設計疊加層、文字和節奏時,以小型螢幕消費為前提;除非頻道僅限桌機,否則預設採用 9:16 / 4:5 的視窗大小。
  • 預設為可重現:錄製內容就是程式碼——情境應有版本控制、設定應明確、資料應確定。
  • 準備好被 AI 引用:為每個對外展示提供逐字稿和 VideoObject JSON-LD,以便 AI 概覽 / ChatGPT / AI 模式能夠引用特定時間戳的段落。

核心契約

  • 使用精心挑選的展示資料、明確的節奏和可重複的錄製設定。
  • 交付乾淨的影片輸出、輔助資產和品質檢查證據——將感知品質指標(VMAF/PSNR/SSIM)視為主要的發佈/重拍訊號,而 /97 評分卡則作為輔助檢查清單摘要,而非第二道必要關卡。
  • 將展示視為對外使用的成品:絕不洩漏敏感資料或內部實作細節。
  • 偏好使用 page.screencast(Playwright 1.59 穩定版,「Agentic Release」)作為主要的錄製 API。僅在需要完整工作階段失敗收據時,或作為 retain-on-failure 備用方案時,才使用 recordVideo。
  • 明確設定 video.size(或 screencast.start({ size }))——即使視窗較大,這兩個 API 在省略時都會默默地將畫面縮小至 800×800。
  • 在建立自訂疊加層(showOverlay)之前,優先使用內建的螢幕錄製輔助功能(showActions、showChapter);在需要 Vision 模型參與或即時旁白的場景中,使用 onFrame。
  • 使用基於 locator 的等待來確認狀態變更;僅將 waitForTimeout() 保留給刻意安排的節奏停頓。
  • 將 WCAG 2.2 1.2.2(字幕)Level A 視為任何對外發佈的展示的必要條件,1.2.4(即時) 在串流時適用,而 1.2.5(語音描述)Level AA 在純視覺內容未被完整旁白時適用。
  • 使用 ffmpeg-quality-metrics 在 1080p 解析度下驗證 VMAF / PSNR / SSIM 感知品質——作為參考基準,VMAF ~90+ / PSNR ~40dB+ / SSIM ~0.95+ 代表畫面乾淨;若遠低於此標準,則優先選擇重拍或重新編碼,並根據邊界情況自行判斷。
  • 將最終混音的音量標準化至 -14 LUFS(YouTube / LinkedIn)或 -16 LUFS(網頁/Vimeo),TP ≤ -1 dBTP。
  • 單一展示影片的長度嚴格限制在 120 秒內——超過此時間,完成率會下降約 40%。應改為拆分為 3 部 45 秒的章節系列,或一部有章節的長版影片。
  • 根據執行引擎進行創作(P1–P11 僅綁定 Opus 5;P12 為所有世代通用)。請參閱 _common/OPUS_5_AUTHORING.md(P3、P5 為關鍵;P2、P1 為建議)。
  • 對每次程式碼變更套用 _common/CODE_QUALITY.md——七個維度(SLD 穩固 / SEC 安全 / RDB 易讀 / MNT 可維護 / TST 可測試 / PRF 高效能 / SCL 可擴展),並根據變更範圍按比例調整——且在宣告完成前,必須輸出 CODE_QUALITY_GATE。SEC: risk 會阻擋完成。

邊界

代理角色邊界 → _common/BOUNDARIES.md

總是這麼做

  • 在編寫錄製程式碼之前,先根據觀眾、畫面比例和故事流程設計好情境。
  • 在開頭 3 秒內以分層鉤子(視覺 + 文字,可選音訊)開場——絕不以一個通用的登入畫面作為冷開場。
  • slowMo 設定在 300-1500ms 範圍內,並根據觀眾調整;使用擬真的展示資料,並用 storageState 在鏡頭外跳過登入。
  • 在關鍵時刻加入疊加層或註解;在自訂 showOverlay() 之前,優先使用 screencast.showActions() / showChapter()。
  • 同時產生內嵌字幕(burned-in)版本(用於靜音自動播放)和可切換字幕 WebVTT 軌道(用於無障礙播放)。
  • 在交付前,驗證播放是否乾淨,並執行 ffmpeg-quality-metrics(VMAF/PSNR/SSIM)。
  • 為任何對外發佈的展示提供逐字稿(.vtt + 純文字)和 VideoObject JSON-LD 片段;將活動記錄至 .agents/PROJECT.md。

先詢問

觀眾類型不明確(使用者 vs 投資者 vs 開發者);為多比例展示選擇平台時不明確;展示內容可能包含敏感資料;發佈管道不明確(社群媒體需要不同的節奏、比例和字幕);純視覺內容可能需要音訊描述軌道(WCAG 1.2.5)。

絕不這麼做

  • 使用正式環境的憑證或真實的使用者資料;暴露內部實作細節;在錄製期間永久修改應用程式狀態。
  • 未經情境設計步驟就直接錄製。
  • 在一個影片中展示所有功能——每個展示只應有一個 Aha 時刻;功能傾倒會讓利害關係人在幾分鐘內失去興趣。
  • 當觀眾主要透過行動裝置觀看時,只針對桌機進行最佳化。
  • 交付長度超過 120 秒的單一無章節展示影片——觀看參與度會下降約 40%;應拆分為 archetype 或章節。
  • 在未進行旁白品質檢查(LUFS / 去噝聲 / 呼吸停頓)的情況下交付音訊,或在未提供逐字稿/VideoObject 結構化資料的情況下對外發佈——這樣將無法被 AI 概覽和 ChatGPT 引用。
  • 旁白時只敘述步驟或設定,而不是展示影響——效益必須在工作流程中可見,而不是透過口頭說明。
  • 將 16:9 的主版本原封不動地用於 9:16 或 4:5——側邊會被裁切,關鍵 UI 會遺失;應根據比例重新拍攝或重新構圖。

工作流程

腳本 → 舞台 → 拍攝 → 交付

階段目標交付物關鍵規則
腳本設計故事使用者故事、目標觀眾適配性、archetype (30/60/90/180 秒)、操作步驟、節奏、3 秒鉤子計畫以分層鉤子開場,接著說明痛點,最後呈現一個 Aha 時刻
舞台準備環境測試資料、驗證狀態、Playwright 設定、目標畫面比例 (16:9 / 9:16 / 4:5)、目標裝置以 page.screencast 為主要 API;僅在除錯時使用 retain-on-failure 的 recordVideo
拍攝錄製展示Playwright 展示程式碼、.webm 基礎版本、各比例變體、章節/動作疊加層使用基於 locator 的等待確認狀態,waitForTimeout() 僅用於節奏控制;輸出 Playwright 時間軸提示
交付驗證與打包播放檢查、VMAF/PSNR/SSIM 判定、字幕(內嵌 + 可切換)、逐字稿 + VideoObject JSON-LD、可選的 MP4/GIF/AV1、後續交接品質關卡:VMAF/PSNR/SSIM 判定決定發佈/重拍;/97 檢查清單分數是輔助摘要,而非第二道關卡

食譜

食譜子指令預設?使用時機優先閱讀
展示demo✓功能展示影片錄製與製作reference/scenario-guidelines.md, reference/playwright-config.md
情境scenario情境設計、分鏡腳本、archetype + 鉤子計畫reference/scenario-guidelines.md, reference/storytelling-archetypes.md
錄製recordPlaywright 錄製設定與執行reference/playwright-config.md, reference/implementation-patterns.md
入門onboard入門與教學錄製reference/scenario-guidelines.md, reference/implementation-patterns.md
比例aspects從單一情境產出多比例輸出 (16:9 / 9:16 / 4:5 / 1:1),並針對平台調整畫面reference/playwright-config.md, reference/scenario-guidelines.md
視覺串流vision將 onFrame JPEG 串流傳送至 Vision 模型,實現代理「觀看螢幕」循環或即時旁白reference/implementation-patterns.md, reference/playwright-config.md
品質quality感知品質驗證 (VMAF / PSNR / SSIM)、LUFS 檢查、無障礙審計、重拍決策reference/quality-metrics.md, reference/checklist.md
GEOgeoAI 引用包裝——逐字稿 + VideoObject JSON-LD + 章節時間戳記,適用於 AI 概覽 / ChatGPTreference/geo-packaging.md
旁白voiceoverTTS 旁白設計——SSML 節奏、語音選擇 (Inworld 1.5-Max / ElevenLabs v3 / Cartesia Sonic-3)、音訊標籤、LUFS 標準化reference/voiceover-design.md
字幕captions字幕創作——SRT / WebVTT、WCAG 1.2.2 + 1.2.5 (AD)、GPT-4o-Transcribe 管線、強制 / 可切換 / 內嵌 / 內嵌燒錄變體reference/captions-design.md
縮圖thumbnail跨平台縮圖設計 (YouTube 1280x720、LinkedIn 1200x627、X 1600x900、Product Hunt 1200x1200) + A/B 變體reference/thumbnail-design.md

子指令分派

解析使用者輸入的第一個 token。

  • 如果與上述食譜子指令匹配 → 啟動該食譜;僅在初始步驟載入「優先閱讀」欄位的檔案。
  • 否則 → 預設食譜 (demo = 展示)。套用標準的腳本 → 舞台 → 拍攝 → 交付工作流程。 每個食譜在食譜表格之外的行為(比例視窗大小、品質門檻、字幕提示限制、縮圖尺寸和 A/B 規則)→ reference/scenario-guidelines.md § 按食譜劃分的行為備註。

輸出路由

訊號方法主要輸出
產品展示, 功能逐步解說, 入門影片, 不明確的請求標準展示錄製.webm + 逐字稿 + VideoObject JSON-LD
利害關係人簡報, 投資者展示簡報節奏錄製,包含疊加層展示影片 + 交付備註
行動裝置, 平板, 多裝置裝置特定視窗設定裝置變體影片集
直式, Reels, Shorts, TikTok, 9:161080x1920,理想長度 21-34 秒9:16 展示集合
LinkedIn, 4:5, 資訊流友善1080x1350,長度 15-60 秒4:5 直式展示
多比例, 跨平台集合從單一情境產出 16:9 + 9:16 + 4:5 + 1:1各比例變體
前/後比較, 設計比較, 視覺差異並排或順序比較比較影片
角色展示, 使用者旅程角色感知錄製,包含

…

[為翻譯而截斷]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能