Skip to content
Get packs

Guide · Agent skill

How to use the PPTX Importer Dev Guide agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The PPTX Importer Dev Guide is an agent skill for developers who maintain the .pptx to JSON converter (packages/@openmaic/importer) inside the OpenMAIC repository. After you install it, your agent knows the package's layered architecture, the OOXML pitfalls that caused past bugs, the rules for changing the shared output type protocol, and which files are high-risk to edit. This guide explains what the skill does, how to install it, how to ask for help in plain language, and what to check before you trust its output.

PPTX Importer Dev GuideTHU-MAIC/OpenMAIC · MIT

Quick start

  1. 1Download the ZIP. Get the skill ZIP from the skill page on this site.
  2. 2Unzip into a skills folder. Place it in ~/.claude/skills/ for all projects, or in the project's .claude/skills/ folder for one project.
  3. 3Check out OpenMAIC. Clone the OpenMAIC repository so the skill's references to DESIGN.md and packages/@openmaic/importer resolve.
  4. 4Install the requirements. Make sure Node.js, tsx and jszip are available, and have a .pptx file that reproduces the problem.
  5. 5Ask for a specific fix. Describe the symptom, the deck and the file you suspect, then ask the agent to follow the before and after JSON workflow.

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder of instructions that an AI coding agent loads when a task matches it. This one is written for maintaining the PPTX importer, which parses a PowerPoint file into structured JSON for downstream renderers such as PPTist.

The skill's main instruction file is SKILL.md. It tells the agent to read DESIGN.md first, then follows a documented workflow for bug fixes: unzip the deck, dump JSON before and after a change, and diff the two results. It also lists the layer rules (parser, model, serializer, adapter, shapes, utils), the rule that src/adapter/types.ts is a protocol that must not break existing fields, and the commit message conventions.

  • Knows the pipeline: ZipParser, then model, then serializer, then adapter, producing Output with slides, themeColors and size.
  • Recalls known OOXML traps, such as grpFill on group children and an explicit noFill line overriding lnRef.
  • Flags high-risk files like groupSerializer.ts, shapeSerializer.ts, imageSerializer.ts, presets.ts and parser/units.ts before you edit them.

How do you install the PPTX Importer skill?

Download the ZIP from the skill page on this site. Unzip it into one of two locations. For a personal install available in every project, use ~/.claude/skills/. For a skill that only applies to one project, put it in that project's .claude/skills/ folder.

If you use the Claude apps instead, you can upload the skill in Settings, then Capabilities, then Skills. Either way, the skill is only useful if you also have the OpenMAIC repository checked out, because many of its instructions point to files inside that repository.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings, then Capabilities, then Skills, then upload the skill

What do you need before the skill is useful?

The skill assumes a working development setup. The listed requirements are Node.js, tsx (used to run the TypeScript scripts), and jszip (used by the structure extraction script). You also need an input .pptx file to test with, and a checkout of the OpenMAIC repository, since the skill refers to DESIGN.md, iterate-prompt.md and other packages.

The skill runs scripts in your repository, so the agent needs permission to run commands in your terminal.

  • Node.js
  • tsx, for running scripts/transvert.ts
  • jszip, used by scripts/extract-pptx-structure.js
  • A sample .pptx file that shows the bug
  • The OpenMAIC repository checkout

How do you ask the agent to use the skill?

You do not need a special command. Describe the converter problem in plain language and name the deck or the symptom. The agent should match the request to the skill because it concerns the PPTX importer's source code.

Good requests name the package, the symptom, and the file you have. Vague requests like make slides look better will match the wrong task, because this skill is about converter code, not slide design.

  • Fix the importer bug where the Logo on slide 2 shows extra hollow circles in my test deck.
  • The photo on my slide should be a circle but the converter outputs a square. Trace it through the importer.
  • Before I change shapeSerializer.ts, follow the standard bug-fix workflow and give me a before and after JSON diff.
  • Check whether my change to src/adapter/types.ts follows the protocol rules.
npx tsx scripts/transvert.ts /path/to.pptx ./out.json

What does the standard bug-fix workflow look like?

The skill's workflow has four steps. First, unzip the deck and read the source XML with the extraction script. Second, generate JSON before you change anything. Third, make the code change. Fourth, generate JSON again and diff the two files.

The skill also advises checking layoutElements, not only elements, when debugging. Logos, footers and master decorations often live in layoutElements. It also says to rerun with a new version label when parsing changes, so you do not mix results from older runs.

  • Look at layoutElements, not only elements, when a decoration seems to be missing or duplicated.
  • Trace the value to the right layer: wrong numbers suggest a serializer, wrong node types suggest model/Slide.ts, and wrong colours suggest StyleResolver and color.ts.
node scripts/extract-pptx-structure.js ./xxx.pptx ./out npx tsx scripts/transvert.ts ./xxx.pptx ./before.json npx tsx scripts/transvert.ts ./xxx.pptx ./after.json

What safety points should you know about?

The skill runs scripts, so review what the agent is about to execute. The listed scripts read a .pptx file you provide and write JSON or extracted XML to an output path you choose. The listing says the skill does not use the network.

The skill also sets repository hygiene rules. Files such as *.pptx, slides.json, out/ and dist/ are in .gitignore, but you should still run git status before committing. The src1/ folder is a read-only reference implementation, and the skill says not to modify or build it.

  • Scripts run in your terminal, so check commands before approving them.
  • Input is a .pptx you supply; output goes to paths you name.
  • Run git status before committing to avoid including test decks or generated output.
  • Do not edit src1/; it is reference-only.

What people use it for

  • Tracking down why a group of shapes renders with extra copies, using the grpFill rule and layoutElements.
  • Fixing a photo clip that should be circular but comes out rectangular, by checking custGeom versus prstGeom handling.
  • Reviewing a commit that touches adapter/types.ts to confirm new fields are optional and documented.
  • Producing a before and after JSON diff for a pull request that changes a serializer.

Frequently asked questions

Is the PPTX Importer Dev Guide skill free to use?

The skill is listed under the MIT licence, the same licence shown for the importer package on this page. The listing does not give a price, so check the licence file in the repository for the exact terms before you reuse the code.

What do I need to install the PPTX Importer skill?

You need Node.js, tsx and jszip, a sample .pptx file, and a checkout of the OpenMAIC repository. Install the skill by unzipping the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.

Can I use this skill to make or edit presentations?

No. The skill covers the converter's source code for turning .pptx files into JSON, not slide creation or editing. If you only want to build a deck, a general presentation tool or a different skill will fit better.

Does the skill work outside the OpenMAIC repository?

It is not designed for that. Many instructions reference OpenMAIC's specific files, scripts and folders such as DESIGN.md and iterate-prompt.md, so teams working elsewhere will find much of it does not apply.

Why does the agent say a file is high-risk?

The skill lists files such as groupSerializer.ts, shapeSerializer.ts and presets.ts as high-risk because they handle many cases at once. It recommends checking callers and comparing results on the same .pptx before changing them.

What should I do if the JSON diff shows unexpected changes?

Check whether you changed only the intended code path, then compare layoutElements and elements separately. The skill says to rerun with a new version after parsing changes, so old and new results are not mixed up.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill is a good fit for contributors to the OpenMAIC PPTX importer who need to fix conversion bugs and want an agent to follow the project's layering and commit rules. It is not useful if you only want to create or edit presentations, or if you work outside this repository, because most of its guidance depends on OpenMAIC's own files and scripts.

Download the skill