feat: Agents record one clip around an action and read its sheets and numbers

Merged
HA
8d ago
+471-150

Summary

  • Agents now learn from the record-video skill to record one clip around an action and read its sheets and numbers. They no longer extract stills at one per second, which misses one-frame flashes.
  • The screenshot description sends agents to record-video for anything that changes between frames.

User Impact

  • Before:
    • The skill described a manual start/stop flow and suggested ffmpeg -vf fps=1 to look at a recording.
    • The description said nothing about flicker or one-frame glitches, so agents reached for a screenshot (one frame) or reported a video path they could not judge.
  • After:
    • The skill leads with --seconds N --trigger '<uloop command>', then reading the burst sheet, the timeline sheet, and the frame change numbers.
    • It says when to trigger by input and when by a trace pause point.
    • It says to judge flicker by the alternating counts rather than all changed frames. Measured: a one-frame blink gave 62 / 30 / 30 and the same element fixed to a 1 s pulse gave 58 / 3 / 4 (FramesChangedVsPrevious / MatchingTwoBack / Count).
    • It says to record the broken state first.
    • It points at re-cutting frames with --video when ffmpeg is installed.

Changes

  • New descriptions for record-video and screenshot.
    • The record-video example quotes the trigger with single quotes: the skill frontmatter reader strips the outer quotes but does not unescape, so \" would reach the tool catalog as a literal backslash.
  • The record-video skill body is rewritten (6,493 bytes, limit 8,000). Its parameter table gains rows for the six CLI-only flags.
  • Output fields (including the new sheet, frame, and one-shot fields), troubleshooting, notes, the detailed reading of the numbers, and frame extraction move to references/output-and-troubleshooting.md.
  • The tool catalog and the generated .claude / .agents skill copies are regenerated.
  • The README lines for record-video are updated in English and Japanese.
  • ADR 0019 records the decision, the measurements (per-frame cost, mark-to-effect offset, flicker numbers), and when to revisit it.

Verification

  • check-skill-size: no SKILL.md over the limit.
  • scripts/sync-tool-docs.sh --check: the catalog matches the skill tables.
  • check-release-triggers: passes.
  • uloop run-tests (regex SkillParameterTableCoverageTests|SkillInstallLayoutTests): 28 passed, 0 failed.
  • uloop skills install --claude --agents, then diff: the generated record-video (with its reference file) and screenshot copies match the sources.