Agent skill

Word Document Builder

by spinabot in spinabot/brigade

Creates and edits Word documents along four paths of rising capability, from a quick tool to the docx library, an OOXML round-trip and pandoc, then verifies the file.

MITAuto-check passedDocuments & Office

Install Word Document Builder

skills CLI
$ npx skills add spinabot/brigade --skill docx -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install spinabot/brigade docx --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/spinabot/brigade.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/docx .claude/skills/docx && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
docx
GitHub stars
11k
Token cost
~2.1k tokens
SKILL.md length
578 words
Files
1
Skills in repo
11
Repo updated
First seen
Licence
MIT

At a glance

Creates and edits Word documents along four paths of rising capability, from a quick tool to the docx library, an OOXML round-trip and pandoc, then verifies the file.

  • Works in 2 steps: write a file gen.cjs. → Run: brigade exec-node gen.cjs
  • Drafting a report, proposal, letter or memo as a .docx file
  • SKILL.md covers Path 1 — quick structured doc…, Path 2 — full power: script…, Path 3 — fill / redline an… and Path 4 — Markdown → branded…, plus 2 more sections
  • Calls pandoc and soffice

What it does

Four paths are on offer, and the lightest one that fits the need is chosen. A simple make_document tool handles headings, paragraphs, bullets, a basic table and an image. Richer documents (custom styles, multi-level lists, merged or shaded cells, headers and footers, a table of contents, hyperlinks, footnotes, tracked changes, comments) are written as a CommonJS script using the docx library and run with brigade exec-node.

To fill or redline an existing branded file without losing its theme, the agent unzips the .docx, edits the XML and rezips it, with the edit_document tool as the first choice for plain placeholder swaps. Markdown can optionally be converted through pandoc using a corporate template. The skill insists that no document is called done until the result has been opened or validated at least once.

When your agent uses it

  • Drafting a report, proposal, letter or memo as a .docx file
  • Filling a branded Word template without disturbing its styling
  • Redlining a contract with tracked changes and comments
  • Building a document with a table of contents and footnotes

Example prompts

  • “Draft a two-page project proposal as a Word document with a table of contents.”
  • “Fill in the company template at ./templates/offer-letter.docx with the new hire's details.”
  • “Redline ./contracts/vendor-agreement.docx with tracked changes and comments on the payment terms.”

Requirements

  • The Brigade agent runtime with its make_document, edit_document and exec-node tools
  • pandoc, optional, for template-based Markdown conversion

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. write a file gen.cjs.
  2. Run: brigade exec-node gen.cjs

What it can do on your machine

Read from SKILL.md and the folder at commit 4c2a18f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • pandoc
    • soffice

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Word Document Builder loads about 2.1k tokens when it runs. Until then it costs about 97 tokens; SKILL.md has 578 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~97
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from spinabot/brigade at commit 4c2a18f, republished under its MIT licence (© spinabot). 578 words, ~2,059 tokens.

Download SKILL.mdSave it as .claude/skills/docx/SKILL.md (or your agent's skills folder).
name
docx
description
Create and edit Microsoft Word (.docx) documents to a professional standard — reports, proposals, contracts, letters, memos — with custom styles, multi-level lists, styled/merged tables, headers/footers, table of contents, hyperlinks, footnotes, tracked changes and comments. Use when the user asks Brigade to make, write, draft, fill, redline, or edit a Word document or .docx file.

docx — professional Word documents

Pick the lightest path that meets the need. Never declare a document done without opening/validating the result at least once (see Verify).

NeedPath
Simple structured doc (headings, paragraphs, bullets, a basic table, an image)Path 1 — make_document tool
Anything richer (custom styles, numbered/multi-level lists, merged/shaded table cells, headers/footers, TOC, hyperlinks, footnotes, inline bold/italic/color, tracked changes, comments)Path 2 — script the docx library via brigade exec-node
Fill / redline an EXISTING branded .docx without disturbing its stylingPath 3 — OOXML round-trip
Markdown → branded Word inheriting a corporate templatePath 4 — pandoc (optional)

Path 1 — quick structured doc (make_document tool)

make_document(format="docx", content={ title, sections:[{heading, level, paragraphs, bullets, table:{rows}, image:{path}}] })

Good for a fast first draft. It is deliberately limited (single-level bullets, string-only tables, no inline formatting). The moment you need more, go to Path 2 — don't fight the schema.

Path 2 — full power: script the docx library

Brigade bundles the docx library (dolanmiu/docx). Write a CommonJS script and run it with brigade exec-node, which makes Brigade's bundled libraries require()-able from anywhere (no install):

  1. write a file gen.cjs.
  2. Run: brigade exec-node gen.cjs
js
// gen.cjs — illustrative; adapt to the content
const fs = require("node:fs");
const {
  Document, Packer, Paragraph, TextRun, HeadingLevel, AlignmentType,
  Table, TableRow, TableCell, WidthType, BorderStyle, ShadingType,
  LevelFormat, Header, Footer, PageNumber, TableOfContents, ExternalHyperlink,
} = require("docx");

const doc = new Document({
  styles: { default: { document: { run: { font: "Calibri", size: 22 } } },     // size is half-points (22 = 11pt)
    paragraphStyles: [{ id: "Body", name: "Body", run: { size: 22 }, paragraph: { spacing: { after: 160 } } }] },
  numbering: { config: [{ reference: "nums", levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.START }] }] },
  sections: [{
    properties: { page: { size: { width: 12240, height: 15840 } } },           // US Letter, in DXA (1440 = 1 inch)
    headers: { default: new Header({ children: [new Paragraph("Acme Corp — Confidential")] }) },
    footers: { default: new Footer({ children: [new Paragraph({ children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })] })] }) },
    children: [
      new Paragraph({ text: "Q3 Business Review", heading: HeadingLevel.TITLE }),
      new TableOfContents("Contents", { hyperlink: true, headingStyleRange: "1-3" }),
      new Paragraph({ text: "Summary", heading: HeadingLevel.HEADING_1 }),
      new Paragraph({ children: [ new TextRun("Revenue was "), new TextRun({ text: "$1.2M", bold: true }), new TextRun(" — up 18%.") ] }),
      new Paragraph({ text: "First item", numbering: { reference: "nums", level: 0 } }),
      new Paragraph({ children: [ new ExternalHyperlink({ children: [new TextRun({ text: "Full data", style: "Hyperlink" })], link: "https://example.com" }) ] }),
      new Table({
        columnWidths: [4680, 4680],                                            // DXA, sum = content width
        rows: [
          new TableRow({ tableHeader: true, children: ["Metric","Value"].map((t) =>
            new TableCell({ width: { size: 4680, type: WidthType.DXA }, shading: { type: ShadingType.CLEAR, fill: "D9E2F3" },
              children: [new Paragraph({ children: [new TextRun({ text: t, bold: true })] })] })) }),
          new TableRow({ children: ["Revenue","$1.2M"].map((t) =>
            new TableCell({ width: { size: 4680, type: WidthType.DXA }, children: [new Paragraph(t)] })) }),
        ],
      }),
    ],
  }],
});
Packer.toBuffer(doc).then((buf) => { fs.writeFileSync(process.argv[2] || "out.docx", buf); console.log("wrote", process.argv[2] || "out.docx"); });

The docx library also supports: footnotes (FootnoteReferenceRun + footnotes), comments, tracked changes (InsertedTextRun/DeletedTextRun with author/date), multi-section layouts, page breaks, columns, internal bookmarks, and images inside table cells. Read its API as needed — anything Word can express, this can author.

Path 3 — fill / redline an EXISTING .docx (highest fidelity)

To fill a branded company template or surgically edit a real document without regenerating it (which would drop the theme), use the OOXML round-trip — unzip, edit the XML, rezip. For plain placeholder/text swaps the edit_document tool (replace_text / fill_template / append) already does exactly this and is the first choice.

For edits beyond text, script it via brigade exec-node with fflate:

js
// edit.cjs — unzip → edit word/document.xml → rezip (styles/headers/theme untouched)
const fs = require("node:fs");
const { unzipSync, zipSync, strToU8, strFromU8 } = require("fflate");
const zip = unzipSync(fs.readFileSync(process.argv[2]));
let xml = strFromU8(zip["word/document.xml"]);
xml = xml.replaceAll("{{client}}", "Acme Corp");          // fill placeholders in <w:t> runs
zip["word/document.xml"] = strToU8(xml);
fs.writeFileSync(process.argv[3], zipSync(zip));

Rules for raw OOXML edits:

  • Safe: replacing text inside <w:t>; pointing a run/paragraph at an already-defined styleId; appending <w:p>/<w:r> that reference existing styles.
  • Do NOT add a new part (image, hyperlink target, header) by hand — that also needs [Content_Types].xml + the matching _rels/*.rels updated atomically, or Word reports corruption. For those, regenerate with the docx library instead.
  • Tracked changes are <w:ins>/<w:del> as siblings of <w:r> (never inside a run); copy the original <w:rPr> into the change runs; keep edits minimal so an "accept all" yields exactly the intended text. Author yourself as "Brigade".
Show full SKILL.md (204 more words)Show less

Path 4 — Markdown → branded Word (optional, needs pandoc)

For long prose where the brand styling lives in a corporate .docx, if pandoc is installed it inherits every style/margin/header:

bash
command -v pandoc >/dev/null 2>&1 && pandoc input.md --reference-doc=brand-template.docx -o out.docx

Detect first; else fall back to Path 2. pandoc is GPL — a separate program shelled out to, never bundled.

Conventions that make output professional

  • Page size is explicit — US Letter 12240×15840 DXA (1440 DXA = 1"); landscape = portrait dims + orientation flip.
  • Tables: give both columnWidths (table) and per-cell width in WidthType.DXA (PERCENTAGE breaks some viewers), summing to content width; ShadingType.CLEAR (never SOLID → black boxes); add cell margins; never use a table as a horizontal rule (use a paragraph bottom border).
  • Lists: real numbering config for numbered/multi-level lists; never paste literal "1." / "•" characters.
  • Prefer bullets + tables over walls of text; one TITLE, then HEADING_1..3 with proper outline levels (required for a working TOC).
  • Use typographic quotes (' ' " ") and en/em dashes.

Verify (required)

After writing, confirm the file exists and is non-trivial. If LibreOffice is available, render to PDF and look at it — fix overflow/placeholder leftovers, then re-verify:

bash
command -v soffice >/dev/null 2>&1 && soffice --headless --convert-to pdf out.docx

TOC/page-number fields show blank until Word (or a soffice convert) recalculates them — note this to the user if you can't run the convert. Never declare success without at least one look-and-fix pass.

© spinabot, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/docx of spinabot/brigade.

Open the folder on GitHubat commit 4c2a18f

Compare with similar skills

Word Document Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Word Document Builder compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Word Document Builder this skillspinabot/brigade11k—~2.1kAutomated safety check: PassMIT
Word Document Reader and WriterHKUDS/DeepTutor41k—~2.5kAutomated safety check: PassApache-2.0
BiSheng DOCX Builderdataelement/bisheng12k—~2.6kAutomated safety check: PassApache-2.0
Pandoc DOCX TemplateAchuan-2/pandoc_docx_template1.1k—~1kAutomated safety check: PassNone
DOCX ToolkitXiaomiMiMo/MiMo-Code14k—~2.4kAutomated safety check: PassApache-2.0
Markdown to Word Convertercat-xierluo/SuitAgent206—~559Automated safety check: PassMIT

Similar skills

  • Reads, creates and edits Word .docx files with python-docx, and drops to raw OOXML for tracked changes, comments and byte-exact edits.

    41k GitHub stars~2.5k tokensUpdated 3 days ago
    Documents & OfficeAuto-check passed
  • BiSheng DOCX Builder

    dataelement/bisheng

    Builds or edits Word .docx documents inside BiSheng's code executor with python-docx, handling Chinese fonts, tables of contents, page numbers and official-document layout.

    12k GitHub stars~2.6k tokensUpdated 6 days ago
    Documents & OfficeAuto-check passed
  • Pandoc DOCX Template

    Achuan-2/pandoc_docx_template

    A skill your agent uses when converting Markdown to Word DOCX or DOCX back to Markdown with Pandoc, especially when the output should use the bundled Chinese Word reference templates, heading…

    1.1k GitHub stars~1k tokensUpdated 3 mo ago
    Documents & OfficeAuto-check passed
  • DOCX Toolkit

    XiaomiMiMo/MiMo-Code

    Produces, edits and reads Microsoft Word files through python-docx and lxml, with a decision table for picking the lightest workflow for a given task.

    14k GitHub stars~2.4k tokensUpdated 4 days ago
    Documents & OfficeAuto-check passed
  • Markdown to Word Converter

    cat-xierluo/SuitAgent

    Converts Markdown files into Word documents formatted to Chinese typesetting conventions, with presets for academic, legal, report and book layouts.

    206 GitHub stars~559 tokensUpdated 1 mo ago
    Documents & OfficeAuto-check passed
  • Industry Bid Document Writer

    Get00/BiaoShu-SKILL

    Converts a tender document into Markdown, extracts scoring criteria and requirements, then drafts an industry-formatted technical bid as a Word file.

    167 GitHub stars~4.6k tokensUpdated 13 days ago
    Documents & OfficeAuto-check passed

More from spinabot/brigade

All 11 skills in this repo
  • Canvas Display

    spinabot/brigade

    Shows HTML content such as games, dashboards, visualizations and demos on a connected Brigade node's canvas, using a local canvas host server and a node bridge.

    11k GitHub stars~1.4k tokensUpdated 4 days ago
    Auto-check passed
  • Writes HTML compositions with a GSAP timeline that the render_video tool turns into deterministic MP4 videos from data, text or layouts.

    11k GitHub stars~1.6k tokensUpdated 4 days ago
    Auto-check passed
  • Diagnoses why a Brigade companion app can't pair or connect, by first identifying the real node-to-gateway route and then fixing auth.

    11k GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed
  • OAuth Account Setup

    spinabot/brigade

    Connects an OAuth 2.0 account such as Gmail with the built-in oauth_authorize tool: an authorization link, automatic code capture and sealed token storage.

    11k GitHub stars~878 tokensUpdated 4 days ago
    Auto-check passed
  • Brigade PDF Toolkit

    spinabot/brigade

    Creates and edits PDFs in Brigade through four paths: a quick content tool, an edit tool for forms and merging, a pdf-lib script for full control, and HTML-to-PDF for styled layouts.

    11k GitHub stars~1.3k tokensUpdated 4 days ago
    Auto-check passed
  • Share Skills

    spinabot/brigade

    Explains how a skill folder should be laid out and bundled as a tar archive for sharing, with a checklist covering name, description and eligibility keys.

    11k GitHub stars~759 tokensUpdated 4 days ago
    Auto-check passed

Questions about Word Document Builder

What does Word Document Builder do?

Creates and edits Word documents along four paths of rising capability, from a quick tool to the docx library, an OOXML round-trip and pandoc, then verifies the file. Four paths are on offer, and the lightest one that fits the need is chosen. A simple make_document tool handles headings, paragraphs, bullets, a basic table and an image.

When should I use Word Document Builder?

Word Document Builder fits situations like: drafting a report, proposal, letter or memo as a .docx file; filling a branded Word template without disturbing its styling; redlining a contract with tracked changes and comments; building a document with a table of contents and footnotes.

How do I install Word Document Builder in Claude Code?

Run `npx skills add spinabot/brigade --skill docx -a claude-code`. Or copy the skill folder (skills/docx in spinabot/brigade) into .claude/skills/docx in your project. Claude Code loads it when a task matches its description.

How do I install Word Document Builder in Codex?

Run `npx skills add spinabot/brigade --skill docx -a codex`. Or copy the skill folder (skills/docx in spinabot/brigade) into .agents/skills/docx in your project. Codex loads it when a task matches its description.

Can I use Word Document Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add spinabot/brigade --skill docx -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/docx, .gemini/skills/docx, .github/skills/docx and .opencode/skills/docx in your project.

What does Word Document Builder need to run?

Going by SKILL.md and its folder, Word Document Builder needs the command-line tools its instructions call (pandoc and soffice). Our summary lists: The Brigade agent runtime with its make_document, edit_document and exec-node tools; pandoc, optional, for template-based Markdown conversion.

Does Word Document Builder access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Word Document Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Word Document Builder use?

Word Document Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Word Document Builder use?

About 2.1k tokens (SKILL.md is roughly 8.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Word Document Builder?

Skills that share tags, products or a category with Word Document Builder: Word Document Reader and Writer (HKUDS/DeepTutor, 41k stars), BiSheng DOCX Builder (dataelement/bisheng, 12k stars), Pandoc DOCX Template (Achuan-2/pandoc_docx_template, 1.1k stars) and DOCX Toolkit (XiaomiMiMo/MiMo-Code, 14k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Word Document Builder?

spinabot (a GitHub organization) maintains it in spinabot/brigade, which has 11,276 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 3, 2026.

Source: spinabot/brigade on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.