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.
Badge for your README
Markdown
[](/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
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)
- {
- "name": "brand-docs",
- "owner": { "name": "Ferdinando Bonsegna" },
- "plugins": [
- {
- "name": "brand-docs",
- "source": "./",
- "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.",
- "version": "0.10.1",
- "license": "MIT"
- }
- ]
- }
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)
- <div align="center">
- <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%" />
- <br/>
- # BrandDocs: AI On-Brand Document Generator for Word, PowerPoint & Excel
- **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.
- [](LICENSE)
- [](https://www.python.org/)
- [](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml)
- [](https://ferdinandobons.github.io/brand-docs/)
- [](https://github.com/ferdinandobons/brand-docs/releases/latest)
- [](#the-three-skills)
- [](#project-status)
- </div>
- ---
- ## What is BrandDocs?
- **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.
- > **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.
- ### At a glance
- | Question | Answer |
- |---|---|
- | **Input** | Existing company `.docx`, `.pptx`, or `.xlsx` templates |
- | **Output** | Same-format on-brand Word documents, PowerPoint decks, and Excel workbooks |
- | **Works with** | Claude Code, Codex, compatible AI agents, or the direct Python CLI |
- | **Best for** | Repeatable reports, decks, workbooks, proposals, memos, briefs, and internal document workflows |
- | **Privacy model** | Local-first; no cloud service is required, and real templates are git-ignored |
- | **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 |
- | **Current release** | [v0.10.1](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.10.1) alpha |
- ---
- ## The three skills
- | Skill | Format | Generates |
- |---|---|---|
- | **`brand-docx`** | Word `.docx` | reports, letters and memos in the template's structural order |
- | **`brand-pptx`** | PowerPoint `.pptx` | decks from the template's real masters & layouts, with native charts, diagrams & merged tables |
- | **`brand-xlsx`** | Excel `.xlsx` | workbooks: named-region fills with **formulas preserved** and brand number formats |
- 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).
- **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.
- **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.
- **Published only after proof:** generation preflights the profile and shell, writes
- to a same-directory temporary file, and atomically publishes the requested output
- only after deterministic QA passes. XLSX also preserves formulas and raw worksheet
- extensions such as sparkline groups; extension loss is a blocking QA error.
- ---
- ## Prerequisites
- BrandDocs runs locally and needs a few things installed **before first use**:
- - **Python 3.10-3.13** plus the packages in [`requirements.txt`](requirements.txt) (`python-docx`, `python-pptx`, `openpyxl`, `lxml`, `Pillow`):
- ```bash
- pip install -r requirements.txt
- ```
- - **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:
- ```bash
- bash scripts/setup_visual_qa.sh
- ```
- Generation still runs without them (it degrades gracefully to deterministic-only QA, level L0), but install them so the visual gate stays on.
- 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)**.
- ---
- ## Installation
- 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:
- ```text
- /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:
- ```bash
- 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)**.
- ---
- ## Quick start
- **With an AI agent** (the intended experience). Describe what you want and attach a template:
- > "Use this company Word template and write a report on the history of Napoleon."
- 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.
- **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.
- **Direct CLI** (the engine, for tests & debugging). No template at hand? Try the
- shipped synthetic example: `examples/templates/branddocs_template.docx` (also
- `.pptx` / `.xlsx`).
- ```bash
- # 1) Extract the brand from a template into a reusable Brand Profile
- python scripts/brandkit/cli.py extract --name <your_company> --template examples/templates/branddocs_template.docx --scope project
- # 2) Verify the profile (fails if a role points at a missing artifact)
- python scripts/brandkit/cli.py verify --name <your_company> --scope auto --qa auto
- # 3) Generate a new on-brand document from structured content
- python scripts/brandkit/cli.py generate --name <your_company> --input idoc.json --output out.docx --scope auto --qa auto
- ```
- The input (`idoc.json`) is an **IntermediateDocument** of brand-agnostic typed blocks (no styles, colors or fonts); the Brand Profile resolves all of that.
- ---
- ## Project status
- **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).
- ## Website & discovery
- - Public website: [ferdinandobons.github.io/brand-docs](https://ferdinandobons.github.io/brand-docs/)
- - Full documentation: [`documentation/`](documentation/)
- ## Changelog
- Latest release: [v0.10.1](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.10.1). See [CHANGELOG.md](CHANGELOG.md).
- ## License, citation & acknowledgements
- - This project's own code is **[MIT](LICENSE)** © 2026 Ferdinando Bonsegna.
- - Self-contained: the OOXML engine is re-implemented from scratch; it does **not** vendor any proprietary or third-party Office tooling. See [`NOTICE`](NOTICE).
- - Citing BrandDocs in academic or organizational work → [`CITATION.cff`](CITATION.cff).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.