HTML Editorial Design — Two-Agent Workflow

A Claude Code skill and project template for iteratively improving the visual design of HTML editorial documents — magazines, annual reports, research booklets, conference programs, longform essay collections — through a two-agent reviewer/implementer team.

What this is

A workflow pattern, plus the tooling to run it:

• skill/ — A Claude Code skill (html-editorial-design/SKILL.md plus supporting files) that teaches Claude how to set up and orchestrate the workflow for any HTML editorial project.
• example_project/ — A working template you can copy as a starting point: CLAUDE.md, .claude/agents/sophia.md, .claude/agents/skipper.md, and a placeholder for your HTML.
• docs/ — Walkthroughs, design principles, and notes on when this workflow fits.

The pattern in one paragraph

Two specialized subagents trade off review and implementation across short rounds. Sophia is a product manager with front-end design taste — she reviews the HTML, produces a prioritized feedback list, and decides when to ship. Skipper is an HTML/CSS engineer — he implements Sophia's feedback, writes the revised HTML back to disk, and produces a change log. Hard constraints prevent either agent from touching text content or embedded assets; they work on design, color, layout, typography, and spacing only. Typical projects ship in 2–4 design rounds, plus targeted content-restoration rounds if needed.

Why two agents

Single-agent design loops drift. The model that designs the change also evaluates the change, and quality plateaus quickly. Separating "implementer who follows specs" from "reviewer who evaluates outcomes" creates productive friction: Sophia pushes back when Skipper's literal interpretation breaks editorial integrity; Skipper flags when Sophia's feedback is technically ambiguous. The pattern also surfaces decisions cleanly — when both agents agree they can't resolve something between themselves, you get an explicit ask rather than a silent compromise.

When to use this

Good fit:

• HTML editorial documents intended for reading (magazines, annual reports, longform essays)
• Documents where text content is authoritative and immutable (author submissions, finalized copy)
• Projects with embedded photos or visual assets that must be preserved
• Cases where you have design taste but want implementation off your plate
• Bilingual or multilingual editorial work (the pattern handles font pairing and language-aware typography)

Not a great fit:

• Single-page websites or marketing landing pages (the round-based iteration is overkill)
• Documents where text and design are being created together (use a single agent)
• Heavily interactive web apps (this is for read-oriented design)
• Projects where you need to author content, not just present existing content

Quick start

Option A — Use the skill (recommended for Claude Code users)

1. Clone or download this repo.
2. Copy skill/html-editorial-design/ into your Claude Code skills directory (typically ~/.claude/skills/ for user-level skills, or .claude/skills/ inside a specific project).
3. In any HTML editorial project, ask Claude Code: "Set up the html-editorial-design workflow for this project." The skill will create the agent files, the orchestration file, and walk you through the first round.

Option B — Copy the example project

1. Clone this repo.
2. Copy the example_project/ contents into your working folder.
3. Drop your HTML file in alongside CLAUDE.md.
4. Edit CLAUDE.md to point at your filename and describe your audience.
5. Open the folder in VS Code with the Claude Code extension. Type: "Read CLAUDE.md and start Round 1 of the design improvement workflow on [your-file.html]."

Both paths produce the same workflow. The skill version is reusable across many projects; the template version is a one-shot starter.

What's inside

html-editorial-design/
├── README.md                          ← you are here
├── LICENSE                            ← MIT
├── skill/
│   └── html-editorial-design/
│       ├── SKILL.md                   ← the skill definition
│       ├── agents/
│       │   ├── sophia.md              ← reviewer agent template
│       │   └── skipper.md             ← implementer agent template
│       └── reference/
│           ├── round_workflow.md      ← round-by-round operating manual
│           ├── prompt_templates.md    ← reusable prompts for each round type
│           ├── design_principles.md   ← editorial design reference
│           └── troubleshooting.md     ← common failures and fixes
├── example_project/
│   ├── CLAUDE.md                      ← project orchestration file
│   ├── .claude/
│   │   └── agents/
│   │       ├── sophia.md
│   │       └── skipper.md
│   ├── annual.html                    ← placeholder; replace with your HTML
│   └── sources/                       ← place author-submitted .docx files here
└── docs/
    ├── getting_started.md             ← detailed walkthrough
    ├── content_audit_workflow.md      ← how to verify text fidelity
    ├── pdf_export.md                  ← exporting the final HTML to PDF
    └── case_study.md                  ← a real-world example walkthrough

Design principles baked in

The skill's default review lens is editorial: it nudges toward restrained palettes, generous line-height, thoughtful photo treatment, varied section pacing, and bilingual-aware typography. Reference points: Harvard Magazine, Nature feature articles, top-tier university annual reports. If your project needs a different aesthetic (startup, fashion editorial, technical documentation), the agent definitions are easy to adapt — sophia.md has a "Design Principles" section you can override.

The constraint system

Three hard constraints run through every round:

1. Text is immutable — Skipper never edits, paraphrases, or "improves" any text content. Not even typos. (Typo-fix exceptions can be opted into per project.)
2. Photos are immutable — every <img> tag, every src, every base64-embedded image is preserved exactly. Style around photos changes; the photos themselves don't.
3. Sophia verifies, every round — text character count and <img> tag count are reported on every revision, so constraint violations get caught immediately rather than discovered later.

When you need to restore text from source documents (a paragraph got cut during the original HTML build, a phrase needs to be reverted), use the content audit workflow in docs/content_audit_workflow.md. It treats text changes as a separate authorized round with explicit per-essay instructions.

Contributing

This pattern was developed iteratively on a real annual report project across 19 rounds. There's a lot of room to extend it:

• Skills for adjacent document types (academic posters, conference proceedings, white papers)
• Additional reviewer agents for specialized lenses (accessibility audit, print-readiness audit, brand-compliance audit)
• Better integration with design tokens or design systems
• Print/PDF-specific workflows with @media print handling

Pull requests welcome. See CONTRIBUTING.md.

License

MIT — use, modify, and share freely.

Credits

Pattern developed during work on the OCAIR 2026 Annual Report. Documented and templated for general use.