mingli-master: a Zi Wei Dou Shu chart skill that does the maths in Python

What mingli-master actually does, and who it is for

Zi Wei Dou Shu is a Chinese astrological system that places stars into twelve palaces based on birth year, month, day and hour. Doing that placement by hand is tedious, and asking a language model to do it in its head is unreliable: the README is blunt that LLMs get it wrong, citing wrong five-element bureau assignment and reversed 禄权 ordering as typical failures. mingli-master exists to remove that class of error. It is an Agent Skills package, meaning it is a folder of instructions plus Python scripts that a compatible agent loads on demand, and the target user is someone who already works inside Claude Code, Codex CLI, Cursor or another runtime that speaks the Agent Skills protocol. The output is not a text answer but a self-contained HTML chart with a pattern dashboard, a luck-cycle section and an optional palmistry cross-check. If you want a web app with a login, this is not that. If you want a chart you can open in a browser and argue with, it is.

The split between Python placement and LLM prose

The pipeline has five stages, and the interesting boundary runs between the second and third. calculate_chart.py calls iztro-py to compute the twelve palaces, the four transformations and the major luck cycles. gezhi_rules.py then applies deterministic rules: it borrows stars into empty palaces with an energy coefficient of 0.7, dropping to 0.5 when the opposite palace carries a malefic, and it scores the chart against named configurations such as 杀破狼, 紫府武相, 机月同梁, 阳梁昌禄, 巨日同宫 and 马头带剑. It also scans for stacked transformations across the annual, decade and natal layers, which the README calls a temporal pressure audit, flagging a score of 2.5 or above as high risk and 1.5 or above as a warning. Only after all of that does the LLM write the reading. The README's framing is that rules are code and not free improvisation: the same chart yields the same judgement every time. That is a defensible design, and it is the reason the project is worth looking at rather than any claim about accuracy of interpretation. Interpretation remains a matter of taste; palace placement does not.

Installing mingli-master and generating a first chart

The dependency is iztro-py, a pure Python port of the JavaScript iztro library. The README gives this install line, which uses --user and --break-system-packages to work around externally managed Python environments:

python3 -m pip install iztro-py --user --break-system-packages

The project supports Python 3.8 and later. After that, the recommended path is to let your agent install the skill by URL, or to use the generic installer from vercel-labs:

npx skills add learnwithu/mingli-master

If you prefer to place the files yourself, clone into the skills directory of your runtime. Claude Code expects the folder under ~/.claude/skills/, and the README lists ~/.codex/skills/mingli-master/ for Codex CLI and ~/.cursor/skills/mingli-master/ for Cursor:

git clone https://github.com/learnwithu/mingli-master ~/.claude/skills/mingli-master/

Once installed, you do not call a script directly. You ask the agent in natural language. The README's own examples look like this:

帮我排个命盘，1991年8月15日，丑时，男
算算我的事业和财运
看看我 2027 年的运势（可指定任意流年）

The agent should invoke calculate_chart.py, run the rule engine, write the reading and drop an HTML file you can open. The V2 changelog notes that an empty reading.json still produces a complete skeleton chart, so a failed interpretation step does not leave you with nothing.

Where the design gets in the way

The hard dependency on iztro-py is the first constraint. If your agent runtime executes Python in a sandbox without network access, or pins an interpreter below 3.8, the placement step has nothing to call. The README offers a workaround for runtimes that cannot auto-load skills at all: paste the contents of SKILL.md into the conversation, since it is markdown with YAML frontmatter. That gets you the instructions but not the deterministic maths, which is the part that distinguishes this project from simply asking a model to read a chart. The second constraint is scope. The rule engine covers a fixed list of named configurations and a fixed set of transformation scans. A chart that does not match any named pattern still gets a dashboard, but the judgement layer has less to say, and the README does not describe how the engine handles configurations outside its list. Third, the interpretation layer is explicitly stylistic: the guide in references/interpretation_guide.md sets a tone, and tone is not verifiable. If you need a chart for record-keeping rather than reading, the LLM stage is the part you would want to skip, and the README does not document a flag for that.

How this compares with using iztro-py alone

The most direct alternative is to call iztro-py yourself and skip mingli-master entirely. iztro-py computes the palaces, the stars, the transformations and the luck cycles, which is the part that must be exact. What it does not do is decide whether a chart forms 杀破狼 across the three directions and four positions, borrow stars into an empty palace with a reduced coefficient, or scan three transformation layers for collisions. That judgement layer, plus the HTML template with its two themes, is what mingli-master adds. So the choice is not really between two chart calculators. It is between a library and a library plus a rules layer plus a presentation layer. If you are building your own application on top of iztro-py, the rules in gezhi_rules.py are the piece worth reading, and the README credits a community contributor named Rita as the main co-author of that system. If you just want a chart to look at, the skill wrapper saves you writing the template.

Maintenance, licence and the cost of upgrading

The last push to the repository was on 2026-08-15, which is when v2.0 was tagged. The README states plainly that the project is maintained out of interest and does not promise an update frequency, so treat version pinning as your own responsibility. The licence is MIT, which permits use and modification with the licence text retained; that is a permissive arrangement, but it says nothing about the accuracy or fitness of the astrological output, and nothing here is legal advice. The upgrade cost is concentrated in one place. V2 corrected three entries in the four-hua table: 甲, 乙 and 丙 had been mapped to the transformation-of-wealth stars instead of the transformation-of-adversity stars, and the correct natal mappings are 甲太阳, 乙太阴 and 丙廉贞. The changelog notes that this error shifts every pressure audit for the affected years, and that the fix was verified against 2024, 2025 and 2026 charts from the iztro engine. If you forked an earlier version, that table is the first thing to diff. The same release also fixed the annual stem-branch calculation, which had a hardcoded value, and added automatic Gregorian date completion when the input is a lunar date, without which the annual audit did not work.

Editorial conclusion

Adopt mingli-master if you already run a skills-compatible agent such as Claude Code, Codex CLI or Cursor, you are comfortable installing iztro-py yourself, and you want reproducible chart placement rather than an LLM improvising star positions. Do not adopt it if you need a hosted service, a stable API, or a promise about update cadence: the README states the project is maintained as a hobby and does not commit to a release schedule. Before relying on it, verify three things in your own environment: that iztro-py 0.5.0 or later is importable under the Python interpreter your agent uses, that a known birth date produces the same twelve-palace layout twice in a row, and that the four-hua table in your copy reflects the corrected 甲太阳 / 乙太阴 / 丙廉贞 mapping described in the V2 changelog.

Frequently asked questions

Official sources

1. Issues
2. learnwithu/mingli-master on GitHub
3. License: MIT
4. README
5. Releases