branded-report
Turn a Markdown report into a polished, consistently branded document in HTML, PDF, and DOCX — all three from one source and one theme, so every report looks identical. The theme (brand colors, fonts,
SKILL.mdskills/documents/branded-report/SKILL.md
GitHubBranded 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:
Works withpython EXTRACT --template "Brand.pptx" --out theme.json --logo-dir ./assets.pptx,.potx,.thmx,.dotx,.docx,.xlsx— anything carrying an OOXML theme. Then opentheme.jsonand pick the rightlogo(a dark/colored logo for white pages; DOCX needs a PNG/JPG logo vialogo_raster— SVG embeds only in HTML/PDF). - From an image, a website, or a PDF (when there is no Office theme) —
extract_theme_visual.pyrenders the source and samples its brand colors (heuristic; review the result):
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.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 - 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
- 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).
- Run the script with the user's theme and the cover fields. Parse the JSON output.
- 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).
- 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
logois an SVG; Word can't embed SVG. Pointlogoat 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 fromskill.install.json).