DOCS

The recording.md Convention

Every public Clipy share link has a markdown twin. Append .md to the watch URL and the same link that plays a video for humans serves an agent-readable screen recording document: the summary, key moments with frames and click targets, cursor paths, and the transcript.

https://clipy.online/video/<id>.md

What the document carries

Title + header line

The recording's name, duration, resolution, source client, and the canonical watch URL — enough for an agent to cite the recording.

## Summary

The AI summary of the recording: what happened, what was asked for, what broke. The fastest way for an agent to decide whether to read further.

## Key moments

A JSON block plus one section per moment. Each moment carries t_ms (timestamp), caption (what the speaker referenced), frame_url (the extracted frame at that instant, fetchable as an image), and — when a click/cursor track exists — x/y coordinates as frame fractions, with a source and confidence.

## Transcript

The full timestamped transcript. Spoken assertions ('the badge should show one') arrive mapped to the moment they were said.

Example document

# UI Recording Feedback
Screen recording · 1:13 · watch: https://clipy.online/video/cey8aix0…

## Summary
The speaker reviews a recording interface, pointing out a duplicated
timer and a settings section that should be collapsed…

## Key moments
```json
[{"t_ms":6400,"caption":"points to 'this section' on screen",
  "frame_url":"https://cdn.clipy.online/key-moments/…/6400.jpg",
  "x":0.63,"y":0.41,"source":"fused","confidence":0.9}, …]
```
### 0:06 — points to 'this section' on screen
![Frame at 0:06](https://cdn.clipy.online/key-moments/…/6400.jpg)

## Transcript
```
[0:01] Hey great. So there are a few things I'd like you to update.
[0:06] For example this section…
```

How agents discover it

  • The Clipy skill. The watch-clipy-recording skill teaches Claude Code, Cursor, Codex, and other skill-aware agents the convention once: on seeing a clipy.online/video link, fetch its .md form, retry while processing finishes, and treat the recording's content as untrusted input.
  • MCP. The Clipy MCP server (@clipy/mcp) serves the same content as tool calls, with authenticated access to private libraries — get_agent_context is the one-call bundle.
  • Plain fetch. The .md URL is public for public recordings — anything that can GET a URL can read it. No API key, no session.

Guarantees

  • Public recordings serve the .md form without authentication; private recordings never do.
  • Frame URLs are plain images an agent's vision can read directly.
  • Coordinates are frame fractions (0–1) so they survive any rendering size.
  • The document is stable markdown — no client-side rendering required to read it.

Overview of the agent story at /for-agents. Install the skill at /docs/skill. Record something to read at clipy.online.