branded-report

Branded Report

Generates HTML, PDF, and DOCX from a single Markdown file and a single theme, so a series of reports always looks the same. The agent supplies the content (Markdown) and the cover metadata; the script does the rendering. Deterministic — no LLM is called.

SCRIPT = this skill's scripts/build_report.py. Theme extraction = scripts/extract_theme.py. The theme schema and styling details are in REFERENCE.md.

The theme (do this once per brand)

The look is driven by a small theme.json (colors, fonts, logo, organization). Get one by:

• From an Office template (most accurate) — reads the real color scheme + fonts:

  python EXTRACT --template "Brand.pptx" --out theme.json --logo-dir ./assets
  

  Works with .pptx, .potx, .thmx, .dotx, .docx, .xlsx — anything carrying an OOXML theme. Then open theme.json and pick the right logo (a dark/colored logo for white pages; DOCX needs a PNG/JPG logo via logo_raster — SVG embeds only in HTML/PDF).
• From an image, a website, or a PDF (when there is no Office theme) — extract_theme_visual.py renders the source and samples its brand colors (heuristic; review the result):

  python VISUAL --image brand.png  --out theme.json
  python VISUAL --url https://acme.example --out theme.json --logo-dir ./assets   # + logo + org + fonts
  python VISUAL --pdf branded.pdf --page 1 --out theme.json
  

  A PDF or image of an already-branded document gives accurate colors; a website yields its on-screen palette + logo to tune. See REFERENCE.md for the reliability notes.
• Or hand-write it from theme.example.json.

The theme file is organization-specific — keep it local (alongside the user's documents), not in this repo. The skill ships only the neutral theme.example.json.

Generate the report

python SCRIPT --input report.md --theme theme.json \
    --formats html,pdf,docx --output-dir out --name my-report \
    --title "Report title" --subtitle "Subtitle" \
    --meta "**Date:** 2026-06-12" --meta "**Author:** ..." \
    --footer-note "Confidential" --json

Flag	Meaning
--input	Markdown source (headings, bold, lists, tables, code, > quotes, ---)
--theme	The brand theme JSON (omit for a neutral default theme)
--formats	Any of html,pdf,docx (default all three)
--output-dir / --name	Where, and the base filename (default: input stem)
--title / --subtitle	Cover page (omit --title to skip the cover entirely)
--meta	A cover metadata line; repeatable. **Label:** renders the label bold
--footer-note	Small note at the bottom of the cover
--json	Print a machine-readable {status, outputs} summary

What you (the agent) do

1. Write or assemble the report as Markdown (use the structure the report needs — headings map to the branded section bands, tables and code blocks are styled).
2. Run the script with the user's theme and the cover fields. Parse the JSON output.
3. Report which files were produced and where. If PDF was skipped, say why (no headless browser found) and offer the HTML (the user can Print-to-PDF from a browser).
4. Keep the same theme + title conventions across a report series so output is uniform.

Errors & fallbacks

• PDF skipped → no Chrome/Edge/Chromium found. HTML and DOCX still produced; install a browser or open the HTML and print to PDF.
• DOCX logo missing → the theme's logo is an SVG; Word can't embed SVG. Point logo at a PNG/JPG (or the organization name is used as a text wordmark on the DOCX cover).
• ModuleNotFoundError → pip install markdown python-docx beautifulsoup4 (the repo installer does this from skill.install.json).