Learn by demo lite

Learn-by-Demo Lite

Stop letting your agent guess APIs. Capture one real demonstration — every URL, header, and payload the workflow actually sends — then draft your automation from observed traffic, not hallucinated endpoints.

Why guessing fails

When an agent is told to automate a UI-driven system with no API docs, the default failure mode is to guess: it invents an endpoint path, invents the auth scheme, invents the body shape. Every wrong guess comes back as:

• 401 / 403 — the auth header is missing, malformed, or the wrong scheme.
• HTML instead of JSON — the guessed path doesn't exist, so the server returns a login page or a SPA shell.
• Burned iterations — each wrong guess is a full request/parse/retry loop converging on nothing.

A single real demonstration solves both halves at once: the real endpoint, method, and body shape, and the real authorization as it was actually sent. You capture facts, then replay facts.

The Iron Rules

1. Never hardcode an API or form flow before you have seen the real request. No endpoint path, no header, no body schema goes into automation until it appeared in a capture.
2. Prefer the user's already-logged-in browser session. A second automated login can trigger single-device kick-out and invalidate the user's session. In this Lite edition that means: capture from the user's own browser window (DevTools), don't open a parallel login.
3. Copy exactly what you captured — endpoint, headers, auth, body schema — then parameterize. Reproduce first, generalize second.

The capture workflow (Lite)

1. Decide. Does the task drive a UI, and are the exact endpoints unknown? If the target has documented public APIs, read the docs instead.

2. Capture. Two zero-install options:

   • Your agent runtime's own network reader — if the runtime you are in can read network requests from a browser it controls, arm it before the user clicks anything, then read the captured requests directly.
   • Browser DevTools HAR export — the user opens DevTools → Network, checks "Preserve log", performs the workflow slowly (pausing per step), then right-clicks → "Save all as HAR".

3. Draft. Feed the capture to the draft tool:

   python scripts/har_draft.py capture.har
   

   You get a redacted Markdown draft per endpoint: method, URL template (volatile ids normalized to {id}/{uuid}), auth type, query parameters, request-body field names, and statuses seen.

4. Build replay from the draft. Reproduce one call exactly as captured (same headers, same body shape) and confirm it returns the same result the user saw. Only then parameterize.

5. Persist. Write the endpoint/field/flow knowledge into a project-level skill or memory so the next run needs no demonstration.

Try it on the bundled synthetic capture: python scripts/har_draft.py fixtures/sample_capture.har

Handling captured secrets

Captures contain live credentials. Discipline is non-negotiable:

• har_draft.py always redacts Authorization, Cookie, API-key headers, and token-ish query parameters. There is no off switch.
• Never commit a raw HAR. Keep captures out of version control (add them to .gitignore) and delete them when done.
• Replay reads tokens from an environment variable, never a literal in the script.
• Never paste a raw capture into a prompt, issue, or chat. Draft first.

Anti-patterns

• Guessed-endpoint loop. Inventing /api/.../records and its body, getting 401s and HTML, and retrying with another guess. Fix: capture the real request once.
• Second-login kick-out. Spinning up a separate automated login "to test", which invalidates the user's live session. Fix: capture from the user's own window.
• Committing a live token. Saving a raw HAR with a valid Authorization header into the repo. Fix: draft (redacted) goes in the repo; the HAR does not.

Lite vs. full

This Lite edition covers the methodology plus HAR-to-draft. The full Learn-by-Demo adds: a Playwright capture harness that attaches to the user's already-logged-in browser over CDP (JSONL + HAR output), session-preservation recipes (storage state, persistent profiles, the three ways around single-device kick-out), a machine-readable endpoint-spec format, a replay-script scaffold generator (tokens via env var), and batch-hardening patterns (pagination, token-expiry refresh, polite rate pacing, baseline verification) — with a worked end-to-end example against a public demo site.

Responsible use

Only automate systems you are authorized to use, and respect the target system's terms of service. This skill does not help bypass authentication, CAPTCHAs, bot detection, or access controls.

Not affiliated with Anthropic; Claude is a trademark of Anthropic, referenced only to describe compatibility.