`minimax-docx` skill: false-negative env check, broken `run-script` reference, broken XSD validator, and SKILL.md inconsistencies

minimax-docx skill: false-negative env check, broken run-script reference, broken XSD validator, and SKILL.md inconsistencies

Summary

While using the minimax-docx skill to create a DOCX from scratch (Pipeline A), I hit several concrete issues that block the documented workflow. This is separate from #89 — that one covers build/OOM/path issues on Apple Silicon for ~/.mavis/.builtin-skills/docx/ with DocumentFormat.OpenXml 3.5.1 and net9.0. The skill I used lives at ~/.mavis/skills/minimax-docx/, depends on DocumentFormat.OpenXml 3.2.0, targets net8.0, and the issues below are different in nature.

Environment

• macOS Tahoe (Apple Silicon, arm64)
• .NET SDK 9.0.315 at ~/.dotnet/dotnet (not on PATH by default)
• pandoc 3.10, soffice 26.2.4, zip/unzip available
• Skill path: ~/.mavis/skills/minimax-docx/
• Workspace: standalone console app at ~/workspace/MavisCapabilities/

Issues

1. env_check.sh reports NOT READY even when everything works

After running the skill's setup.sh (which failed at brew install --cask dotnet-sdk due to missing sudo in a non-interactive shell) and manually adding ~/.dotnet to PATH, I ran:

PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" \
  bash ~/.mavis/skills/minimax-docx/scripts/env_check.sh

Output:

[OK]      dotnet         9.0.315 (>= 8.0)
[OK]      nuget          packages restored
[FAIL]    project        build failed
[OK]      pandoc, soffice, zip/unzip, locale
[WARN]    permissions    4 script(s) not executable
Status: NOT READY

But running dotnet build ~/.mavis/skills/minimax-docx/scripts/dotnet in the same shell succeeded with Сборка успешно завершена and zero errors. The check appears to invoke dotnet build with a path that the shell does not resolve correctly, or reads cached state from a previous failed run.

Suggested fix: print the actual command it ran and its stderr, and treat OK items as definitive — do not lump WARN into the final status.

2. SKILL.md references a run-script subcommand that does not exist

SKILL.md "Quick Start" section says:

File: scripts/dotnet/task.csx  (or a new .cs in a Console project)
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx

But Program.cs of MiniMaxAIDocx.Cli only registers these commands:

rootCommand.Add(CreateCommand.Create());
rootCommand.Add(EditContentCommand.Create());
rootCommand.Add(ApplyTemplateCommand.Create());
rootCommand.Add(ValidateCommand.Create());
rootCommand.Add(MergeRunsCommand.Create());
rootCommand.Add(FixOrderCommand.Create());
rootCommand.Add(AnalyzeCommand.Create());
rootCommand.Add(DiffCommand.Create());

There is no run-script. The MiniMaxAIDocx.Cli/Commands/ directory is empty. The real command implementations live in MiniMaxAIDocx.Core/Commands/. Following the documented "write C# directly" path leads to a dead end unless you create your own standalone console app — which is not what the example implies.

Suggested fix: either implement run-script in the CLI, or remove the example from SKILL.md and point users to the Core library / a separate template csproj.

3. validate --xsd wml-subset.xsd throws an unhandled exception

dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- \
  validate --input out.docx --xsd assets/xsd/wml-subset.xsd

Throws:

Unhandled exception: System.Xml.Schema.XmlSchemaValidationException:
The 'http://schemas.openxmlformats.org/officeDocument/2006/relationships:id'
attribute is not declared.
   at System.Xml.Schema.XmlSchemaValidator.SendValidationEvent(...)
   ...
   at MiniMaxAIDocx.Core.Validation.XsdValidator.ValidateXml(...)

This is a bug in wml-subset.xsd — it does not import the relationships namespace, but r:id attributes appear throughout OpenXML documents. The XSD gate-check is therefore unusable on every output the skill produces.

Suggested fix: add <xs:import namespace="http://schemas.openxmlformats.org/officeDocument/2006/relationships" schemaLocation="..."/> to assets/xsd/wml-subset.xsd, or ship a curated subset that explicitly declares the attributes used by the skill's emitters.

4. validate --business reports a benign orphaned relationship on every output

Every document I produce passes --business but emits:

WARNINGS (1):
  [Warning] Orphaned relationship: Id='Re3dcb71e2ebe46ea'
  is defined but never referenced
Validation: PASSED

The orphan is the FooterPart rel — mainPart.GetIdOfPart(footerPart) returns an id that the validator does not see as referenced from document.xml.rels (likely because the SDK registers the rel via AddNewPart first and only the explicit FooterReference in sectPr ties it back). The relationship is in fact correct and required for the page-number footer; the validator should not warn about it.

Suggested fix: either recognize footer/header rels as referenced-by-virtue-of-attachment, or have AestheticRecipeSamples.AddPageNumberFooter register the rel in a way the validator accepts.

5. setup.sh calls brew install --cask dotnet-sdk without checking sudo availability

setup.sh runs:

brew install --cask dotnet-sdk

which invokes sudo /usr/sbin/installer .... In a non-interactive shell (CI, agent runs, SSH without TTY), sudo prompts for a password and fails with:

sudo: a terminal is required to read the password; either use -S ...

The script then aborts and the user has to install dotnet by hand. Meanwhile, the script does not look in the obvious existing locations: ~/.dotnet/dotnet, /usr/local/share/dotnet, /opt/homebrew/Cellar/dotnet*.

Suggested fix: probe ~/.dotnet/dotnet / ~/.dotnet/sdk / /usr/local/share/dotnet / /opt/homebrew/Cellar/dotnet* first; only fall back to brew install if none exist; and if brew install is needed, document the manual install path (curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 9.0) instead.

6. docx_preview.sh (pandoc) silently drops paragraphs styled Title / Subtitle

I built a cover page with three paragraphs: Title ("Mavis"), Subtitle ("Capabilities of your personal assistant"), Caption ("Документ сгенерирован ..."). The XML in word/document.xml is correct and soffice --convert-to pdf renders it correctly. But scripts/docx_preview.sh shows only the Caption line — the title and subtitle are eaten by pandoc because it treats the first heading-level paragraph as the document title and pulls metadata from elsewhere.

This made me think the cover was broken until I checked the raw XML. For a skill whose name ends in docx and whose core use case is producing documents, this is misleading.

Suggested fix: use pandoc --standalone --nometadata or pandoc -t plain with --wrap=none so style-only paragraphs are preserved; or run unzip -p … word/document.xml | xmllint --format - for a faithful text dump.

7. Four scripts are not executable after setup.sh

env_check.sh consistently reports:

[WARN]    permissions    4 script(s) not executable

These are presumably setup.sh, env_check.sh, docx_preview.sh, doc_to_docx.sh. The skill never chmod +xs them after install, so on a fresh checkout every downstream invocation has to be prefixed with bash.

Suggested fix: add chmod +x to the install paths in setup.sh.

Reproduction

# After setup.sh has been run once (even partially):
cd ~/.mavis/skills/minimax-docx

# Issue 1: env check false-negative
PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" \
  bash scripts/env_check.sh
# → "Status: NOT READY" but build actually works

# Issue 2: missing run-script
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script foo.csx
# → error: No command was found for: run-script

# Issue 3: XSD validator crashes
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- \
  validate --input any.docx --xsd assets/xsd/wml-subset.xsd
# → XmlSchemaValidationException, not a clean failure

# Issue 6: preview swallows title
bash scripts/docx_preview.sh docs/with-cover.docx
# → cover content missing from output

Impact

• Issues 1–3 mean the documented "first run" path (setup.sh → env_check.sh → validate) does not work cleanly on a fresh macOS environment.
• Issue 2 blocks the "structural / write C# directly" path that SKILL.md recommends for non-trivial documents — exactly the path a user takes when producing anything beyond a one-pager.
• Issues 6–7 are smaller but erode trust in the skill on every run.

Notes

• Cross-references: #89 already covers the Apple Silicon build/permissions path issues at a more fundamental level — those apply here too. The seven items above are the additional issues I hit on top of #89.
• I produced a 6-page DOCX successfully (MinimalModern recipe, business-rules validation passed, PDF render verified visually), so the skill is functional despite the friction. The friction just makes the first session longer than it needs to be.

Start by reading SKILL.md, setup.sh, env_check.sh, and scripts/docx_preview.sh, then reproduce the documented commands. Inspect Program.cs, the Core validation entry points, and assets/xsd/wml-subset.xsd for the CLI and validator failures. Done means the documented setup, check, preview, and validate workflows complete without false failures, crashes, or misleading warnings.