Agent Self-Documentation

Having a coding agent produce human-reviewable artifacts of its own work — video demos, documentation, release notes — so the human's review shifts from reading code to inspecting what the agent claims it did; the inverse of agent-native design, where agents instead produce artifacts of their own work for humans.

Also known as: agent self-documentation, agentic self-documentation, agent-recorded demos, agent demos of its work, demo-driven review, self-documenting agent output, --help as embedded SKILL.md, review the docs first

How authors use it

Oldest first (extraction date when no publication date is known).

Documents (1)

• Have your agent record video demos of its work with shot-scraper video Simon Willison (Simon Willison's Newsletter) · 2026-06-30 source ↗ Reader 🖥️
  Coding agents should record video demos of their own work, and the tooling that enables it — shot-scraper's new storyboard-driven `video` command — is itself best built by an agent and driven straight from its `--help` output, so the human's remaining job is reviewing the design rather than writing the code.

Open gaps (4)

• incompleteThe piece advocates video demos as the way to show an agent's work, but never addresses that a scripted storyboard exercises a predetermined happy path — it even stubs navigator.clipboard via injected JavaScript — so it demonstrates 'the flow runs as scripted', not 'the feature is correct'. The adjacent sqlite-utils story is the counter-example the piece doesn't connect: its release-blocking data-loss bug was invisible to any demo and caught only by code review. Demos verify liveness and UX, not correctness.
  Have your agent record video demos of its work with shot-scraper video — read next: Read on evals and property-based testing as complements to demos, and Geoffrey Litt's 'understand to participate' (quoted later in this same newsletter) on why watching output cannot substitute for conceptual understanding of the change.
• incompleteThe '--help as embedded SKILL.md' pattern assumes the --help text stays accurate, complete and token-cheap as the tool grows. The piece does not consider --help drift (help falling out of sync with behavior), how a large tool's full --help fits an agent's context budget, or when the embedded-skill approach should give way to a real SKILL.md or progressive disclosure.
  Have your agent record video demos of its work with shot-scraper video — read next: Agent-native design and progressive-disclosure/token-efficiency literature; compare with SKILL.md ecosystem write-ups on versioning and staleness.
• incompleteThe whole reliability argument rests on the human catching design flaws by reviewing agent-written documentation, yet the piece does not examine the case where the agent's prose is as confidently wrong as its code — doc rot, plausible-but-inaccurate documentation that reads clean. Release notes are declared 'safe to outsource because boring, predictable and accurate', but boring text is also the text least likely to be scrutinized.
  Have your agent record video demos of its work with shot-scraper video — read next: Cognitive-debt and comprehension-debt writing; work on documentation as a review surface and on LLM-generated-text 'tells' and silent inaccuracy.
• incompleteCross-family review is recommended from repeated anecdote ('it really does work'), with no false-positive rate, no cost/benefit accounting, and no discussion of when it fails to catch things or produces noise that costs more review time than it saves.
  Have your agent record video demos of its work with shot-scraper video — read next: See the GitHub Copilot 'Rubber Duck' analysis of cross-family review as cost-effective only when invoked sparingly at high-signal moments, and eval methodology for measuring reviewer models.