Agent Skill

Agent skill: port a publication to Postext

Install the postext-port skill in Claude Code, Codex or any agent and let it turn a PDF, Word, PowerPoint, EPUB, InDesign or HTML source into a Postext project that follows the original layout

Generated from docs/skill-en.mdx (updated 2026-10-09). Read it on postext.dev, where it is also available in Spanish, Catalan, Portuguese, French, German, Italian, Chinese, Japanese and Arabic. To change this page, edit the MDX and run pnpm wiki in apps/web.

In short

This page is for people who already have a book or document in another format, such as PDF, Word or InDesign, and want to move it into Postext. An AI helper, called an agent, can do most of the work if you give it a small add-on called a skill. The skill teaches the agent how to copy the text and rebuild the design of the original. The page explains how to install it, what to ask for and how to check the result. A video of about five minutes shows every step.

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.

Watch the tutorial

Five minutes, no code: prepare the folder, bring the vector originals, add a reference PDF, ask the agent, and check the result in the sandbox.

Convert your publication to Postext with an AI agent · Watch the tutorial · 5:12

Transcript. Everything the narrator says, with a description of what appears on screen.

• 0:00 · On screen: Title card: the Postext logo, the kicker “Tutorial · 5 steps” and the title “Turn your publication into Postext with an AI agent. No code.”
• 0:03 · On screen: “Your publication already exists.” Three pages set by Postext, a book, a manual and a magazine, drop in one by one, labelled InDesign (IDML), Word (DOCX) and PDF. They gather on the left, a dashed gold arrow runs through an “AI agent” badge and a file icon named my-book.postext appears, under “An agent turns it into Postext. Five steps. A few well-written requests.” · Narration: You already have a publication: a book, a manual, a magazine. It lives in InDesign, in Word, or in a PDF. In this tutorial, an AI agent will turn it into Postext for you. No code: just five steps and a few well-written requests.
• 0:23 · On screen: “The plan”: five numbered cards appear as each step is named: 01 Prepare the folder, 02 Bring the vector originals, 03 Add a reference, 04 Ask the agent, 05 Check in the sandbox. · Narration: Here's the plan: prepare the folder, bring the original artwork, add a reference, ask the agent, and check the result.
• 0:33 · On screen: Step 01, the folder: “One project, one folder.” A large folder, my-book/, floats among ten loose files such as MinionPro-Regular.otf, cover.jpg, fig-2-1.ai, chapter-01.docx, map.svg, book.idml and chart.pdf. A window opens on the folder tree and each file flies into its subfolder as it is named: reference.pdf (how it must look, step 03), fonts/ (Minion Pro, Myriad…, .otf .ttf .woff2), images/ (photos, .jpg .png), artwork/ (vector originals, .ai .svg .pdf) and text/ (Word, InDesign IDML…). · Narration: Step one: put everything in a single folder on your computer. One project, one folder. Inside, give each kind of material its own subfolder: the fonts, the images, the illustrations, and the text files.
• 0:50 · On screen: The fonts/ row is highlighted and a card headed “Fonts” shows a large “Aa”, the styles Regular, Italic and Bold, the formats OTF, TTF and WOFF2, and the note “Only the fonts you include can be used.” Then “The tidier the folder, the less it guesses.”, while each subfolder in the tree gets a tick. · Narration: Don't forget the fonts. They give the design its voice, and the agent can only use the ones you include. The tidier the folder, the less the agent has to guess.
• 1:03 · On screen: Step 02, vector originals: “Bring the originals.” A diagram, a chart and a map are drawn as line art with their anchor points showing, and three file icons appear: .ai Illustrator, .svg SVG and .pdf PDF. · Narration: Step two: if your illustrations are vector graphics, like diagrams, charts or maps, find the original files: Illustrator, SVG, or PDF.
• 1:14 · On screen: Two panels show the same figure, a diagram in which Manuscript and Template both point to Pages, captioned “Fig. 2.1 Content and design meet.” On the left, “Cut from the PDF: a photo of the drawing” turns blurred and blocky as the view zooms in; on the right, “The original: the drawing itself” stays sharp. The left panel fades, the labels of the original are retyped in Spanish (Manuscrito, Plantilla, Páginas), crop marks frame it, and three ticks read “Sharp at any size”, “Labels are live text” and “Print master → press”. · Narration: A figure cut out of the finished PDF is little more than a photo of the drawing. The original is the drawing itself. With it, the agent rebuilds each figure: sharp at any size, with its labels still as real text, ready to be translated. And for print, the original goes to press untouched.
• 1:37 · On screen: Step 03, the reference: “Show how it should look.” In the folder tree, reference.pdf is highlighted and tagged “In the root”; a page flies out of it and becomes a large two-column book page marked reference.pdf. · Narration: Step three is essential: in the root of the folder, include a file that shows clearly how the finished product should look. A PDF is ideal.
• 1:47 · On screen: Measurements appear over the page: column outlines, a 9 mm gutter, a 20 mm margin, labels for the heading (Fraunces 28 pt), the body (Lora 9.4/13.6 pt) and a box (tinted, 1 rule), and baselines with 13.6 pt leading. A file, spec-sheet.md, fills in: page 210 × 280 mm; margins 24 · 20 · 22 · 20 mm, mirrored; 2 columns, gutter 9 mm; baseline grid 13.6 pt; body Lora 9.4 / 13.6 pt, justified; headings Fraunces 28 pt · Geist; openers with a 101 mm colour band; boxes with a tint and a left rule. Then the word “Guess” is struck through and “Measure.” lights up in gold. · Narration: The agent reads the design from those pages. It measures margins, columns, fonts and spacing, and writes them down as layout rules. Without a reference, it would have to guess. With one, it measures.
• 2:03 · On screen: Step 04, the agent: “Ask for it in plain words.” A window titled “Agent · ~/my-book” opens beside the badges Claude Code, Codex and “or any other agent”. A message from YOU types out: “Install the Postext skill: npx skills add drnachio/postext --skill postext-port”, and the agent answers “✓ Skill installed: postext-port”. A card for the postext-port skill lists “A proven workflow”, “Everything about Postext” and “Tools to check its own work”. · Narration: Step four: open your agent, Claude Code, Codex or whichever you use, in that folder, and ask it to install the Postext skill. A skill is a package of expert know-how. This one teaches the agent how to bring a publication into Postext, and gives it the tools to check its own work.
• 2:24 · On screen: The next request types out: “Use the postext-port skill to convert this book to Postext. The design is in reference.pdf, the fonts are in fonts/ and the original illustrations are in artwork/: use them instead of cutting figures out of the PDF. Start with chapter 1 only, and show me the spec sheet before you build it.” Beside it, reference.pdf, fonts/ and artwork/ light up in the folder tree as the prompt names them, and a card reading “Ch. 1” pops up. · Narration: Then ask for what you want, in plain words. Tell it where the reference, the fonts and the originals are, and ask it to start with a single chapter.
• 2:37 · On screen: A grid of twelve dimmed book pages; the first is outlined in gold. A circular arrow counts polishing rounds on it until a tick appears, then the other eleven light up. Below: Sample chapter → Polish → Extend. · Narration: If the content is long, start with a sample chapter. Polish it until it's perfect, and only then extend it to the rest.
• 2:46 · On screen: The agent asks “Faithful copy or redesign?”, “Which languages?” and “Print, screen, or both?”. A checklist runs through Take inventory, Measure the design, Extract the text, Fonts and images, Compare page by page and Pack the file, and the file my-book.postext appears. A third request types out: “Chapter 1 is approved. Convert the remaining chapters with the same design, compare each one with reference.pdf, and pack everything into a single .postext file.” The agent replies “✓ 12 chapters · 0 warnings · my-book.postext”. · Narration: The agent will ask a few questions: a faithful copy or a redesign, which languages, print or screen. Then it measures, extracts, assembles and checks. And it hands you a Postext file. Once the sample is right, extending it to the whole book is just one more request.
• 3:14 · On screen: Step 05, the sandbox: “Check it, page by page.” A browser window types the address postext.dev/sandbox. The pointer clicks Books in the side bar, then New, then “Open a .postext file…”; the file flies in, “My book, 12 chapters · 184 pages” appears at the top of the list and its first pages open in the Canvas view; the view tabs read Canvas, HTML, PDF, Folio and EPUB 3. · Narration: Step five: open the Postext sandbox at postext.dev. In Books, choose New, and open your file.
• 3:24 · On screen: The reference page and the Postext page stand side by side, labelled Reference and Postext, and a gold line scans down both. The Checks panel opens with a badge of 3 and lists Widow (p. 4), Loose line (p. 7) and Figure does not fit (p. 9); red boxes mark each problem on the Postext page. · Narration: Go through it page by page, next to your reference. The Checks panel points out problems for you: widows, loose lines, figures that don't fit.
• 3:35 · On screen: Two rows of page wireframes, “Reference · PDF” and “Postext · reflowed”. In the reflowed row a figure travels from the first page to the top of the second, and a dashed line links its two positions. Text: “Same rules, not the same pages. The content flows: a figure or a page break may land elsewhere.” Then an equals sign joins each pair of pages under “What must match”: Margins and baseline grid, Typography, Figure and box styles, Clean pages: no widows, even columns. A red panel marked ≠ reads “Hand-made craft decisions: not rules, so they can’t set changing content”. · Narration: One thing to keep in mind: the pages don't need to be identical to your PDF. Postext has learned the layout rules, and your content now flows, so a figure or a page break may land somewhere else. What should match is the quality: the same production values. When we lay out by hand, we make small craft decisions that aren't rules. And only rules can set content that keeps changing.
• 4:03 · On screen: The agent window returns with a fourth request: “In the sandbox, chapter 2, page 7: the “Remember” box is split across two columns, and the running head is missing. Checks shows 3 loose lines. Fix it and pack the file again.” A screenshot is attached, screenshot-ch2-p7.png. Then a loop between Sandbox (check) and Agent (fix) runs through rounds 1 to 3 while the warning count drops from 3 to 0, and ends with a tick and “Exactly right.” · Narration: Then tell the agent what you see, as precisely as you can: the chapter, the page, and what's wrong. A screenshot helps. Open the new version, check again, and repeat. Each round gets closer, until it's exactly right.
• 4:23 · On screen: “Not just a Postext version.” The my-book.postext file splits in two along a gold line. On the left, Content (what it says): chapters/en/02-the-cell.md, with the heading “The cell”, a sentence citing figure fig-cell and a “remember” callout. On the right, Form (how it looks): a template deduced from your original, with page 210 × 280 mm mirrored, 2 columns with a 9 mm gutter, body Lora 9.4/13.6 justified, numbered Fraunces headings, “remember” boxes with tint and rule, and figures floated to the column top. · Narration: And this is the best part: you haven't just made a Postext version of your content. You've separated content from form. The text lives in clean chapters. The design lives in a template, with layout rules deduced from your original.
• 4:39 · On screen: Chips light up for Correct, Extend and Translate above a row of book pages: a line is highlighted and a shimmer crosses the pages, two more pages slide in, and the pages flip over to the Spanish edition. A request types out: “Add a Spanish edition: translate the chapters, captions and diagram labels, and keep the same design.” Caption: “Same rules. New content. Pages set themselves.” Then “One file, the whole book.”: a .postext icon branches to a page with crop marks (Print-ready PDF), an e-reader with the text reflowed to its screen (EPUB e-book), a browser window (Web reader) and a pair of pages (Every page, set). · Narration: So when your content changes, when you correct it, extend it or translate it, you don't have to think about the layout. Postext sets it again, following the same rules. One file for the whole book: a print-ready PDF, an EPUB e-book, a reader for the web, and pages that set themselves.
• 5:03 · On screen: End card: the Postext logo, the tagline “The programmable typesetter for the web”, postext.dev, a pill reading “The prompts from this video are in the description ↓” and the footer “Open source · MIT · github.com/drnachio/postext”. · Narration: Postext. Open source, at postext.dev. You'll find the example prompts in the description.

Also on YouTube: watch it there or in the Postext playlist.

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, back-of-book indexes, floated/split/nested boxes, vector print masters, live-text figures, pictures in table cells, landscape tables, bilingual editions, and more;
  • Chinese books, set horizontally or vertically and bound on the right: what to ask in the brief (script, region, direction, binding), how to measure a grid of characters, how to read vertical PDFs, InDesign ruby and warichu, Word's East Asian layout and right-to-left EPUBs, and how to cut CJK fonts to the book (see Chinese layout);
  • Japanese books, vertical bunko and tankōbon novels bound on the right or horizontal technical books: the locale that switches on the Japanese rules (ja, never a Chinese tag), what to ask (direction, grid, furigana, notes, the edition's orthography), how to measure the type area in characters and lines, furigana and bōten markup, Aozora Bunko texts converted with aozora.py, scans of public-domain editions from the National Diet Library, and Japanese fonts cut with their kana and vertical forms (see Japanese layout);
  • Arabic books, modern or classical and vocalised, set right to left and bound on the right: the locale that turns the book, what to ask (region and digits, vocalisation, verse, contents at the end), how to measure a mirrored page, how to read Arabic from PDFs, Word and Wikisource, poems as :::verse, notes «(١)» per page, and Arabic fonts cut with their joining tables (see Arabic layout);
  • comics, manga and newspaper strips: the split that cuts a page into panels, the panel pictures with their speaker anchors and safe areas, one script per language that the engine letters (balloons, captions, sound effects), right-to-left manga and Arabic editions, and how to port from text-free art plus translations, from lettered scans or from a script with generated art (see Comics);
  • the printed object: how to read the paper, binding, covers and spine of the source and set them as the folio settings that the Folio viewer shows, checked by the linter.
• 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; for a PDF printed as PDF/X, its output condition and bleed with the print settings that reproduce them.
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; ruby, tate-chu-yoko, emphasis marks and warichu become :ruby, :tcy, :dots and :warichu, and vertical stories and a right-to-left binding are reported
aozora.py	Aozora Bunko text (a CP932 zip or .txt) → Postext Markdown: furigana, bōten and side lines, headings with their indents, 字下げ and 地付き blocks as paragraph styles, page breaks, 外字 resolved through JIS X 0213, kanbun marks; it returns the credits block and a report of what it could not express
index_marks.py	Rebuilds a printed back-of-book index as :index marks: reads the index pages of the PDF, finds each term on its page and marks the same words in the chapters
comic_panels.py	Measures comic pages: finds the panels by the paper between them, writes the split expression (left to right or right to left, slanted gutters included), the gutters and the frame, cuts one picture per panel and prints the :::page skeletons; lays a grid over the pictures to read speaker anchors and safe areas, and draws them back to check them
fonts.py, images.py, convert_assets.py	Instance, subset, scale and split fonts (a Chinese or Japanese face cut to the book's characters keeps its vertical forms and metrics, an Arabic one its joining forms and tatweel); 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, and lints the configuration: text of the book typed into design elements, where the configuration should hold only the design, and a configuration too large for the Sandbox
lint_project.py	Catches everything the parser and loader silently get wrong, and, for Chinese, Japanese and Korean text, the characters the bundled fonts cannot set; for Japanese text, kana under a Chinese locale, Chinese faces or settings, Aozora notation left in the chapters and kanji index entries without a reading; for Arabic text, a missing Arabic locale, Latin-only or unjoined faces, letter-spacing, forced hyphenation and italic emphasis; in comics, split expressions that do not parse, panels that do not match the cells, unknown pictures and balloon or panel styles, malformed speaker anchors, lettering faces the project does not bundle, and editions whose pages differ
render.mjs	Lays the project (a folder or a .postext file) out headlessly with the real engine, reading its configuration as the Sandbox does, and prints warnings. With --jpeg it paints the pages you ask for (--pages 12-15) as JPEG files with the engine's own canvas renderer, in a second or two, so the agent looks at its pages without building a PDF; --out writes the PDF. A book set up for print gets PREFLIGHT lines (low-resolution pictures, thin rules, small text in several inks, ink over the limit, text near the trim), and its PDF is separated through the ICC output profile.
compare_pages.py	Places source and Postext pages side by side, from the render's PDF or its folder of JPEGs

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 postext-citeproc react @pdf-lib/fontkit @napi-rs/canvas

Pandoc is needed for Word, PowerPoint, EPUB and HTML sources, and poppler for the source's page images. The Node packages power the headless renderer (Node 22.15 or newer); @napi-rs/canvas is a prebuilt canvas that lets it paint the book's pages straight to JPEG. Optional tools: ocrmypdf for scans, ImageMagick, and veraPDF for PDF/UA checks.

The work loop runs on the command line, one self-contained executable with nothing to install: the agent keeps the project unpacked and leaves postext build --watch running on the pages it is working on, so every change shows up as a JPEG about a second later, even in a long book. The Node packages are optional: they run render.mjs, which adds the Sandbox's extra checks. Both lay the book out with bodyText.shapingLanguage: 'host', whatever its configuration says, so a line can break at another word than in the Sandbox (see Differences from the Sandbox).

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:

1. 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.
2. 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. It classifies every page as running text or as a composed page (boxes, labels and maps at set places); when more than a third are composed, it asks whether you want the identical layout or text you can edit and translate.
3. Project. It scaffolds my-book/ with a build_preset.py generator that holds the spec as constants and produces preset.json.
4. 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.
5. Verification. It lints the project and leaves postext build --watch running on the unpacked project: it changes a chapter or a setting, looks at the page's JPEG, repainted about a second later, and changes again until page breaks, figures and boxes match the source page by page. At each milestone it runs the full checks (postext check and the linter). The PDF is built for the print checks, not for every look.
6. Delivery. It sets the book's paper, binding and covers for the Folio viewer and packs my-book.postext.

Open the result in the Sandbox: Books → New → Open a .postext file…. 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.
• The text stays in the Markdown. The configuration holds the design and every word of the book is in the chapters, so a correction or a translation is an edit to Markdown. Composed pages are set with boxes pinned to their place, page pictures without text and SVG figures with live labels. When Postext cannot express something without typing text into the configuration, the agent stops, writes the gap as an issue draft and asks you. The skill never changes the engine to fit one book.
• One book file for every language. A translation is a set of chapters in the same .postext file, with its own captions and figure labels, checked with postext check in each language.
• 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.