1How It Works & Mechanism
The default orientation is 'preserving UI takes precedence over removing canvas': only crop when key UI remains fully visible throughout zooms and scrolls, and proof frames confirm that the tightest crop remains valid.
skills/product-demo-integration/SKILL.mdDefault to preserving UI over removing background canvas.
What is being done here: Downgrading cropping from a 'beautification default' to a 'conditional, risky operation', using proof frames as an unlocking prerequisite—exemplifying the family-wide recurring pattern of 'prove first, act second'.
Build a moment map first (screen recording timestamps / visible content / corresponding narration phrase / target global time / cursor importance / scroll position importance / subtitle overlap / crop safety) before deciding on trimming and retiming.
skills/product-demo-integration/SKILL.mdCreate a moment map before editing:
What is being done here: Tabulating 'which frame corresponds to which spoken line' upfront, avoiding repeatedly scrubbing through the recording to locate moments during editing.
Transition-in rule: Start from the final frame of the previous scene, use a camera swipe or push rather than a hard cut (if continuity is requested by the user), and land on the current initial frame of the screen recording; crop leading dead time only when sync is maintained.
skills/product-demo-integration/SKILL.md- Land on the current first frame of the product recording.
What is being done here: Treating 'first-frame alignment' as a hard requirement, rooted in the same first-frame matching discipline of scene-continuity-and-transitions.
Four synchronization criteria: The product state must be visible at the narration moment (trigger transitions early if needed), hold the final frame if comprehension is critical, slow down earlier segments rather than unnaturally accelerating scrolls, and never cut mid-word.
skills/product-demo-integration/SKILL.md- Do not cut mid-word in narration to reach a product state.
What is being done here: Defining 'sync' as 'landing the product state on the spoken line' rather than 'duration alignment'—hence favoring adjusting upstream speed over hard cuts.
Screen cleanup has an itemized checklist but must remain restrained: cursors, browser UI, notification popups, dead time, blank loading screens, desktop edges, scroll speed, and zoom focus—process these only if it does not harm product clarity.
skills/product-demo-integration/SKILL.md- Notification popups.
What is being done here: Enumerating all cleanable items (including privacy-sensitive notification popups) while constraining over-processing via 'Only remove or hide these if it does not harm product clarity.'
The crop decision matrix is divided into three tiers: no crop (user accepts canvas, zoom spans screens, body text would be cut, product state matters more than polish), light crop (canvas distracts but UI is centered, subtitles need space, browser chrome or dead margins can be safely removed), and dynamic crop (every crop rectangle is mapped, motion appears intentional, and proof frames exist for all critical product states).
skills/product-demo-integration/SKILL.mdChoose dynamic crop only when:
What is being done here: Turning 'how much to crop' into conditional criteria rather than an aesthetic preference, with dynamic crop having the strictest unlock requirements.
Front-load user approval checkpoints: Ask first before cropping visible canvas, removing cursors, significantly speeding up footage, blurring or masking product details, or replacing genuine recordings with recreated mock UI.
skills/product-demo-integration/SKILL.mdAsk before:
- Cropping out visible canvas.
What is being done here: Designating edits that 'potentially alter informational authenticity' as requiring approval; replacing authentic recordings with mock UI is especially sensitive as it may be misinterpreted as actual product capability.
2Core Capabilities
01Screen recording intake inspection: duration, resolution, frame rate, audio; identifies presence of canvas, browser chrome, cursor, zooms, scrolls, or dead time
02Three-tier crop decisions (no crop / light crop / dynamic crop) and crop safety procedures: sample frames at recording start, zoom peaks, scroll resting points, required product states, and final frame; test candidate crops frame-by-frame and reject if any critical text, cursor context, or UI control is cut, preferring slightly wider framing
03Transition rules and proof frames for entering/exiting product segments (sample transition boundaries; prevent accidental blank frames at recording tails; allow sufficient registration time for the final product state)
04Product moment mapping and narration synchronization (early transitions when needed, holding final frames, slowing preceding footage rather than accelerating scrolls, no mid-word cuts)
05Subtitle safety review: check bottom navigation bars, product tables, modal buttons, and timeline controls when burning subtitles; adjust subtitle margins or swap proof frames as needed
06QA checklist and handoff fields (first product frame, zoom peaks, required product states, in/out transitions, subtitles not obstructing UI; handoff reports covering source recordings, crop strategy, cut points, retime ratios, critical proof frames, and unresolved UI imperfections)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|
| cli | 媒体探测与切分（时长/分辨率/帧率/音轨；trim 与重定时）——SKILL.md 只写探测要求，具体命令由同族 ffmpeg/ffprobe 链路承担 |
| cli | ffmpeg（间接：抽帧与接触表的实现工具，见仓库根 scripts/extract_proof_frames.py） |
| package | 素材输入：用户提供的原始屏幕录制（SaaS demo / app 录屏 / 浏览器录制），本地文件，无外部服务 |
| package | 参考文件 skills/product-demo-integration/references/crop-and-zoom.md（裁切安全程序与常见错误清单） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Local script or command execution: (No scripts inside this skill directory) The host inspects, extracts frames from, crops, and retimes screen recordings per documentation (ffmpeg/ffprobe toolchain), rendering product segments
- 本地工作目录: File read/write and artifact output: Cropped and retimed product segments and rendered outputs (under renders/)
Audit Notes: The skill directory contains only SKILL.md + references/crop-and-zoom.md (pure instructions, no scripts); behavioral scope is limited to local file read/write (sampling frames, cropping, retiming, rendering, and exporting proof frames from recordings) and local media tools, conforming to the blue tier. **No assets sent to external services**: full scan confirms no http(s):// endpoints, no fetch/requests, and no token/env reading; recordings are provided by the user and processing occurs entirely locally. The documentation establishes user approval gates for edits that might mislead viewers, such as 'blurring or masking product details' or 'replacing genuine recordings with mock UI'. Aligned with the classification criteria of nine peer skills: contains only SKILL.md (+ references), scope limited to local read/write and local CLI, with no endpoints, credentials, or external asset transmission.
5Second-Pass Verification
- [ok] 「无网络无凭证」是否成立 — 目录扫描无 URL、无 fetch、无 token/env/cookie；产品录屏作为本地素材处理，无上传、无生成服务，故不构成橙档。
- [ok] 三处裁切判据是否自相矛盾 — SKILL.md 的 Use crop only when（三个必要条件）、Crop Decision Matrix（三档适用条件）、references 的四步程序（逐帧测试与否决规则）方向一致：默认不裁、裁切需证据、动态裁切最严。未发现冲突。
- [discrepancy] 探测要求是否有可执行命令 — 本 skill 与族内多件一样只写探测要求，未点名 ffprobe 或仓库脚本；实际命令在 audio-sync-assembly（ffprobe 与探测脚本）与 render-qa-and-surgical-changes（scripts/probe_media.py）里。只加载本件时探测动作需自行补齐。
- [ok] 用户批准点是否覆盖 references 建议的所有激进编辑 — SKILL.md 的 Ask before 列表含裁掉可见画布、去光标、大幅加速、模糊或遮罩产品细节、用重制 UI 替换真实录屏；覆盖了 crop-and-zoom.md 建议的动态裁切与「更优替代方案」中涉及真实性的项，未见遗漏的高风险编辑。
- [ok] 转场规则是否与 scene-continuity-and-transitions 一致（避免两件给出不同做法） — 本件要求从前一场景末帧起、用相机擦或推而非硬切、落在当前首帧、边界抽证明帧；scene-continuity-and-transitions 的首帧匹配与边界证明程序方向相同（后者另给 0.05s 前后与转场中间的抽帧程序），互为细化而非冲突。
- [ok] 是否有未声明的素材外发（例如云端转写或云渲染） — 全目录无端点、无服务名；清理与裁切均在本地完成。唯一外生动作是宿主抽帧后的读图（若使用视觉模型），不属本 skill 声明的调用。
6Verdict & Scenarios
Defines cropping as a 'risky action unlocked only by evidence', using proof frames as an unlock requirement to directly prevent the most common failure mode (cutting off critical UI after zooming)Uses a moment map to tabulate 'which frame corresponds to which spoken line' upfront, providing an objective basis for trimming and retiming rather than relying on iterative scrubbingFeatures a clear synchronization philosophy: favors slowing preceding segments over unnaturally speeding up product scrolls, and avoids cuts mid-wordSeparately isolates subtitle conflicts with product UI (bottom navigation, tables, modal buttons, timeline controls), addressing a frequent challenge unique to product demosSubmits edits that might mislead viewers (removing cursors, blurring details, replacing recordings with mock UI) to user approval rather than agent discretionBest for: Suitable for: Scenarios where the user provides raw screen recordings (SaaS demos, app walkthroughs, browser captures, product walkthroughs) that must be integrated into a designed video—determining whether to crop, how to transition in and out, how to synchronize product states with narration, ensuring subtitles do not block UI, and validating using proof frames.
Not for: Not suitable for: ① Scenarios without any product screen recordings (use hyperframes-scene-builder / motion-design-systems); ② Tasks requiring recording or capturing product footage on the user's behalf (this skill only processes existing recordings, no acquisition); ③ Projects requiring deep post-production compositing (multi-track, keying, tracking)—this skill covers only cropping, transitions, timing, and readability; ④ Projects requiring material licensing and privacy compliance audits (not covered in documentation).