Turn an existing publication into a Postext project with a coding agent.

Many people come to Postext with a book that already exists: a textbook as a print PDF, a report in Word, a course in PowerPoint, a catalogue in InDesign, an EPUB. Porting it means two jobs:

Content: the enriched Markdown of every chapter, with its directives and microformats.
Design: a configuration manifest that reproduces the original's layout rules (page geometry, baseline grid, type, openers, running heads, boxes, floats, tables, parts).

An LLM can do much of this work, but only if it knows how Postext works. Postext Markdown is not CommonMark, and the configuration has traps that only show up when a page renders wrong. The postext-port skill packages that knowledge together with the tools we used to build every preset in the sandbox, so your agent can do the port properly.

It follows the open Agent Skills format, so it works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and many other agents.

#What the skill contains

A workflow:
1. agree the brief;
2. take an inventory of the source;
3. measure the design into a spec sheet;
4. scaffold the project;
5. extract the content;
6. curate it into Postext Markdown;
7. prepare fonts and images;
8. verify page by page;
9. package it.
References:
- the document format and the configuration manifest, both checked against the engine;
- the project (bundle) format;
- a playbook per source format;
- a design-analysis method;
- a catalogue of solved layout cases: parts with their own colours, chapter openers, verse, margin glosses, footnotes, floated/split/nested boxes, vector print masters, live-text figures, pictures in table cells, landscape tables, bilingual editions, and more.
Scripts (Python and Node), described in the next section.

#Scripts

Script	What it does
`inventory.py`	First look at any source: geometry, fonts, styles in use, media, pages that need OCR
`measure_layout.py`	Margins, columns, gutter and leading (the baseline grid) of a PDF
`pdf_extract.py`	PDF → draft chapters by type role (font/size/colour): reading order, paragraphs, de-hyphenation, bold/italic, super/subscripts, lists, captions
`pdf_figures.py`	Cuts figures out of a PDF: photos at native resolution, SVG previews, vector PDF print masters
`extract_tables.py`	PDF tables → Postext `TableModel`
`pandoc_to_postext.py`	DOCX, PPTX, ODT, EPUB, HTML, LaTeX, Markdown, JATS, DocBook → draft chapters, with Word styles mapped to callouts and paragraph styles
`idml_extract.py`	InDesign IDML → draft chapters by paragraph style, tables and anchored images
`fonts.py`, `images.py`, `convert_assets.py`	Instance, subset, scale and split fonts; convert images to sRGB, trim and join them; turn `.ai`/`.pdf` artwork into SVG
`preset_kit.py`	Scaffolds the project and its generator script, builds `preset.json`, packs the `.postext` file
`lint_project.py`	Catches everything the parser and loader silently get wrong
`render.mjs`	Lays the project (a folder or a `.postext` file) out headlessly with the real engine, prints warnings and writes the PDF
`compare_pages.py`	Places source and Postext pages side by side

#Installing it

#Any agent (skills.sh)

The skills CLI detects your agents and installs the skill for them:

npx skills add drnachio/postext --skill postext-port

Pick agents explicitly with -a, and install globally (every project) with -g:

npx skills add drnachio/postext --skill postext-port -a codex -a claude-code -g

The same skill is published by the website, so this works too:

npx skills add https://postext.dev

#Claude Code plugin

The Postext repository is also a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add drnachio/postext
/plugin install postext@postext

Or from a shell:

claude plugin marketplace add drnachio/postext

claude plugin install postext@postext

#Let the agent install it

You can ask your agent to do it, for example: "Install the Postext porting skill (npx skills add drnachio/postext --skill postext-port) and use it to port this PDF." Agents that read https://postext.dev/llms.txt find this page and the install command there.

#Tools the scripts use

python3 -m pip install pymupdf pillow fonttools brotli

brew install pandoc poppler

mkdir -p ~/.cache/postext-tools && cd ~/.cache/postext-tools && npm init -y && npm i postext postext-pdf react @pdf-lib/fontkit

Pandoc is needed for Word, PowerPoint, EPUB and HTML sources, and poppler for page images. The Node packages power the headless renderer (Node 22.15 or newer). Optional tools: ocrmypdf for scans, ImageMagick, and veraPDF for PDF/UA checks.

#Using it

Put the source files in your working folder and ask for the port. For example:

"Port chapters 1–3 of manual.pdf to Postext, reproducing its two-column layout, chapter openers and boxes."
"Convert course.docx into a Postext book. The styles 'Nota' and 'Actividad' are boxes."
"Turn deck.pptx into a Postext handout: slides become sections, speaker notes become the text."
"We have the InDesign package (IDML + print PDF) of this textbook. Build the Postext preset for chapter 1 in Spanish and English."

The agent follows the workflow:

Brief. It asks what it cannot infer: a faithful reproduction or a redesign, a sample chapter or the whole book, languages, print or screen, and the rights on the text, images and fonts.
Inventory and measurement. It reads the source and writes a spec sheet of measured facts: trim, margins, columns, leading, type roles, palette, openers, running heads, box families and placement habits.
Project. It scaffolds my-book/ with a build_preset.py generator that holds the spec as constants and produces preset.json.
Content. It extracts draft chapters with the right extractor, then curates them into Postext Markdown: callouts, paragraph styles, parts, heading attributes for openers, :ref citations, table and figure resources.
Verification. It lints the project, lays it out headlessly and compares it with the source page by page until page breaks, figures and boxes match.
Delivery. It packs my-book.postext.

Open the result in the Sandbox: Projects → Import .postext…. The import takes the chapters and wording of the sandbox's language. To work on a folder of projects in a local copy of Postext, set POSTEXT_PRIVATE_PRESETS_DIR (see Sandbox).

#Loading the result from code

The delivered file is not tied to the Sandbox. The postext package opens it with openBundle, lays the book out with buildBundle and renders it to canvas, HTML or PDF (see Bundles). A port can therefore feed a program directly. When that program's output needs adjusting, export it back to a .postext file with createBundle, fine-tune it in the Sandbox and load the corrected file again. The skill's headless render.mjs also accepts a packed .postext file as well as a project folder.

#What to expect

The extractors produce drafts; the agent curates them. Expect a review pass per chapter against the original pages. That review is where the quality comes from.
Config and Markdown only. The skill never changes the engine to fit one book. When Postext cannot express something, the agent picks the closest expression and lists it as a known gap.
Rights are your call. The agent asks before reproducing images or fonts whose licences are unclear. Licensed fonts are marked redistributable: false, so exported projects leave them out.
Fidelity where it matters. The goal is the same grid, type, openers, boxes, figure placement and page breaks on most pages (within one page per chapter), not identical line breaks.

#Where it lives

The skill is in the repository at plugins/postext/skills/postext-port. It covers every case met while building the presets in the sandbox, public and private. When a port hits a case it does not cover yet, please open an issue or a pull request that improves the skill, so the next port gets it for free.

Agent skill: port a publication to Postext