Skip to content
Back to search

brand-docs

BrandDocs is a set of agent skills that learn your existing Word, PowerPoint and Excel templates and generate new on-brand documents from them. Unlike generic AI document generators, it preserves brand, structure, styles and formulas by construction. Built for Claude Code, Codex and compatible AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ferdinandobons-brand-docs/badge.svg)](/listings/ferdinandobons-brand-docs)

HTML

<a href="/listings/ferdinandobons-brand-docs"><img src="/api/listings/ferdinandobons-brand-docs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The three skills share one Python engine (`scripts/brandkit/`), so install the **whole repository** (copying a single skill folder on its own won't work). After either install below, set up the [prerequisites](#prerequisites) so the engine can run, then verify with `python scripts/brandkit/cli.py doctor`.

Claude Code

The plugin loads all three skills plus the shared engine together:

/plugin marketplace add ferdinandobons/brand-docs
/plugin install brand-docs@brand-docs

Codex (and other agents)

Clone the repo and symlink the three skills into your Codex skills directory, so each skill's engine in `scripts/brandkit/` travels with it:

git clone https://github.com/ferdinandobons/brand-docs.git ~/.codex/brand-docs
cd ~/.codex/brand-docs && python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
mkdir -p ~/.codex/skills
for s in brand-docx brand-pptx brand-xlsx; do ln -s ~/.codex/brand-docs/skills/$s ~/.codex/skills/$s; done

Restart or reload the agent if the skills don't appear immediately.

> Git-submodule install and updating instructions are in **[documentation/INSTALLATION.md](documentation/INSTALLATION.md)**.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "brand-docs",
  3. "owner": { "name": "Ferdinando Bonsegna" },
  4. "plugins": [
  5. {
  6. "name": "brand-docs",
  7. "source": "./",
  8. "description": "AI on-brand document generator: turn a company's Word, PowerPoint or Excel template into unlimited on-brand .docx/.pptx/.xlsx. Learn the template once into a reusable Brand Profile, then generate faithful documents - off-brand output impossible by construction. Skills: brand-docx, brand-pptx, brand-xlsx.",
  9. "version": "0.10.1",
  10. "license": "MIT"
  11. }
  12. ]
  13. }
README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/hero.webp" alt="BrandDocs workflow: one real Word, PowerPoint or Excel template is extracted into a verified, reusable Brand Profile, which then generates unlimited on-brand DOCX, PPTX and XLSX documents in the same format" width="100%" />
  3. <br/>
  4. # BrandDocs: AI On-Brand Document Generator for Word, PowerPoint & Excel
  5. **BrandDocs is a set of agent skills that learn your existing Word, PowerPoint and Excel templates and generate new on-brand documents from them.** Unlike generic AI document generators, it preserves **brand, structure, styles and formulas by construction**. Built for Claude Code, Codex and compatible AI agents.
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-3B82F6.svg)](LICENSE)
  7. [![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-3776AB.svg)](https://www.python.org/)
  8. [![CI](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml)
  9. [![Website](https://img.shields.io/badge/website-GitHub%20Pages-16A34A.svg)](https://ferdinandobons.github.io/brand-docs/)
  10. [![Latest release](https://img.shields.io/github/v/release/ferdinandobons/brand-docs?label=latest%20release)](https://github.com/ferdinandobons/brand-docs/releases/latest)
  11. [![Skills](https://img.shields.io/badge/skills-docx%20·%20pptx%20·%20xlsx-6EA8FE.svg)](#the-three-skills)
  12. [![Status: alpha](https://img.shields.io/badge/status-alpha-F59E0B.svg)](#project-status)
  13. </div>
  14. ---
  15. ## What is BrandDocs?
  16. **BrandDocs** is an open-source **agent-skill bundle** that learns a company's existing Office templates and generates new on-brand documents from them. Point it at one branded `.docx`, `.pptx`, or `.xlsx`; it **extracts** the brand (theme colors and fonts, named styles, the document's *structure*, layouts, cover anchors, logos and tables) into a portable **Brand Profile**. From then on, every document it **generates** is built *from the original template shell* and uses *only* the artifacts the template actually defines. Each format stays in its own lane: there is no cross-format conversion.
  17. > **The core guarantee: off-brand output is impossible by construction.** No generator ever writes a literal style name, hex color, or font: those live only in the Brand Profile, and `verify` refuses a profile that points at anything the template doesn't contain.
  18. ### At a glance
  19. | Question | Answer |
  20. |---|---|
  21. | **Input** | Existing company `.docx`, `.pptx`, or `.xlsx` templates |
  22. | **Output** | Same-format on-brand Word documents, PowerPoint decks, and Excel workbooks |
  23. | **Works with** | Claude Code, Codex, compatible AI agents, or the direct Python CLI |
  24. | **Best for** | Repeatable reports, decks, workbooks, proposals, memos, briefs, and internal document workflows |
  25. | **Privacy model** | Local-first; no cloud service is required, and real templates are git-ignored |
  26. | **Speed** | First run on a new template: up to ~15 min end to end (extract + model comprehension + visual QA); every later document from the saved profile: seconds |
  27. | **Current release** | [v0.10.1](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.10.1) alpha |
  28. ---
  29. ## The three skills
  30. | Skill | Format | Generates |
  31. |---|---|---|
  32. | **`brand-docx`** | Word `.docx` | reports, letters and memos in the template's structural order |
  33. | **`brand-pptx`** | PowerPoint `.pptx` | decks from the template's real masters & layouts, with native charts, diagrams & merged tables |
  34. | **`brand-xlsx`** | Excel `.xlsx` | workbooks: named-region fills with **formulas preserved** and brand number formats |
  35. All three share one engine and expose the same verbs: **`extract` → `comprehend` *(optional, model-driven)* → `verify` → `generate`**, plus the learning verbs **`learn` / `propose-overrides` / `refine`** that fold QA findings and user feedback back into the profile. Details → [documentation/SKILLS.md](documentation/SKILLS.md).
  36. **Several templates, one brand?** `extract --blend` folds a second same-format template into a saved profile at the value-fact level: it fills gaps and corroborates agreements, the primary template wins every conflict, and the brand guarantee is untouched because artifact pointers never cross templates. `compare-profiles` reports brand drift (theme colors, fonts, off-theme usage) between any two saved profiles and exits non-zero on drift, so it can gate brand coherence in CI.
  37. **Two-phase by design:** the deterministic engine works with **no model at all** (extract / verify / generate, fully offline); the model-assisted verbs sit ON TOP and can only NAME captured facts - every proposal is validated fail-closed, so the brand guarantee never depends on a model being right.
  38. **Published only after proof:** generation preflights the profile and shell, writes
  39. to a same-directory temporary file, and atomically publishes the requested output
  40. only after deterministic QA passes. XLSX also preserves formulas and raw worksheet
  41. extensions such as sparkline groups; extension loss is a blocking QA error.
  42. ---
  43. ## Prerequisites
  44. BrandDocs runs locally and needs a few things installed **before first use**:
  45. - **Python 3.10-3.13** plus the packages in [`requirements.txt`](requirements.txt) (`python-docx`, `python-pptx`, `openpyxl`, `lxml`, `Pillow`):
  46. ```bash
  47. pip install -r requirements.txt
  48. ```
  49. - **Visual QA tools (keep the visual gate on):** the render-based **visual QA gate runs by default** and catches layout problems the deterministic checks can't (text overflow, blank pages, clipping, stale demo text). It needs LibreOffice + Poppler (Tesseract is optional, for OCR). Install them with one auto-detecting command:
  50. ```bash
  51. bash scripts/setup_visual_qa.sh
  52. ```
  53. Generation still runs without them (it degrades gracefully to deterministic-only QA, level L0), but install them so the visual gate stays on.
  54. Check what's present at any time with `python scripts/brandkit/cli.py doctor`. Per-OS commands and the full setup → **[documentation/INSTALLATION.md](documentation/INSTALLATION.md)**.
  55. ---
  56. ## Installation
  57. The three skills share one Python engine (`scripts/brandkit/`), so install the **whole repository** (copying a single skill folder on its own won't work). After either install below, set up the [prerequisites](#prerequisites) so the engine can run, then verify with `python scripts/brandkit/cli.py doctor`.
  58. ### Claude Code
  59. The plugin loads all three skills plus the shared engine together:
  60. ```text
  61. /plugin marketplace add ferdinandobons/brand-docs
  62. /plugin install brand-docs@brand-docs
  63. ```
  64. ### Codex (and other agents)
  65. Clone the repo and symlink the three skills into your Codex skills directory, so each skill's engine in `scripts/brandkit/` travels with it:
  66. ```bash
  67. git clone https://github.com/ferdinandobons/brand-docs.git ~/.codex/brand-docs
  68. cd ~/.codex/brand-docs && python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
  69. mkdir -p ~/.codex/skills
  70. for s in brand-docx brand-pptx brand-xlsx; do ln -s ~/.codex/brand-docs/skills/$s ~/.codex/skills/$s; done
  71. ```
  72. Restart or reload the agent if the skills don't appear immediately.
  73. > Git-submodule install and updating instructions are in **[documentation/INSTALLATION.md](documentation/INSTALLATION.md)**.
  74. ---
  75. ## Quick start
  76. **With an AI agent** (the intended experience). Describe what you want and attach a template:
  77. > "Use this company Word template and write a report on the history of Napoleon."
  78. The agent activates `brand-docx`, extracts (or reuses) a Brand Profile, fills the template shell in its structural order, runs QA, and returns the file. PowerPoint (`brand-pptx`) and Excel (`brand-xlsx`) work the same way.
  79. **How long does it take?** The FIRST run on a new template is the slow one: extraction, the optional model comprehension, content authoring and the visual QA gate (plus any repair round) can take up to ~15 minutes end to end with an AI agent. Every later document from the saved profile takes seconds. Still a fraction of formatting the document by hand, and you get a faithful file instead of an approximate one.
  80. **Direct CLI** (the engine, for tests & debugging). No template at hand? Try the
  81. shipped synthetic example: `examples/templates/branddocs_template.docx` (also
  82. `.pptx` / `.xlsx`).
  83. ```bash
  84. # 1) Extract the brand from a template into a reusable Brand Profile
  85. python scripts/brandkit/cli.py extract --name <your_company> --template examples/templates/branddocs_template.docx --scope project
  86. # 2) Verify the profile (fails if a role points at a missing artifact)
  87. python scripts/brandkit/cli.py verify --name <your_company> --scope auto --qa auto
  88. # 3) Generate a new on-brand document from structured content
  89. python scripts/brandkit/cli.py generate --name <your_company> --input idoc.json --output out.docx --scope auto --qa auto
  90. ```
  91. The input (`idoc.json`) is an **IntermediateDocument** of brand-agnostic typed blocks (no styles, colors or fonts); the Brand Profile resolves all of that.
  92. ---
  93. ## Project status
  94. **Alpha, maturing.** Stability is per format: **Word (`brand-docx`) is robust** - the reference implementation, verified end-to-end on real templates with a 900+ test suite, three QA lanes and frozen byte-identity anchors; **PowerPoint and Excel share the engine** and are catching up to docx parity. The profile schema (1.2.0) is frozen and additive: profiles keep working across releases. Full status table → [documentation/SKILLS.md](documentation/SKILLS.md#project-status).
  95. ## Website & discovery
  96. - Public website: [ferdinandobons.github.io/brand-docs](https://ferdinandobons.github.io/brand-docs/)
  97. - Full documentation: [`documentation/`](documentation/)
  98. ## Changelog
  99. Latest release: [v0.10.1](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.10.1). See [CHANGELOG.md](CHANGELOG.md).
  100. ## License, citation & acknowledgements
  101. - This project's own code is **[MIT](LICENSE)** © 2026 Ferdinando Bonsegna.
  102. - Self-contained: the OOXML engine is re-implemented from scratch; it does **not** vendor any proprietary or third-party Office tooling. See [`NOTICE`](NOTICE).
  103. - Citing BrandDocs in academic or organizational work → [`CITATION.cff`](CITATION.cff).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.