# officeimo-conversion-operator

Adopt this skill: https://proskills.md/skills/other/evotecit-officeimo-agents-skills-officeimo-conversion-operator

Page: https://proskills.md/skills/other/evotecit-officeimo-agents-skills-officeimo-conversion-operator
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/officeimo-conversion-operator/SKILL.md
size: 2446
upstream: https://github.com/evotecit/officeimo/blob/master/.agents/skills/officeimo-conversion-operator/SKILL.md

````text
---
name: officeimo-conversion-operator
description: Use when contributing code that changes or validates OfficeIMO conversion behavior, especially DOCX/XLSX/PPTX/HTML/Markdown/PDF byte and stream APIs, browser-safe paths, or fidelity diagnostics. Prefer OfficeIMO core APIs first and keep hosts, websites, cmdlets, MCP tools, and demos thin.
---

# OfficeIMO Conversion Operator

Use this skill for OfficeIMO conversion work across Word, Excel, PowerPoint, Markdown, HTML, and PDF.

## Golden Path

1. Start by locating the owning reusable API.
   - Word behavior belongs under `OfficeIMO.Word*`.
   - Excel behavior belongs under `OfficeIMO.Excel*`.
   - PowerPoint behavior belongs under `OfficeIMO.PowerPoint*`.
   - Shared PDF behavior belongs in the PDF engine projects, not in a host wrapper.
2. Treat file paths as adapter concerns.
   - Prefer byte array and stream entrypoints for conversion APIs.
   - Keep browser, CLI, PowerShell, MCP, and website shells as orchestration only.
3. Validate real artifacts.
   - For PDF output, at minimum verify the returned bytes start with `%PDF`.
   - For browser work, validate inside a real Blazor WebAssembly runtime before calling it GitHub Pages-safe.
   - For fidelity work, keep a named fixture and record the expected known gap.
4. Separate platform limits from conversion defects.
   - Browser-safe means no Office automation, LibreOffice process, native graphics dependency, server filesystem dependency, or environment-only state.
   - Font coverage, Unicode embedding, large memory use, and startup size are conversion quality gaps even when the browser runtime works.
5. Keep public surfaces friendly.
   - Add simple options and presets at host layers only after the reusable OfficeIMO API already supports the behavior.
   - Avoid hidden environment-variable switches for behavior that should be an explicit option.

## Useful Checks

```powershell
dotnet build OfficeIMO.Word.Pdf\OfficeIMO.Word.Pdf.csproj -c Release -f net10.0
dotnet test OfficeIMO.Word.Tests\OfficeIMO.Word.Tests.csproj -c Release --filter "*SaveAsPdf*"
dotnet test OfficeIMO.Html.Tests\OfficeIMO.Html.Tests.csproj -c Release --filter "*Html*"
dotnet test OfficeIMO.Markdown.Tests\OfficeIMO.Markdown.Tests.csproj -c Release --filter "*Markdown*"
```

When the work targets GitHub Pages or OfficeIMO.com, pair these with the browser conversion proof described in `Docs/officeimo.blazor-wasm-conversion-proof.md`.
````

## File: README.md
upstream: https://github.com/evotecit/officeimo/blob/master/README.md

````text
# OfficeIMO

[![CI](https://github.com/EvotecIT/OfficeIMO/actions/workflows/dotnet-tests.yml/badge.svg?branch=master)](https://github.com/EvotecIT/OfficeIMO/actions/workflows/dotnet-tests.yml)
[![license](https://img.shields.io/github/license/EvotecIT/OfficeIMO.svg)](LICENSE)
[![Discord](https://img.shields.io/discord/508328927853281280?style=flat-square&label=discord%20chat)](https://evo.yt/discord)

OfficeIMO creates, edits, reads and converts Word, Excel, PowerPoint, PDF, Markdown and two dozen other document formats in .NET, without Microsoft Office or COM. New documents start from a theme, so a table, chart or slide looks finished without styling each element by hand.

PowerShell users get the same engines through [PSWriteOffice](PowerShell/PSWriteOffice/README.MD), which lives in this repository.

## Install

```sh
dotnet add package OfficeIMO
```

`OfficeIMO` brings Word, Excel, PowerPoint, PDF and Markdown, the conversions between them, `OfficeConverter` and the document reader. To keep a dependency small, reference only the [packages](#packages) you use.

## Quick start

A Word report, an Excel table with a chart and a PowerPoint deck from the same data, each also saved as PDF:

<!-- powerforge:code source="Build/DocumentationExamples/QuickStart/Program.cs" region="QuickStart" -->
```csharp
using OfficeIMO;
using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;
using OfficeIMO.PowerPoint;
using OfficeIMO.PowerPoint.Pdf;
using OfficeIMO.Word;
using OfficeIMO.Word.Pdf;

Sale[] sales = [new("North", 182_400m, 0.12), new("South", 141_900m, 0.08), new("West", 97_300m, -0.03)];

using (var report = WordDocument.Create("Sales.docx")) {
    report.AddHeading("Quarterly sales", level: 1);
    report.AddParagraph("Revenue by region for the third quarter.");
    report.AddTable(sales);
    report.AddChart(OfficeChartType.Column, sales, nameof(Sale.Region), nameof(Sale.Revenue));
    report.Save();
    report.SaveAsPdf("Sales.pdf");
}

using (var book = ExcelDocument.Create("Sales.xlsx", new ExcelCreateOptions { Theme = OfficeTheme.Modern })) {
    ExcelSheet sheet = book.AddSheet("Sales");
    sheet.AddTable(sales, new OfficeTableOptions { Name = "Sales" });
    sheet.AddChart(OfficeChartType.Column, sales, nameof(Sale.Region),
        new ExcelChartOptions { Title = "Revenue by region", Row = 2, Column = 6 }, nameof(Sale.Revenue));
    book.Save();
    book.SaveAsPdf("Sales-workbook.pdf");
}

using (var deck = PowerPointDocument.Create("Sales.pptx")) {
    deck.AddSlide().AddTitle("Quarterly sales");
    PowerPointSlide chartSlide = deck.AddSlide();
    chartSlide.AddTitle("Revenue by region");
    chartSlide.AddChart(OfficeChartType.Column, sales, nameof(Sale.Region), new PowerPointChartOptions {
        Left = OfficeLength.Centimeters(2.3), Top = OfficeLength.Centimeters(5.5),
        Width = OfficeLength.Centimeters(29), Height = OfficeLength.Centimeters(12)
    }, nameof(Sale.Revenue));
    deck.Save();
    deck.SaveAsPdf("Sales-deck.pdf");
}

record Sale(string Region, decimal Revenue, double Growth);
```
<!-- /powerforge:code -->

Every format follows the same shape:

| Job | API |
| --- | --- |
| Create, load and save | `{Format}Document.Create(path)`, `Load(path)`, `Save()`, `Save(path)`, `SaveAsync(stream)` |
| Add content | `AddHeading`, `AddParagraph`, `AddTable(rows)`, `AddChart(type, rows, category, values)`, `AddImage`; each returns what it created |
| Write another format | `doc.SaveAsPdf(path)`, `doc.SaveAsHtml(path)`; returns an `OfficeConversionReport` |
| Convert in memory | `doc.ToMarkdown()`, `markdown.ToWord()` |
| Convert files or folders | `OfficeConverter.Convert(input, output)`, `OfficeConverter.ConvertAsync(files, outputDirectory, target)` |
| Read for search or AI | `OfficeDocumentReader` from `OfficeIMO.Reader.All` |

Conversions report what the target could not carry. `report.HasLoss` and `report.ThrowIfLoss()` check it; `FailOnLoss` in the conversion options turns loss into an error.

### Themes

`OfficeTheme` carries the palette, fonts, type scale, table and chart styles. The built-in themes are `Modern` (the default), `Classic`, `Minimal`, `Boardroom` and `Dark`. Loading an existing document never restyles it.

Colors can name theme roles instead of literal values, so output follows the theme:

```csharp
using OfficeIMO;

OfficeColor brand = OfficeColor.Accent1;
OfficeColor alert = OfficeColor.Danger;
OfficeLength margin = OfficeLength.Centimeters(2.5);
```

### Convert files and folders

```csharp
using OfficeIMO;

OfficeConversionReport report = OfficeConverter.Convert("Sales.docx", "Sales-copy.pdf",
    new OfficeConversionOptions { FileConflictPolicy = OfficePublicationPolicy.Replace });
Console.WriteLine($"{report.Target}: {report.Diagnostics.Count} diagnostics");

OfficeBatchReport batch = await OfficeConverter.ConvertAsync(
    Directory.EnumerateFiles("Reports", "*.docx"),
    outputDirectory: "Pdf",
    target: OfficeDocumentFormat.Pdf,
    new OfficeBatchOptions { MaxParallelism = 4, ConflictPolicy = OfficePublicationPolicy.Replace });
Console.WriteLine($"{batch.Summary.Completed} converted, {batch.Summary.Failed} failed");
```

`OfficeConverter` refuses to replace an existing output unless the conflict policy says so. A batch reports every file and can resume an interrupted run from a checkpoint (`OfficeBatchOptions.ResumeFrom`, which needs the default `Fail` policy).

## Packages

Install a format package for that format alone. Conversion adapters are named `OfficeIMO.{Source}.{Target}` and bring only the two engines they join.

| Format | Package | Document type | Common adapters |
| --- | --- | --- | --- |
| Word `.docx`, `.doc` | [OfficeIMO.Word](OfficeIMO.Word/README.md) | `WordDocument` | `.Word.Pdf`, `.Word.Markdown`, `.Word.Html`, `.Word.Rtf`, `.Word.OpenDocument` |
| Excel `.xlsx`, `.xls` | [OfficeIMO.Excel](OfficeIMO.Excel/README.md) | `ExcelDocument` | `.Excel.Pdf`, `.Excel.Html`, `.Excel.Csv`, `.Excel.OpenDocument` |
| PowerPoint `.pptx`, `.ppt` | [OfficeIMO.PowerPoint](OfficeIMO.PowerPoint/README.md) | `PowerPointDocument` | `.PowerPoint.Pdf`, `.PowerPoint.Html`, `.PowerPoint.OpenDocument` |
| PDF | [OfficeIMO.Pdf](OfficeIMO.Pdf/README.md) | `PdfDocument` | `.Pdf.Word`, `.Pdf.Excel`, `.Pdf.PowerPoint`, `.Pdf.Ocr` |
| Markdown | [OfficeIMO.Markdown](OfficeIMO.Markdown/README.md) | `MarkdownDocument` | `.Markdown.Pdf`, `.Markdown.Html` |
| HTML | [OfficeIMO.Html](OfficeIMO.Html/README.md) | `HtmlDocument` | `.Html.Pdf`, `.Html.Rtf` |
| Visio `.vsdx` | [OfficeIMO.Visio](OfficeIMO.Visio/README.md) | `VisioDocument` | `.Visio.Pdf` |
| Project `.mpp`, `.xml` | [OfficeIMO.Project](OfficeIMO.Project/README.md) | `ProjectDocument` | |
| Access `.accdb`, `.mdb` | [OfficeIMO.Access](OfficeIMO.Access/README.md) | `AccessDocument` | |
| OneNote `.one` | [OfficeIMO.OneNote](OfficeIMO.OneNote/README.md) | `OneNoteSection` | `.OneNote.Markdown`, `.OneNote.Html`, `.OneNote.Pdf` |
| Email `.eml`, `.msg`, `.pst` | [OfficeIMO.Email](OfficeIMO.Email/README.md) | | `.Email.Html`, `.Email.Image` |
| RTF | [OfficeIMO.Rtf](OfficeIMO.Rtf/README.md) | `RtfDocument` | `.Rtf.Pdf`, `.Rtf.Markdown` |
| OpenDocument `.odt`, `.ods`, `.odp` | [OfficeIMO.OpenDocument](OfficeIMO.OpenDocument/README.md) | | `.OpenDocument.Odt.Pdf`, `.Ods.Pdf`, `.Odp.Pdf` |
| EPUB | [OfficeIMO.Epub](OfficeIMO.Epub/README.md) | `EpubDocument` | `.Epub.Image` |
| CSV | [OfficeIMO.CSV](OfficeIMO.CSV/README.md) | | `.Excel.Csv` |
| YAML | [OfficeIMO.Yaml](OfficeIMO.Yaml/README.md) | `YamlDocument` | |
| Apple Pages, Numbers, Keynote | [OfficeIMO.IWork](OfficeIMO.IWork/README.md) | | `.Word.IWork`, `.Excel.IWork`, `.PowerPoint.IWork` |
| AsciiDoc, LaTeX | [OfficeIMO.AsciiDoc](OfficeIMO.AsciiDoc/README.md), [OfficeIMO.Latex](OfficeIMO.Latex/README.md) | | `.Markdown`, `.Pdf` |
| Publisher, XPS, DjVu, CHM, DocBook, OPML | [OfficeIMO.Publisher](OfficeIMO.Publisher/README.md), [OfficeIMO.Xps](OfficeIMO.Xps/README.md), [OfficeIMO.DjVu](OfficeIMO.DjVu/README.md),
````
