Skip to content

xlang-ai/CUA-Gym / .claude/skills/libreoffice-writer

libreoffice-writer

Verified

How to programmatically create, modify, and verify LibreOffice Writer (.docx) files using Python python-docx. For setup-gen and reward-gen agents.

LibreOffice Writer — Python Manipulation Guide

This skill teaches setup-gen (create/modify docx) and reward-gen (read/verify docx) how to work with document files using pure Python code.

  • Library: python-docx
  • Install: pip3 install python-docx Pillow

0. GUI Startup on VM (for setup-gen)

After generating /home/user/<task_id>_initial.docx, setup-gen should open it in LibreOffice Writer for the GUI agent.

CRITICAL VM LIMIT: GUI launches must set DISPLAY=:0.

import os
import shlex
import subprocess
import time

def launch_gui(command: str, delay_sec: float = 1.0):
    env = os.environ.copy()
    env["DISPLAY"] = ":0"
    subprocess.Popen(
        shlex.split(command),
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        env=env,
    )
    time.sleep(delay_sec)

launch_gui('libreoffice --writer "/home/user/<task_id>_initial.docx"', delay_sec=2.0)

Guidelines:

  • Open initial artifact, never golden artifact.
  • Use non-blocking launch (Popen) and short delays.

1. Creating & Writing Files (setup-gen)

Basic Document

from docx import Document
from docx.shared import Pt, Inches, RGBColor, Emu
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_TAB_ALIGNMENT, WD_TAB_LEADER, WD_COLOR_INDEX
from docx.enum.section import WD_ORIENT, WD_SECTION_START
from docx.oxml.ns import qn
import shutil

doc = Document()
doc.add_heading("Title", level=0)
para = doc.add_paragraph("First paragraph.")
doc.add_paragraph("Bullet item", style="List Bullet")
doc.add_paragraph("Numbered item", style="List Number")
doc.save("/home/user/output.docx")

Font Formatting (Runs)

para = doc.add_paragraph()
run = para.add_run("Styled text")
run.bold = True
run.italic = True
run.underline = True
run.font.strike = True           # strikethrough
run.font.name = "Times New Roman"
run.font.size = Pt(14)
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00)

run_sub = para.add_run("2")
run_sub.font.subscript = True    # or .superscript = True

Paragraph Formatting

para = doc.add_paragraph("Centered")
para.paragraph_format.alignment = WD_PARAGRAPH_ALIGNMENT.CENTER  # LEFT, RIGHT, JUSTIFY
para.paragraph_format.line_spacing = 2.0      # 1.0=single, 1.5, 2.0=double
para.paragraph_format.space_before = Pt(12)
para.paragraph_format.space_after = Pt(6)
para.paragraph_format.left_indent = Inches(0.5)
para.paragraph_format.first_line_indent = Inches(0.25)
para.paragraph_format.page_break_before = True

Tab Stops

tab_stops = para.paragraph_format.tab_stops
tab_stops.add_tab_stop(Inches(2), WD_TAB_ALIGNMENT.LEFT)
tab_stops.add_tab_stop(Inches(3.5), WD_TAB_ALIGNMENT.CENTER)
tab_stops.add_tab_stop(Inches(6), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
para.add_run("Col1\tCol2\tCol3")

Tables

table = doc.add_table(rows=3, cols=4)
table.style = "Table Grid"
table.cell(0, 0).text = "Header"
# Formatted cell text
cell = table.cell(1, 0)
run = cell.paragraphs[0].add_run("Bold red")
run.bold = True
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00)
# Add row, merge cells
table.add_row().cells[0].text = "New row"
table.cell(0, 0).merge(table.cell(0, 1))

Images

doc.add_picture("/home/user/image.png", width=Inches(4))
# In a table cell
run = table.cell(1, 2).paragraphs[0].add_run()
run.add_picture("/home/user/image.png", width=Inches(1.5))

Page Breaks

doc.add_page_break()  # simplest
# Or via run
run = para.add_run()
br = run._element.makeelement(qn('w:br'), {qn('w:type'): 'page'})
run._element.append(br)

Headers, Footers & Page Numbers

section = doc.sections[0]
header = section.header
header.is_linked_to_previous = False
header.paragraphs[0].text = "Document Header"

footer = section.footer
footer.is_linked_to_previous = False
fp = footer.paragraphs[0]
fp.text = "Page "
# Page number field code
r1 = fp.add_run()
r1._element.append(r1._element.makeelement(qn('w:fldChar'), {qn('w:fldCharType'): 'begin'}))
r2 = fp.add_run()
instr = r2._element.makeelement(qn('w:instrText'), {})
instr.text = ' PAGE '
r2._element.append(instr)
r3 = fp.add_run()
r3._element.append(r3._element.makeelement(qn('w:fldChar'), {qn('w:fldCharType'): 'end'}))

Page Setup

section = doc.sections[0]
section.page_width = Inches(8.5)
section.page_height = Inches(11)
section.left_margin = Inches(1)
section.right_margin = Inches(1)
section.top_margin = Inches(1)
section.bottom_margin = Inches(1)
# Landscape
section.orientation = WD_ORIENT.LANDSCAPE
section.page_width, section.page_height = section.page_height, section.page_width

Highlighting

run = para.add_run("Highlighted")
run.font.highlight_color = WD_COLOR_INDEX.YELLOW  # GREEN, CYAN, PINK, RED, etc.
run.font.highlight_color = None  # remove

Modifying Existing Files

shutil.copy("/home/user/original.docx", "/home/user/modified.docx")  # ALWAYS copy first
doc = Document("/home/user/modified.docx")
for para in doc.paragraphs:
    for run in para.runs:
        run.font.name = "Calibri"
doc.save("/home/user/modified.docx")

2. Reading & Verifying Files (reward-gen)

Loading & Structure

from docx import Document
from docx.shared import Pt, RGBColor
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_TAB_ALIGNMENT

doc = Document("/path/to/file.docx")
num_paras = len(doc.paragraphs)
num_tables = len(doc.tables)
num_sections = len(doc.sections)

Reading Text & Font Properties

for para in doc.paragraphs:
    # para.text — full text (all runs concatenated)
    for run in para.runs:
        run.text                    # run text
        run.font.name               # "Arial" or None
        run.font.size               # EMU value; use .pt for float (e.g. 12.0)
        run.font.bold               # True / False / None (None=inherit)
        run.font.italic             # True / False / None
        run.font.underline          # True / False / None
        run.font.strike             # True / False / None (strikethrough)
        run.font.subscript          # True / False / None
        run.font.superscript        # True / False / None
        run.font.color.rgb          # RGBColor or None
        run.font.highlight_color    # WD_COLOR_INDEX or None

Verifying Paragraph Format

pf = para.paragraph_format
pf.alignment              # WD_PARAGRAPH_ALIGNMENT enum or None
pf.line_spacing           # float (1.0, 2.0) or Pt or None
pf.space_before           # Pt or None
pf.space_after            # Pt or None
pf.left_indent            # EMU or None
pf.first_line_indent      # EMU or None
pf.page_break_before      # True / False / None

Verifying Tab Stops

for ts in para.paragraph_format.tab_stops:
    # Filter defaults: skip CLEAR and LEFT+position=0
    if ts.alignment == WD_TAB_ALIGNMENT.CLEAR: continue
    if ts.alignment == WD_TAB_ALIGNMENT.LEFT and ts.position == 0: continue
    print(f"Alignment={ts.alignment}, Position={ts.position}")

Verifying Tables

for table in doc.tables:
    for i, row in enumerate(table.rows):
        for j, cell in enumerate(row.cells):
            text = cell.text.strip()
            for para in cell.paragraphs:
                for run in para.runs:
                    # run.font.bold, .color.rgb, etc.
                    pass

Verifying Images

from io import BytesIO
from PIL import Image

def extract_images(doc):
    images = []
    for rel in doc.part.rels.values():
        if "image" in rel.reltype:
            images.append(BytesIO(rel.target_part.blob))
    return images

# Check inline image in run via XML
has_image = 'graphicData' in run._element.xml

Verifying Page Breaks

def count_page_breaks(doc):
    ns = {'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'}
    count = 0
    for para in doc.paragraphs:
        for run in para.runs:
            for br in run.element.findall('.//w:br', ns):
                if br.attrib.get(f'{{{ns["w"]}}}type') == 'page':
                    count += 1
    return count

Verifying Headers, Footers & Page Numbers

section = doc.sections[0]
header_text = section.header.paragraphs[0].text if section.header.paragraphs else ""
footer_text = section.footer.paragraphs[0].text if section.footer.paragraphs else ""
has_page_num = any(c.isdigit() for c in footer_text)

Verifying Page Setup

s = doc.sections[0]
# s.page_width, s.page_height, s.left_margin, s.right_margin, s.top_margin, s.bottom_margin (EMU)
from docx.enum.section import WD_ORIENT
is_landscape = s.orientation == WD_ORIENT.LANDSCAPE

Verifying Highlighting & Strikethrough

# Highlight check
for run in para.runs:
    if run.font.highlight_color is not None:
        print(f"Highlighted: '{run.text}' color={run.font.highlight_color}")

# Strikethrough on last paragraph
last_para = doc.paragraphs[-1]
all_strike = all(run.font.strike for run in last_para.runs if run.text.strip())

Verifying Case Conversion

def has_uppercase(doc):
    for para in doc.paragraphs:
        for run in para.runs:
            if run.text.strip() and run.text.isupper(): return True
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for para in cell.paragraphs:
                    for run in para.runs:
                        if run.text.strip() and run.text.isupper(): return True
    return False

Verifying Colored Words in Tables

from math import sqrt

def color_distance(c1, c2):
    return sqrt(sum((a - b) ** 2 for a, b in zip(c1, c2)))

for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            for para in cell.paragraphs:
                for run in para.runs:
                    if run.text and run.font.color.rgb:
                        first = run.text[0].lower()
                        if first in 'aeiou':
                            assert color_distance(run.font.color.rgb, RGBColor(255,0,0)) < 50
                        else:
                            assert color_distance(run.font.color.rgb, RGBColor(0,0,255)) < 50

ODF (.odt) File Verification

from odf.opendocument import load
from odf.text import P, Span

odt_doc = load("/path/to/file.odt")
for para in odt_doc.getElementsByType(P):
    text_parts = []
    for node in para.childNodes:
        if node.nodeType == node.TEXT_NODE:
            text_parts.append(node.data)
        elif node.nodeType == node.ELEMENT_NODE and node.tagName == 'text:span':
            for child in node.childNodes:
                if child.nodeType == child.TEXT_NODE:
                    text_parts.append(child.data)

# Check ODT highlighting (background color in automatic styles)
for span in odt_doc.getElementsByType(Span):
    style_name = span.getAttribute('stylename')
    if style_name:
        for auto_style in odt_doc.automaticstyles.childNodes:
            if auto_style.getAttribute('name') == style_name:
                for prop in auto_style.childNodes:
                    if prop.getAttribute('backgroundcolor') == '#ffff00':
                        print("Yellow highlight found!")

Common Helpers for reward.py

import re

def compare_text(doc1, doc2, ignore_blanks=True):
    p1 = [p.text for p in doc1.paragraphs]
    p2 = [p.text for p in doc2.paragraphs]
    if ignore_blanks:
        return re.sub(r'\s+', ' ', '\n'.join(p1)).strip() == re.sub(r'\s+', ' ', '\n'.join(p2)).strip()
    return p1 == p2

def check_all_font_name(doc, expected):
    return all(run.font.name == expected for para in doc.paragraphs for run in para.runs if run.font.name)

def check_italic_size(doc, expected_pt):
    return all(run.font.size and run.font.size.pt == expected_pt
               for para in doc.paragraphs for run in para.runs if run.italic)

3. Bitter Lessons

  1. run.font.size is EMU, not points. run.font.size == 14 fails. Use run.font.size.pt == 14 or run.font.size == Pt(14).

  2. para.text concatenates runs, losing formatting. To check per-run formatting (bold word + normal), iterate para.runs. Never rely on para.text for style checks.

  3. None means "inherited" for font properties. run.font.bold is None means "inherit from style". If the style is bold, None means bold. Usually treat None as False, but be aware.

  4. Page breaks are inside runs, not paragraphs. Manual breaks are <w:br w:type="page"/> in run elements. Use XML parsing: run.element.findall('.//w:br', ns). Cannot detect via para.text.

  5. Highlighting differs between .docx and .odt. run.font.highlight_color works for .docx. ODT stores highlights in automatic styles as backgroundcolor. Need different code paths.

  6. Copy-then-modify for golden files. shutil.copy(initial, golden) then modify. Scratch files lack styles, numbering, and metadata causing comparison failures.

  7. Tab stop comparison must filter defaults. LibreOffice adds default LEFT@0 and CLEAR stops. Filter them out to avoid false mismatches.

  8. ignore_blanks=True collapses all whitespace. When paragraph structure (empty lines) matters, use ignore_blanks=False and compare paragraph-by-paragraph.

  9. Footer page numbers are field codes, not text. <w:fldChar> + <w:instrText> PAGE </w:instrText>. The .text property shows cached values. Check for digit presence, not exact number.

  10. doc.part.rels images include ALL images. Headers, footers, textboxes too. Not just body. Filter if needed.

  11. para.runs may miss hyperlink/field text. para.text includes all text, but ''.join(r.text for r in para.runs) may be shorter. Use para.text for full text comparison.

  12. Color comparison: use perceptual distance. The evaluator uses CIEDE2000 (Delta E) with threshold ~3.5 from skimage.color.deltaE_ciede2000. Simple RGB distance is imprecise.

  13. Equations are OLE objects. Detect with run.element.xpath('.//w:object'). No readable text via python-docx.

  14. Multiple gold files for tolerance. LibreOffice formatting varies by version/fonts. Provide 2-4 gold files with OR logic in reward scripts.

canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall