Convert MDX Dictionaries to macOS Dictionary with an Agent Skill

Sat, 08 Aug 2026 14:00:00 +0200

This post introduces MDX to macOS Dictionary, an open-source Agent Skill that turns local MDict .mdx dictionaries into searchable native macOS .dictionary bundles and ready-to-install DMG files.

MDX is a popular format for dictionary data, but macOS Dictionary.app cannot use an .mdx file directly. Converting one usually means preparing XML, compiling it with Apple’s Dictionary Development Kit, preserving styles, and packaging the result. This skill brings those steps into one guided workflow.

What the skill creates

Give a supported coding agent a local .mdx file or dictionary folder, and the skill can:

extract the dictionary entries from MDX;
convert them into Apple’s searchable dictionary format;
preserve companion CSS when it is available;
use a supplied cover or logo as the dictionary icon;
build a drag-to-install DMG installer;
install the finished dictionary in ~/Library/Dictionaries/ when requested.

The original MDX, CSS, JavaScript, and MDD files are left untouched. The result is a native dictionary that can be enabled in Dictionary.app and used from macOS features such as Spotlight and Look Up.

Why convert an MDX dictionary?

An MDX dictionary is convenient to share between compatible dictionary applications, but it is separate from the dictionary service built into macOS. A native .dictionary bundle fits more naturally into the Mac:

search entries from Dictionary.app;
use macOS’s Look Up feature on selected text;
access the dictionary from Spotlight where supported;
keep several dictionaries together in the system’s own dictionary folder;
install the result from a familiar DMG window.

This is useful for language learners, researchers, translators, and anyone who already owns a useful MDX dictionary and wants it to feel like part of macOS.

Install the Agent Skill

The skill is available on GitHub:

Jingyuan-Zheng/mdx-to-macos-dictionary-skill

If you use a compatible coding agent, install it with:

`1`	`npx skills add Jingyuan-Zheng/mdx-to-macos-dictionary-skill --agent codex`

After installation, ask the agent to convert a local .mdx file or folder. The skill checks the Mac’s prerequisites first and explains what needs attention before starting the conversion.

What the conversion looks like

The workflow is designed to keep the complicated parts together:

Select a local MDX dictionary and any companion CSS, JS, MDD, cover, or logo files.
Let the skill check the required macOS tools.
It extracts the entries and builds the native Apple Dictionary data.
It verifies the finished .dictionary bundle and creates a DMG installer.
The dictionary can then be copied into the user’s Dictionary folder and enabled in Dictionary.app.

You can request an output-only conversion if you do not want the skill to install anything. Otherwise, it installs the completed bundle in the current user’s ~/Library/Dictionaries/ folder. An existing dictionary with the same name is not replaced without approval.

What you need on the Mac

The project runs on macOS and uses Apple’s dictionary-building tools. Depending on the Mac and the source dictionary, it may require:

Python 3;
Xcode Command Line Tools;
Rosetta on Apple Silicon Macs;
Homebrew’s create-dmg tool.

The skill checks these requirements before processing a dictionary. It can also obtain the open-source components it needs, including mdict-utils, Apple’s Dictionary Development Kit, and DMG Maker, while keeping the conversion work inside a separate working directory.

From a finished dictionary to everyday use

After installation, open Dictionary.app, choose Dictionary → Settings (or Dictionary → Preferences on older macOS versions), and enable the new dictionary. You can change its position in the list to control which source appears first.

Once enabled, select a word in a supported Mac app and use Look Up, or open Dictionary.app and search normally. With a compatible trackpad, you can also tap the selected word with three fingers. On a Force Touch trackpad, you can press firmly instead, using Force Click. These gestures use the Look Up & data detectors option in System Settings → Trackpad; the available choice depends on your Mac and macOS version. Apple documents the gesture options in Look up words on Mac.

Two open-source dictionaries from my projects

This Skill is meant to make projects like these easier to package and share. I have already written about two Mac dictionaries built from open dictionary data:

The Little Dict Mac 版 — a large English dictionary converted from MDX into Apple’s native .dictionary format, with support for Dictionary.app and trackpad Look Up.
Ġabra Maltese Dictionary for macOS — an open-source Maltese dictionary with millions of inflected forms, packaged for Dictionary.app, Spotlight, and three-finger or Force Click Look Up.

They show the practical result of the conversion workflow: a dictionary is no longer just a file to open in a separate reader, but a source that can participate in the Mac’s built-in lookup experience.

How it works

The skill uses mdict-utils to read the MDX entries, converts them to the XML structure expected by Apple’s Dictionary Development Kit, and compiles that data into a .dictionary bundle. It validates the generated XML and checks that the bundle contains the indexes, metadata, stylesheet, and dictionary body before packaging it.

The project is MIT licensed and available on GitHub. For the DMG packaging step itself, see DMG Maker.

Apple Dictionary on Jingyuan